IF Commons GitHub

Telemetry

0001Draft

0001-telemetry · owner if · domain commons

The data model

FR-001checkpassing

otel MUST give the OpenTelemetry data model as types: a resource and an instrumentation scope with attributes; a span (trace id, span id, parent span id, trace state, name, kind internal | server | client | producer | consumer, start and end time in nanoseconds since the epoch as bigint, attributes, events, links, status unset | ok | error with a description for an error, and the counts of what was dropped); a log record (time, observed time, severity number 1 to 24 and its text, a body, attributes, trace and span id); and metrics (sum, gauge and histogram data points with their temporality). An attribute value MUST be a string, a boolean, an integer (bigint), a double (number), bytes, or a homogeneous array of one of those; a body MAY also be a map. No value of another type MUST be representable.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: the model's types (type-level tests) and the values an attribute can hold

Proved by: telemetry/suite/otel.test.ts, telemetry/suite/otlp.test.ts

Written in: telemetry/src/otel.ts

Tests: passed: suite/otel.test.ts attribute values and bodies admit only the types OpenTelemetry allows; passed: suite/otlp.test.ts a span is written with camel-case fields, hexadecimal ids, int64 as decimal strings, enums

Cited by: Telemetry, otel

FR-002checkpassing

A trace id (32) and a span id (16 lower-case hexadecimal digits) MUST be brands, made only by a validating function or from bytes a caller gives (traceIdFrom(random(16))), so that the kernel has no source of randomness of its own; an id of all zeros MUST be refused, as W3C Trace Context requires.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: ids from given bytes, zeros refused, brands kept apart

Proved by: telemetry/suite/otel.test.ts

Tests: passed: suite/otel.test.ts trace and span ids are made from bytes or text, and all zeros are refused

FR-003checkpassing

Telemetry MUST read and write W3C Trace Context (Level 2) traceparent and tracestate: version 00 exactly (lower-case hexadecimal, the lengths, ids not all zeros, the sampled flag), version ff refused, a later version read by its first four fields; tracestate of at most 32 members with keys and values of the grammar, a member that breaks it dropped rather than the header, written newest member first.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: traceparent and tracestate against the W3C examples, with property round trips

Proved by: telemetry/suite/otel.test.ts

Tests: passed: suite/otel.test.ts traceparent and tracestate read back what they write (round trip); passed: suite/otel.test.ts traceparent version 00 is read exactly, and its edge cases refused; passed: suite/otel.test.ts tracestate keeps valid members, drops the others, at most 32, newest first

FR-004checkpassing

Telemetry MUST encode an export request of traces, logs or metrics as OTLP/HTTP JSON as the OTLP specification defines it (camel-case field names, trace and span ids as hexadecimal, 64-bit integers as decimal strings, enumerations as integers, bytes as base64, resource and scope grouping) and decode such a request back to the same values, with the failure as a Result naming the path. Decoding MUST accept a 64-bit integer as a JSON number or a string, and MUST ignore a field it does not know. Encoding then decoding MUST give back what was encoded.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otlp.test.ts: OTLP JSON encode and decode, round-trip properties, int64 as strings, unknown fields ignored

Proved by: telemetry/suite/otlp.test.ts

Written in: telemetry/src/otlp.ts

Tests: passed: suite/otlp.test.ts logs encoded as OTLP/JSON and sent as text decode to what was encoded (round trip); passed: suite/otlp.test.ts metrics encoded as OTLP/JSON and sent as text decode to what was encoded (round trip); passed: suite/otlp.test.ts traces encoded as OTLP/JSON and sent as text decode to what was encoded (round trip); passed: suite/otlp.test.ts a span is written with camel-case fields, hexadecimal ids, int64 as decimal strings, enums; passed: suite/otlp.test.ts 64-bit integers are read from numbers or strings, enumerations from numbers or names, unkn and 3 more

Cited by: Telemetry, otlp

FR-005checkpassing

