Module: Foam::Otel::Ingest

Defined in:
lib/foam/otel/ingest.rb,
lib/foam/otel/ingest_metric_reader.rb

Overview

Internal door-2 machinery. Nothing in here is public surface except the returned instances' processor/reader ducks.

Defined Under Namespace

Modules: DoubleClaim Classes: InertLogRecordProcessor, InertMetricReader, InertMetricStore, InertSpanProcessor, LogRecordProcessor, LogStampExporter, MetricReader, MetricStampExporter, SpanProcessor, SpanStampExporter, StampExporter

Constant Summary collapse

EXPORT_SUCCESS =

Duck-correct export result codes (== OpenTelemetry::SDK::*::Export:: SUCCESS/FAILURE in every signal's SDK). Spelled as integers so the INERT kill-switch instances never need the SDK loaded (rule 41 — a killed tap must not pay the SDK's load cost, let alone its threads).

0
EXPORT_FAILURE = 
1
ENTRY_NAMES = 
{
  traces: "Foam::Otel.create_ingest_span_processor",
  logs: "Foam::Otel.create_ingest_log_record_processor",
  metrics: "Foam::Otel.create_ingest_metric_reader",
}.freeze
KILL_WARNING =

W4 — kill switch.

"OTEL_SDK_DISABLED=true — this foam ingest entry is disabled by the operator " \
"kill switch and will send nothing. Unset the variable and restart to re-enable."

Class Method Summary collapse

Class Method Details

.build(signal, token:, environment:, redact_keys:, redact_pii_keys:, diagnostics:) ⇒ Object 



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/foam/otel/ingest.rb', line 109

def build(signal, token:, environment:, redact_keys:, redact_pii_keys:, diagnostics:)
  # (1) the operator kill switch — read once at construction, exactly
  # like init (rule 19 / fleet audit R13). Trimmed + case-insensitive
  # so the fleet's one emergency switch behaves the same across
  # languages (JS/Python already trim + downcase). Token deliberately
  # NOT validated on this path: the operator's off must never crash the
  # customer's boot.
  if Foam::Otel.send(:kill_switch_active?)
    Diagnostics.warn(KILL_WARNING)
    return inert_instance(signal)
  end

  # (2) construction validation — fail loudly AT BOOT, on the FDE's
  # machine (rules 10/23). Token is unconditionally validated after
  # the kill check (fleet ruling 2b — there is no `enabled`).
  entry = ENTRY_NAMES.fetch(signal)
  validate_present!(entry, :token, token)
  validate_present!(entry, :environment, environment)
  Foam::Otel.send(:warn_environment, environment)

  # (3) build. After validation NOTHING ever throws (rule 9): a broken
  # transitive dependency, an SDK load error, or an endpoint-resolution
  # failure degrades to a LOUD inert instance, never a crashed customer
  # boot. The heavy gems load here — the factory is the export path
  # (rule 41). Endpoint resolution is identical to init's: the pinned
  # fleet endpoint, or OTEL_EXPORTER_OTLP_ENDPOINT honored with the loud
  # warning; per-signal variants stay INERT + warned (GOTCHAS F2).
  begin
    Foam::Otel.send(:require_sdk!)
    endpoint = Foam::Otel.send(:resolve_endpoint)
    Foam::Otel.send(:warn_inert_per_signal_endpoints, endpoint)
    config = Foam::Otel.resolve_config(
      name: "", environment: environment.to_s, version: nil, enabled: true,
      redact_keys: redact_keys, redact_pii_keys: redact_pii_keys,
      ignored_outbound_hosts: [], diagnostics: diagnostics ? true : false,
      endpoint: endpoint
    )
    headers = { "Authorization" => "Bearer #{token}" }
    stamp = build_stamp(environment.to_s)
    ForkHooks.install!

    tap =
      case signal
      when :traces then build_span_tap(endpoint, headers, config, stamp)
      when :logs then build_log_tap(endpoint, headers, config, stamp)
      when :metrics then build_metric_reader(endpoint, headers, config, stamp)
      end
    narrate(config, "ingest #{signal} tap created -> #{endpoint} " \
                    "(environment: #{environment}, diagnostics: on)")
    tap
  rescue StandardError, SystemStackError => e
    Diagnostics.warn("#{entry}: internal setup failed (#{e.class}: #{e.message}) — this ingest entry is " \
                     "INERT (no export). Check the installed OpenTelemetry SDK/exporter gems against " \
                     "foam's supported range (README).")
    inert_instance(signal)
  end
