IF Commons GitHub

Signals

0006Draft

0006-signals · owner if · domain commons

The data model (kernel)

FR-001reviewno test run

The signals MUST take the OpenTelemetry data model from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-001), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-001

FR-002reviewno test run

The signals MUST take trace and span ids from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-002), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-002

FR-003reviewno test run

The signals MUST take W3C Trace Context from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-003), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-003

FR-004reviewno test run

The signals MUST take OTLP/HTTP JSON from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-004), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-004

Cited by: test-report, Quality evidence

FR-005reviewno test run

The signals MUST take the configuration from the OpenTelemetry environment variables from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-005), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-005

FR-006reviewno test run

The signals MUST take the redaction of what leaves the process from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-006), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-006

Cited by: pure/record, trust/audience, Quality evidence, Test, Headless governance

FR-007reviewno test run

The signals MUST take the limits of an attribute, an event and a link from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-007), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-007

FR-008reviewno test run

The signals MUST take the samplers from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-008), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-008

Cited by: meaning-registers

Typed signals (kernel)

FR-009reviewno test run

The signals MUST take typed signals from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-009), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-009

FR-010reviewno test run

The signals MUST take spans that end by their Result from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-010), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-010

FR-011reviewno test run

The signals MUST take the clock, the random bytes and the parent of a signal from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-011), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-011

FR-012reviewno test run

The signals MUST take the processors of a pipeline from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-012), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-012

FR-013reviewno test run

The signals MUST take the aggregation of metrics from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-013), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-013

Cited by: pure/objectives, Quality evidence, Test evidence

The host (runtime)

FR-014reviewno test run

The signals MUST take the OTLP/HTTP JSON exporter from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-014), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-014

FR-015reviewno test run

The signals MUST take the probe and the wait at exit from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-015), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-015

FR-016reviewno test run

The signals MUST take the journal from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-016), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-016

FR-017reviewno test run

The signals MUST take the current span across await from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-017), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-017

Cited by: Test

FR-018reviewno test run

The signals MUST take the runtime's own signals from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-018), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-018

Cited by: proc

FR-019reviewno test run

The signals MUST take the OTLP/HTTP JSON receiver from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-019), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-019

FR-020reviewno test run

The signals MUST take the conformance with the OpenTelemetry Collector from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-020), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-020

The console (kernel and runtime)

FR-021reviewno test run

The signals MUST take the renderer of the console from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-021), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-021

FR-022reviewno test run

The kernel MUST take the palette of colour roles and marks from the library terminal (@intellectual-frontiers/terminal, terminal 0001-terminal FR-003), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library terminal: terminal 0001-terminal FR-003

Cited by: Terminal, palette, Terminal, Headless command line

FR-023reviewno test run

The signals MUST take the cutting of a line to the terminal's width from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-022), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-022

Cited by: Terminal, width, Terminal

FR-024reviewno test run

The signals MUST take the said-once warning of a failed export from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-023), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-023

FR-025reviewno test run

The kernel MUST take the terminal emulator for snapshot tests from the library terminal (@intellectual-frontiers/terminal, terminal 0001-terminal FR-005), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT hold it itself.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library terminal: terminal 0001-terminal FR-005

Cited by: Terminal, vt, Terminal

FR-026reviewno test run

The signals MUST take the console as the one writer for a person from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-024), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-024

Cited by: stdio

FR-027reviewno test run

The signals MUST take what a person reads and when it alarms from the library telemetry (@intellectual-frontiers/telemetry, telemetry FR-025), where it is specified and proved (0032-libraries-by-concern FR-010), and MUST NOT specify it here.

Enforced (review): 0032-libraries-by-concern FR-010 — kept by the library telemetry: 0001-telemetry FR-025

Cited by: Headless command line

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-024.
  • 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-023.
  • Output piped to a file: no escape sequence in it, per FR-021 and FR-026.
  • 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

pure/objectives, pure/record, test-report, trust/audience, proc, stdio, Terminal, palette, vt, width, Quality evidence, Telemetry, Terminal, Test, Headless governance, Headless command line, GRC engineering, Test evidence, meaning-registers

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