Telemetry MUST resolve the configuration from the OpenTelemetry environment variables alone, given as a record (the kernel reads no environment): OTEL_SDK_DISABLED, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES (percent-decoded), OTEL_EXPORTER_OTLP_ENDPOINT (with /v1/traces, /v1/logs and /v1/metrics appended) and its per-signal forms (used as given), OTEL_EXPORTER_OTLP_HEADERS and per-signal headers, OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_PROTOCOL (http/json; any other protocol is a warning and no export), OTEL_TRACES_SAMPLER and its argument, OTEL_BSP_*, OTEL_BLRP_*, OTEL_METRIC_EXPORT_INTERVAL, OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT, OTEL_ATTRIBUTE_COUNT_LIMIT, OTEL_SPAN_EVENT_COUNT_LIMIT, OTEL_SPAN_LINK_COUNT_LIMIT and OTEL_LOG_LEVEL. A value that is not valid MUST be a warning in the result and its default used, as the OpenTelemetry specification asks; no vendor's variable (OTEL_BUN) MUST be read.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: configuration from OTEL_* records, invalid values warned and defaulted

Proved by: telemetry/suite/otel.test.ts

Tests: passed: suite/otel.test.ts a value that is not valid is a warning and its default; a protocol but http/json disables ; passed: suite/otel.test.ts the configuration comes from the OTEL_ variables, with their defaults

FR-006checkpassing

Before any signal leaves the process it MUST be redacted: an attribute declared secret MUST never be written; the user information of a URL and the value of a query parameter whose name says it is a credential (token, key, secret, password, signature, code, and the like) MUST be replaced by REDACTED; a bearer token, a basic credential and a private key block found in a value MUST be replaced; and a process's arguments MUST be kept as the program and its option names alone, never their values. Text MUST be redacted by one function, the same for signals and for a message a harness sends (a mail, a notification), so that what may not be exported may not be mailed either: besides the above it MUST replace the value of a name=value or name: value pair, quoted or bare, in prose, JSON, YAML or an environment file, whose name ends in token, secret, password, passwd, passphrase, apikey, accesskey, secretkey, privatekey, credential or signature (case, -, _ and . ignored), the credential of an Authorization header with any scheme, the token formats that announce themselves (GitHub, GitLab, Slack, Google, Cloudflare, Anthropic, OpenAI, Stripe, npm, DigitalOcean, Docker, Hugging Face, Linear, Atlassian, JSON Web Tokens) and crypt password hashes ($6$, $y$, $2b$), and every exact secret of four characters or more that its caller names (the credential in use).

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: redaction of secret attributes, URLs, tokens, name=value pairs, provider token formats

Proved by: telemetry/suite/otel.test.ts, telemetry/suite/signals.test.ts

Written in: telemetry/tools/check.ts, telemetry/tools/pack.ts

Tests: passed: suite/otel.test.ts URLs lose their user information and the values of credential parameters; passed: suite/otel.test.ts a command line keeps the program and its option names alone; passed: suite/otel.test.ts an Authorization header keeps its scheme and loses its credential, whatever the scheme; passed: suite/otel.test.ts bearer and basic credentials, private keys and token shapes are replaced in text; passed: suite/otel.test.ts name=value pairs whose name is a secret's lose their values, in prose, JSON, YAML and envi and 3 more

FR-007checkpassing

The limits of FR-005 MUST be applied as the OpenTelemetry specification applies them: a string longer than the value limit cut to it, an attribute, event or link beyond the count dropped and counted in the span's dropped counts.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: attribute, event and link limits with dropped counts

Proved by: telemetry/suite/otel.test.ts, telemetry/suite/signals.test.ts

Tests: passed: suite/otel.test.ts values are cut to the length limit and attributes beyond the count dropped and counted; passed: suite/signals.test.ts limits and redaction apply to what a span records

FR-008checkpassing