end

.build_stamp(environment) ⇒ Object

The four stamp keys, exactly (fleet ruling 2d): merged onto FOAM'S COPY ONLY at export encoding time — the foreign resource object is never touched, and service.name/service.version/service.instance.id are never stamped (the data carries THEIR identity). Ruby's Resource.create folds in NO default resource (unlike the default/ process/telemetry_sdk class helpers), so the stamp injects no telemetry.sdk.* / service.name — pinned by the R12 test.



174
175
176
177
178
179
180
181
 
# File 'lib/foam/otel/ingest.rb', line 174

def build_stamp(environment)
  OpenTelemetry::SDK::Resources::Resource.create(
    "deployment.environment.name" => environment,
    "foam.ingest.tier" => "external",
    "telemetry.distro.name" => DISTRO_NAME,
    "telemetry.distro.version" => Foam::Otel::VERSION
  )
end

.double_claim_warning(signal) ⇒ Object

W3 — same-signal double-claim (warn once + KEEP FLOWING).



90
91
92
93
94
 
# File 'lib/foam/otel/ingest.rb', line 90

def self.double_claim_warning(signal)
  "wiring bug: init() already exports #{signal} to foam AND a foam ingest entry is attached " \
    "to another #{signal} pipeline. Both keep flowing (they are different pipelines; " \
    "foam.ingest.tier distinguishes them) — if unintended, remove one."
end

.echo_warning(host) ⇒ Object

W5 — echo filter (fleet audit R1: the structural third loop layer).



101
102
103
104
105
106
 
# File 'lib/foam/otel/ingest.rb', line 101

def self.echo_warning(host)
  "loop guard: this ingest entry received telemetry describing foam's own exports — your " \
    "HTTP instrumentation is tracing foam's export calls. Foam will not re-export its own " \
    "echo. REQUIRED fix: suppress host #{host} in YOUR http instrumentation " \
    "(README \"Door 2 — the required loop step\")."
end

.foam_resource?(resource) ⇒ Boolean

Structural self-ingest predicate (fleet ruling 2c): foam's own door-1 resource always carries telemetry.distro.name = "foam" (resource.rb); a foreign pipeline's resource never does. Identity- free, so it survives forks and copies. Fails safe to "foreign".

Returns:

  • (Boolean) 


187
188
189
190
191
192
193
 
# File 'lib/foam/otel/ingest.rb', line 187

def foam_resource?(resource)
  return false if resource.nil?

  resource.attribute_enumerator.to_h["telemetry.distro.name"] == DISTRO_NAME
rescue StandardError
  false
end

.narrate(config, message) ⇒ Object

Tap-scoped diagnostics (fleet ruling 2e): the gate is PER TAP, never the process-global diagnostics channel — and narration carries names, hosts and counts only, never attribute values, bodies, or the token (fleet audit R10).



199
200
201
 
# File 'lib/foam/otel/ingest.rb', line 199

def narrate(config, message)
  Kernel.warn("[foam] #{message}") if config.diagnostics
end

.self_ingest_warning(signal) ⇒ Object

---- the fleet warning templates (one fleet voice; text pinned by spec/ingest_spec.rb; [foam] prefix added by Diagnostics.warn) -------- W2 — self-ingest stand-down (fleet ruling 2c: warn once + STAND DOWN).



83
84
85
86
87
 
# File 'lib/foam/otel/ingest.rb', line 83

def self.self_ingest_warning(signal)
  "wiring bug: #{ENTRY_NAMES.fetch(signal)} is attached to foam's OWN pipeline — door 1 " \
    "already exports this data, so this tap is standing down (nothing is lost, nothing is " \
    "doubled). Ingest entries tap FOREIGN pipelines only; remove this line, or remove init()."
end