Telemetry MUST sample by the samplers OpenTelemetry names (always_on, always_off, traceidratio decided by the trace id alone, and parentbased_* following the parent's sampled flag), so that every process of a trace samples it alike.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel.test.ts: the samplers, ratio decided by the trace id alone

Proved by: telemetry/suite/otel.test.ts

Tests: passed: suite/otel.test.ts samplers decide by the trace id and the parent alone

Cited by: Telemetry, otel

Typed signals

FR-009checkpassing

signals MUST give defineSignals, a registry where each kind of signal is declared once with what it is (a span, a log event, or a counter, up-down counter, gauge or histogram), its attributes and their types, a log event's severity, a metric's unit, and its presentation role (step, detail, progress, result, hint, warning, error, or none). Emitting a kind that is not declared, or an attribute of the wrong type or a missing required attribute, MUST NOT compile.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — signals.test.ts: defineSignals, with @ts-expect-error for undeclared kinds and wrong attributes

Proved by: telemetry/suite/signals.test.ts

Written in: telemetry/src/signals.ts

Tests: passed: suite/signals.test.ts a kind not declared, a wrong attribute type or a missing attribute does not compile; passed: suite/signals.test.ts a log record has its kind's severity unless the call gives one of its own, in the span or

Cited by: Telemetry, signals

FR-010checkpassing

span(kind, attributes, fn) MUST start a span as the child of the current one, run fn with a handle (attributes, events, child spans), and end it with the status its Result gives: ok for Ok, error with the error's description for Err; a function that throws MUST end its span with an exception event (exception.type, exception.message, exception.stacktrace) and error, and the exception MUST be thrown on. A span MUST end exactly once, and a span that is never ended MUST be ended as error by shutdown.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — signals.test.ts: span ends by its Result, exceptions recorded and rethrown, one end only

Proved by: telemetry/suite/signals.test.ts

Tests: passed: suite/signals.test.ts limits and redaction apply to what a span records; passed: suite/signals.test.ts a span tree is exact: the same ids, times, parents, statuses and order every run; passed: suite/signals.test.ts the parent comes from the context, a traceparent or the options, and sampling follows it; passed: suite/signals.test.ts shutdown ends an open span as error, a span ends once, and nothing is recorded after; passed: suite/signals.test.ts a function that throws ends its span with an exception event and error, and the exception and 1 more

FR-011checkpassing

The tracer, logger and meter MUST take their clock, their source of random bytes and their parent context from the caller, so that a test of a span tree is exact (the same ids, times and order every run).

Enforced (check): .github: cd commons/telemetry && bun test suite/ — signals.test.ts: an exact span tree from a fixed clock and random source

Proved by: telemetry/suite/signals.test.ts

Tests: passed: suite/signals.test.ts a span tree is exact: the same ids, times, parents, statuses and order every run; passed: suite/signals.test.ts the parent comes from the context, a traceparent or the options, and sampling follows it

FR-012checkpassing

A pipeline MUST hand every finished span, every log record and every metric collection to each of its processors in the order they were made: an in-memory processor (for tests and the renderer), a simple processor and a batch processor (at most maxQueueSize waiting, sent in batches of maxExportBatchSize at scheduleDelay, what does not fit dropped and counted). forceFlush and shutdown MUST resolve within the time they are given, whatever an exporter does.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — signals.test.ts: in-memory, simple and batch processors, drops counted, flush bounded

Proved by: telemetry/suite/signals.test.ts

Tests: passed: suite/signals.test.ts shutdown ends an open span as error, a span ends once, and nothing is recorded after; passed: suite/signals.test.ts a batch processor sends full batches, then what waits after its delay, and drops what does; passed: suite/signals.test.ts a simple processor exports each signal in order, and counts what failed, never throwing; passed: suite/signals.test.ts forceFlush and shutdown end within their time whatever the exporter does

FR-013checkpassing

Metrics MUST be aggregated as OpenTelemetry defines them, with cumulative temporality: a counter that refuses a negative increment, an up-down counter, a gauge keeping the last value, and a histogram with OpenTelemetry's default explicit bucket bounds or bounds the kind declares, keeping count, sum, minimum and maximum; one series for each distinct set of attributes.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — signals.test.ts: counter, up-down, gauge and histogram aggregation

Proved by: telemetry/suite/signals.test.ts

Tests: passed: suite/signals.test.ts metrics are cumulative: counters refuse a negative increment, gauges keep the last value,

Cited by: Telemetry, signals

The host

FR-014checkpassing

host/otel MUST export over OTLP/HTTP JSON with fetch: POST to the endpoint with content-type: application/json and the configured headers, a retry on 429, 502, 503 and 504 after the server's Retry-After or a growing wait, within the export timeout, a partial success read and counted. An export MUST never throw to its caller nor fail the command that made the signals, and a failure MUST become one warning signal, said once per run.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel-host.test.ts: export to a local receiver, retries on 503 with Retry-After, never throws

Proved by: telemetry/suite/otel-host.test.ts

Written in: telemetry/src/host/otel.ts

Tests: passed: suite/otel-host.test.ts an export is a POST of OTLP JSON with the configured headers, and the receiver gets the sa; passed: suite/otel-host.test.ts 503 with Retry-After: 1 is sent again after a second; 429, 502 and 504 without it after gr; passed: suite/otel-host.test.ts a partial success is read and counted as rejected by the processor; passed: suite/otel-host.test.ts a pipeline whose exports fail says one warning for the run, as a warning signal too; passed: suite/otel-host.test.ts a real 503 then 200 from a server on 127.0.0.1 is retried and succeeds and 3 more

Cited by: host/otel, Telemetry

FR-015checkpassing

Where no endpoint is configured the runtime MUST probe http://localhost:4318 for at most 150 milliseconds before the first export and export nothing when nothing answers; at exit the runtime MUST wait at most one second for what is left to be sent, then give up and say so.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel-host.test.ts: the probe gives up within 150 ms, the exit wait within a second

Proved by: telemetry/suite/otel-host.test.ts

Tests: passed: suite/otel-host.test.ts a collector that never answers: the wait at exit is at most a second, then it gives up and; passed: suite/otel-host.test.ts with no endpoint and a collector answering at the default, the export goes there; passed: suite/otel-host.test.ts with no endpoint and nothing answering, the probe gives up within 150 ms, nothing is sent,

FR-016checkpassing

Telemetry's host MUST keep a journal when asked: every export request also written as one line of OTLP JSON to a file, which is rotated when it passes its size limit, keeping a given number of older files, and, where a maximum age is given, a journal file last written longer ago than that removed when the journal starts and at each rotation, so that a journal keeps, say, 30 days; a journal is what a run recorded even with no collector.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel-host.test.ts: the journal writes OTLP lines, rotates and removes files past their age

Proved by: telemetry/suite/otel-host.test.ts

Tests: passed: suite/otel-host.test.ts a journal with a maximum age removes the files last written before it, when it starts and ; passed: suite/otel-host.test.ts a run keeps a journal of its spans, logs and metrics even with no collector; passed: suite/otel-host.test.ts the journal writes one OTLP JSON line per export and rotates past its size, keeping the gi

FR-017checkpassing

The current span MUST be carried implicitly across await by AsyncLocalStorage (node:async_hooks), and a process MUST take its parent from the TRACEPARENT and TRACESTATE environment variables when they are set, as the OpenTelemetry specification for environment carriers defines.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel-host.test.ts: the current span across await, and the parent from TRACEPARENT

Proved by: telemetry/suite/otel-host.test.ts

Tests: passed: suite/otel-host.test.ts a pipeline hands a span or a log record made elsewhere to every processor, with its source; passed: suite/otel-host.test.ts AsyncLocalStorage carries the current span across await, each async path its own; passed: suite/otel-host.test.ts the clock is nanoseconds since the epoch and never goes back; passed: suite/otel-host.test.ts the parent comes from TRACEPARENT and TRACESTATE, and spans after an await are children of; passed: suite/otel-host.test.ts proc.run is a client span with the command's shape and exit code, and the program gets its

FR-018checkpassing

The runtime's own modules (system, the HTTP client and serve) MUST make signals: proc.run a client span for each program run (process.executable.name, the option names of FR-006, process.exit.code) that gives the program TRACEPARENT and TRACESTATE; the HTTP client a client span (http.request.method, url.full redacted, server.address, http.response.status_code) that sends traceparent; and serve a server span whose parent is the request's traceparent. These MUST be no-ops when no pipeline is installed.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — process-span.test.ts: proc spans, with traceparent passed on; the http client and serve spans are proved by commons/ts tests/runtime/otel-net.test.ts until the library net is lifted

Proved by: telemetry/suite/otel-host.test.ts

Tests: passed: suite/otel-host.test.ts the resource names the service and the runtime, never the host or a person; passed: suite/otel-host.test.ts proc.run is a client span with the command's shape and exit code, and the program gets its

Cited by: Net

FR-019checkpassing

Telemetry's host MUST give an OTLP/HTTP JSON receiver over serve (/v1/traces, /v1/logs, /v1/metrics): a request decoded by FR-004 handed to a sink, 415 for any content type but JSON, 400 with the path for a request that does not decode, and the success body OTLP defines.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — otel-host.test.ts: the receiver decodes, refuses protobuf (415) and bad JSON (400)

Proved by: telemetry/suite/otel-host.test.ts

Tests: passed: suite/otel-host.test.ts an export is a POST of OTLP JSON with the configured headers, and the receiver gets the sa; passed: suite/otel-host.test.ts the receiver: 415 for protobuf, 400 with the path, 404, 405, and OTLP's success body (gzip

Cited by: host/otel, Telemetry, Net

FR-020gatepartly run

CI MUST send the suite's OTLP to a pinned OpenTelemetry Collector (its version and SHA-256 in commons' pins) whose file exporter writes what it received, and the test MUST find every span, log record and metric sent, with the same ids, attributes and values.

Enforced (gate): .github: .github/workflows/ifc-typescript.auto.yml — the otel-conformance job runs suite/otel-conformance.test.ts against the pinned OpenTelemetry Collector and compares its file export

Proved by: telemetry/suite/otel-conformance.test.ts

Tests: skipped: suite/otel-conformance.test.ts the OpenTelemetry Collector receives every span, log record and metric sent, with the same

The console

FR-021checkpassing

render MUST be a pure reducer from a state, a signal and the time to a new state and the frames to write, in five modes: attended (a live region of the spans in progress, nested by parent, redrawn in place), plain (lines appended, no escape sequence, for a log or a pipe), quiet (only warnings, errors and results), silent (nothing) and json (one OTLP JSON log record per line). Only a signal whose kind has a presentation role other than none MUST be shown.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — render.test.ts: the reducer in each mode, snapshots through the terminal emulator

Proved by: telemetry/suite/render.test.ts

Written in: telemetry/src/render.ts

Tests: passed: suite/render.test.ts attended: the live region nested by parent, with elapsed time and progress, redrawn in pla; passed: suite/render.test.ts property: plain never writes an escape byte; attended never wraps, and ends showing plain'; passed: suite/render.test.ts json: one OTLP JSON logs request of one record per line, for each shown signal; passed: suite/render.test.ts only a kind whose role is not none is shown, in every mode; passed: suite/render.test.ts plain: the final lines appended, nothing in progress, no escape sequence and 2 more

Cited by: Telemetry, render

FR-022checkpassing

A line MUST be cut to the terminal's width by display width (a wide character or emoji counts two columns, an escape sequence none), never wrapped inside the live region; a span in progress MUST show its elapsed time, and its progress where it has one.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — render.test.ts: lines cut by display width, elapsed time and progress

Proved by: telemetry/suite/render.test.ts

Tests: passed: suite/render.test.ts attended: the live region nested by parent, with elapsed time and progress, redrawn in pla; passed: suite/render.test.ts property: plain never writes an escape byte; attended never wraps, and ends showing plain'; passed: suite/render.test.ts a crowded live region keeps to its height and counts the rest; passed: suite/render.test.ts a line is cut to the width by display width, never wrapped; elapsed time and progress as a; passed: suite/render.test.ts marks fall back to ASCII without emoji, and colour is written only where the look allows i

FR-023checkpassing

Where an export failed or no collector answered, the console MUST say so once, dimmed, at the end of the run, and nowhere else.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — render.test.ts: the export warning said once, dimmed, at the end

Proved by: telemetry/suite/render.test.ts

Tests: passed: suite/render.test.ts an export warning is said once, dimmed, at the end of the run, and nowhere else

Cited by: Telemetry, render

FR-024checkpassing

host/console MUST be the only code of IFC TypeScript that writes for a person to standard output or standard error: it subscribes to the pipeline, chooses the mode from the terminal and the environment (attended at a terminal, plain otherwise, json where asked), writes the frames, and on an uncaught exception or unhandled rejection records an error log record with the exception, renders it, flushes, and exits with status 1.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — console.test.ts: the console is the only writer, its modes, uncaught errors recorded and rendered

Proved by: telemetry/suite/console.test.ts

Written in: telemetry/src/host/console.ts

Tests: passed: suite/console.test.ts IFC_CONSOLE=json: one OTLP JSON logs request per line on standard output; passed: suite/console.test.ts a telemetry whose registry declares the uncaught kind is what installUncaught takes; the m; passed: suite/console.test.ts an uncaught exception or an unhandled rejection is rendered as an error record, and the pr; passed: suite/console.test.ts piped, the console writes plain lines with no escape byte, and says once at the end where ; passed: suite/console.test.ts the console is the one writer for a person and stdio the one for a program: no other file

Cited by: host/console, Telemetry

FR-025checkpassing

What a person reads MUST say whether anything is wrong, and only then alarm: ❌ (failed) and ⚠️ (warning) are problems; ⏳ (pending) is something not set up yet, expected until someone does it; ⚡ (action) is a step that is the person's to take (send a change, back up, approve), with the command, where nothing is wrong. A pending or an action is never counted as a warning or a failure, never fails a run, and a signal kind declares it with the roles pending and action, which the renderer marks ⏳ and ⚡. Every command line of Intellectual Frontiers closes a run the same way: the problems under "Needs attention", the actions under "Your move", the pending under "Not set up yet", in that order.

Enforced (check): .github: cd commons/telemetry && bun test suite/ — render.test.ts: the pending and action marks and roles; a pending or an action is no warning

Proved by: telemetry/suite/render.test.ts

Tests: passed: suite/render.test.ts pending is ⏳ and an action is ⚡: neither a warning nor an error; quiet keeps the action

The package

FR-026checkno test run

Telemetry MUST depend on Core, Formats, Terminal and System alone, MUST have a pure entry that names no host global and reads no environment (otel, otlp, signals, render) and a host entry that holds the exporter, the pipeline and the console, and MUST be published as compiled modules with their declarations as @intellectual-frontiers/telemetry (commons 0032-libraries-by-concern FR-005, FR-013), importable by Node 26 and by Bun from node_modules, with @types/node as a peer.

Enforced (check): .github: cd commons/telemetry && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball and runs every entry on Node 26 and Bun and type-checks a consumer

Written in: telemetry/about.ts, telemetry/library.ts, telemetry/src/host/mod.ts, telemetry/src/mod.ts

Acceptance scenarios

  1. Given a traceparent with a trace id of zeros, When it is read, Then it is refused and a new trace is started, per FR-002 and FR-003.
  2. Given a span whose function returns err("not found"), When it ends, Then its status is error with not found, per FR-010.
  3. Given a collector that answers 503 with Retry-After: 1 once, When a batch is exported, Then the request is sent again and nothing throws, per FR-014.
  4. Given a span tree from a fixed clock and fixed random bytes, When it is exported as OTLP JSON and read back, Then every span, log record and metric is found with the same ids and values, per FR-004 and FR-020.
  5. Given output piped to a file, When the console writes, Then there is no escape sequence in it, per FR-021 and FR-024.
  6. Given the packed package installed under node_modules, When Node 26 and Bun import each entry, Then both give the same decoded request, per FR-026.

Out of scope

  • OTLP over gRPC or protobuf: JSON over HTTP is what a collector accepts and what the kernel can write with no dependency; protobuf may follow if a collector without JSON must be served.
  • Profiles, exemplars and exponential histograms.
  • What erga and stolos declare as their signals: each harness's own registry, made with defineSignals.

Edge cases

  • traceparent: 00-00000000000000000000000000000000-00f067aa0ba902b7-01: refused (a trace id of zeros), and a new trace started, per FR-002 and FR-003.
  • traceparent with upper-case hexadecimal: refused, per FR-003.
  • tracestate with 40 members: the first 32 kept, per FR-003.
  • An integer attribute of 2^63 - 1: written as the string "9223372036854775807", never rounded, per FR-001 and FR-004.
  • A JSON number 1 where OTLP has a 64-bit integer: read as 1n, per FR-004.
  • OTEL_EXPORTER_OTLP_PROTOCOL=grpc: a warning, and nothing exported, per FR-005.
  • OTEL_TRACES_SAMPLER_ARG=2: a warning, and the ratio 1, per FR-005.
  • OTEL_RESOURCE_ATTRIBUTES=team=a%2Cb: the value a,b, per FR-005.
  • https://user:pw@host/x?token=abc&page=2: written https://REDACTED:REDACTED@host/x?token=REDACTED&page=2, per FR-006.
  • password: hunter22, {"client_secret":"abc def"}, AWS_SECRET_ACCESS_KEY=... and Authorization: token ghp_... in a log line or a mail: each value written REDACTED, its name kept, per FR-006.
  • max_tokens=1024, token_type: bearer and status code=200: kept, as their names do not end in a credential's, per FR-006.
  • cfut_ followed by forty characters (a Cloudflare user API token) in an error message: REDACTED, per FR-006.
  • A journal of 30 days whose <path>.2 was last written 31 days ago: removed when the journal starts, and its newer files kept, per FR-016.
  • git clone --depth 1 https://... run by proc.run: the span says git and --depth, nothing else, per FR-006 and FR-018.
  • An attribute declared as an integer given a string: does not compile, per FR-009.
  • A function that returns err("not found"): its span ends error with not found, per FR-010.
  • A collector that answers 503 with Retry-After: 1 once: the request is sent again, per FR-014.
  • A collector that never answers: the command's exit status is its own, the wait at exit is at most a second, and one dim line says the signals were not sent, per FR-014, FR-015 and FR-023.
  • A batch queue that is full: the new span is dropped and counted, never blocking the caller, per FR-012.
  • A child process run with TRACEPARENT set: its spans are children of the span that ran it, per FR-017 and FR-018.
  • A line holding ✅ 测试 at a width of 6: cut after 测, per FR-022.
  • Output piped to a file: no escape sequence in it, per FR-021 and FR-023.
  • A protobuf body sent to the receiver: 415, per FR-019.

Assumptions

  • The OTLP/JSON encoding and the environment variables are stable in the OpenTelemetry specification; the semantic conventions used (process.*, http.*, url.*, server.*, exception.*) are the stable ones, and where a convention is still in development its name is used as it stands.
  • An OpenTelemetry Collector of the contrib distribution has a file exporter and an OTLP/HTTP receiver that accepts JSON.

Open questions

OQ-1open question

Whether to add protobuf once a collector without JSON must be reached.

OQ-2open question

Whether the browser needs an exporter of its own (navigator.sendBeacon) or the fetch one is enough.

Key entities

  • Signal - a span, a log record or a metric, as OpenTelemetry defines it.
  • Signal kind - a declared kind of signal with its attributes and its presentation role.
  • Pipeline - the processors every signal of a process goes to.
  • Rendering - what the console writes, made from signals by a pure reducer.
  • Journal - the file of export requests a run wrote.

Success criteria

SC-001success criterion

A harness built on IFC TypeScript sends its traces, logs and metrics to any OpenTelemetry Collector with no package and no runtime flag.

SC-002success criterion

Every line a harness shows a person is found, as a signal, in its journal or its collector.

SC-003success criterion

The same run gives the same trace on Bun and Node.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

host/console, host/otel, Telemetry, otel, otlp, render, signals, Net

Titles, headings, exports, tables, columns and requirements. Esc closes.