Summary
v2 has no observability document. The core says only that a host SHOULD export openwop. spans (conformance.md), the gen_ai. mapping lives in the frozen v1 tree, and the v2 observability metadata describes itself as "optional v1 hints". No v2 host has a witnessed OTLP export. This RFC adds a core family, telemetry, whose presence is the claim that the host exports OTLP traces. When advertised, the host MUST emit one span per run and per node execution under fixed names and attributes, continue an inbound traceparent, and keep secrets out of every span. An optional facet, genAiSemconv, names the OTel GenAI semantic-conventions version the host maps model calls to. The suite's existing OTLP collector witnesses each rule.
Motivation
- Finding P-020 (August 2026 assessment, still open on 13 November): "v2 has no observability document; the
gen_ai.*mapping exists only in the frozen v1 tree." - The v2 export path is unwitnessed (
docs/KNOWN-LIMITS.md). The OTel span, export and canary legs (otel-emission,otel-trace-propagation,secret-leakage-otel-attribute,otel-collector-canary-inspection) are registered at major 1 only. At major 2 the trace-context rows on the production host's bundle areinapplicable. - A metadata key cannot carry a claim.
observabilityiskind: metadatainspec/v2/declaration.json. Metadata has no witness class and binds nothing, so a host can advertise it and emit nothing. A family record is a claim, and a claim binds its rules (capabilities.md§2,security-defaults.md§"The rule"). - Operators expect OTLP. Every durable-execution product in the rubric's benchmark set exports OpenTelemetry. A protocol that standardises execution but not its trace shape leaves cross-host debugging to each vendor.
Proposal
§A The family
telemetry is a core family (anchor: core), homed in a new core document spec/v2/core/telemetry.md. Its record is a v2 capability record (status, since, witness, …) with two facets (spec/v2/facets/telemetry.schema.json):
otlp— REQUIRED.{ protocols: [...] }, a non-empty array of the OTLP transports the host can export over:"http/protobuf","http/json","grpc".genAiSemconv— OPTIONAL. A string naming the OpenTelemetry GenAI semantic-conventions version the host maps model calls to (for example"1.37.0"), pattern^\d+\.\d+\.\d+$.
§B Export
A host advertising telemetry:
- MUST export OTLP traces to the endpoint the operator configures through the standard OpenTelemetry exporter configuration (
OTEL_EXPORTER_OTLP_ENDPOINT,OTEL_EXPORTER_OTLP_PROTOCOL, and the per-signal variants), over a transport it lists inotlp.protocols. - MUST emit, for every run, a span named
openwop.run(oropenwop.run.<phase>) carryingopenwop.run_idandopenwop.workflow_id. - MUST emit, for every node execution, a span named
openwop.node.<typeId>carryingopenwop.run_id,openwop.node_id,openwop.node_typeandopenwop.node_attempt(a non-negative integer, the zero-based retry counter). - MUST, when
createRuncarries a valid W3Ctraceparent, emit that run's spans in the inbound trace (sametraceId). - SHOULD export the run and node metrics the v1 vocabulary names. Metrics are not part of the claim.
Names and attributes are the ones spec/v1/observability.md already defines, so a host that met v1's vocabulary changes nothing. A host MAY emit further spans and attributes outside openwop.*.
§C The GenAI mapping
A host advertising telemetry.genAiSemconv MUST put, on the span for each model call a node makes, the gen_ai.* attributes that version defines for a chat or completion call. At minimum these are gen_ai.operation.name, the provider attribute that version names (gen_ai.provider.name, or gen_ai.system in versions before it), gen_ai.request.model, gen_ai.usage.input_tokens and gen_ai.usage.output_tokens. A host that does not advertise the facet makes no GenAI claim. The mapping is optional because the conventions are still marked experimental upstream: core correctness never depends on them.
§D Proposed core text
spec/v2/core/telemetry.md, the family's normative home (the integrator lands this text verbatim or tighter):
# Telemetry
> **Status: Experimental.**
> **Normative home:** `telemetry`.
## Why this exists
An operator debugging a run needs its trace in their own OpenTelemetry backend. The `telemetry` family is the claim that a host exports one.
## Export
A host advertising `telemetry` MUST export OTLP traces to the endpoint the operator configures with the standard `OTEL_EXPORTER_OTLP_*` settings, over a transport listed in `otlp.protocols`.
- Every run MUST produce a span named `openwop.run` carrying `openwop.run_id` and `openwop.workflow_id`.
- Every node execution MUST produce a span named `openwop.node.<typeId>` carrying `openwop.run_id`, `openwop.node_id`, `openwop.node_type` and `openwop.node_attempt`.
- A run created with a valid W3C `traceparent` MUST emit its spans in that trace.
- A span name, attribute, event or resource attribute MUST NOT carry credential material or a resolved secret ([host-services.md](host-services.md) §`secrets`).
- Metrics SHOULD be exported; they are not part of the claim.
## GenAI mapping
With `genAiSemconv`, each model-call span MUST carry the `gen_ai.*` attributes that version defines for a chat call: operation name, provider, request model and input and output token usage.
*Sources: RFC 0262.*
The text is about 175 words. Homing a new core family raises the core budget's cap by 200 words (scripts/check-core-budget.mjs), so it pays for itself.
§E Secrets in telemetry
A host advertising telemetry MUST NOT put credential material or a resolved secret in any span name, span attribute, span event, link or resource attribute it exports. This is the export-side instance of host-services.md §secrets ("Raw key material MUST NOT appear in any … trace"), restated here only as the falsifiable obligation the family binds. It gets a protocol-tier row in SECURITY/invariants.yaml (telemetry-export-no-secret), whose test is the leg below.
§F The observability metadata
observability stays a metadata key with its current shape. Its description changes to say that the telemetry family is the v2 claim and that observability carries no obligation. Whether to delete it at v3 is Unresolved question 1.
Compatibility
- Additive. A new optional core family and a new optional facet file. No existing field, event, endpoint, error code or MUST changes. A closed v2 discovery root gains one optional property,
telemetry(COMPATIBILITY.md§2.4). - Hosts that emit v1 spans already meet §B.2–§B.3 by name and attribute, so advertising the family costs them nothing beyond §B.4 and §E.
- Consumers that validate discovery against an older pinned v2 schema reject a document carrying
telemetry; consumers pin, as with every additive family. - Replay and fork. No event-log shape changes. A replay fork is a new run and emits its own spans; this RFC says nothing about the trace a fork belongs to (Unresolved question 3).
Security considerations
- Secrets in spans are the main risk, and §E makes the rule falsifiable on the export path rather than the host's own scrape seam.
- Tenant data in a shared collector. Run and workflow ids are tenant-bound (
identity.md), and an operator's collector may serve several tenants. This RFC does not addopenwop.tenant_idto the MUST set (v1 has it as a MAY); an operator that needs tenant separation routes by resource attributes it controls. - Inbound
traceparentis caller-controlled. Continuing a trace grants no authority. A host MAY start a new trace for a caller it does not trust and link the inbound context instead; §B.4 then fails for that caller, so such a host does not advertise the family to it. This is Unresolved question 2.
Conformance
conformance/src/scenarios/v2-telemetry-export.test.ts, target major 2. Every host leg is gated on the telemetry family record and on the suite's OTLP collector (OPENWOP_OTEL_COLLECTOR=true, with the host's exporter pointed at it). It is a host-callback scenario (REQUIRES_HOST_CALLBACK): a host in a separate network namespace records blocked, not a failure.
0262.shape— server-free: the facet schema accepts{otlp:{protocols:["http/protobuf"]}}and a semvergenAiSemconv, and refuses an emptyprotocols, an unknown transport and a non-semver version.0262.run-span— aconformance-nooprun produces anopenwop.runspan carrying itsopenwop.run_idandopenwop.workflow_id.0262.node-span— the same run produces anopenwop.node.<typeId>span carryingopenwop.node_id,openwop.node_typeand a non-negativeopenwop.node_attempt.0262.traceparent-continued— a run created with a suite-mintedtraceparentemits its spans under thattraceId.0262.no-secret-in-spans— after anopenwop-smoke-byok-roundtriprun (gated on that fixture), no captured span name, attribute or resource attribute carries the store canary. The scan uses the surfaced digest detector (lib/secret-scan.ts) and, when the operator supplies it, the plaintext. A run that captured no span for the run recordsblocked: an empty export cannot pass a leak check.0262.gen-ai-attributes— gated ongenAiSemconvand theconformance-callai-attempt-accountingfixture. The model-call span carriesgen_ai.operation.name, a provider attribute,gen_ai.request.modeland both usage-token attributes.
Every host leg records blocked, not a pass, when the collector captured no span for the run, so a host that advertises the family and exports nothing fails to certify.
Falsifiability — one row per normative requirement
| Requirement | Observable — what an outside party sees | Who can cause the condition | Verdict |
|---|---|---|---|
| §A facet shape | schema validation of the telemetry facet — openwop.requirement.0262.shape | the suite, unaided (server-free) | witnessable — unaided |
| §B.1–§B.2 run span exported | an openwop.run span with the run's id at the suite's collector — openwop.requirement.0262.run-span | the suite (one conformance-noop run) | witnessable — gated (family + collector) |
| §B.3 node span exported | an openwop.node.<typeId> span with the four attributes — openwop.requirement.0262.node-span | the suite (the same run) | witnessable — gated (family + collector) |
| §B.4 inbound trace continued | the run's spans carry the suite-minted traceId — openwop.requirement.0262.traceparent-continued | the suite (createRun with traceparent) | witnessable — gated (family + collector) |
| §E no secret in exported spans | the canary absent from every captured span surface — openwop.requirement.0262.no-secret-in-spans | the suite (one BYOK roundtrip run) | witnessable — gated (family + collector + fixture) |
| §C GenAI attributes | the model-call span's gen_ai.* attributes — openwop.requirement.0262.gen-ai-attributes | the suite (one mock-provider ctx.callAI run) | witnessable — gated (facet + collector + fixture) |
| §B.1 configured endpoint honoured | — | the operator, at host boot | claims-check — the suite cannot set a host's environment; legs 2–6 show it was honoured for the suite's collector |
Alternatives considered
- Turn the
observabilitymetadata into a family. Rejected: a family record carriesstatus,sinceandwitness. Re-shaping an existing root key would break every v2 discovery document that carries it today, which is breaking underCOMPATIBILITY.md§2.4. - Leave telemetry a SHOULD in
conformance.md. Rejected: a SHOULD binds nothing and the v2 export path stays unwitnessed (P-020). - Make the GenAI mapping part of the base claim. Rejected: the upstream conventions are experimental and renamed attributes between versions (
gen_ai.system→gen_ai.provider.name). Pinning the version in a facet lets a host claim exactly what it maps. - Witness through a host scrape seam (v1's
GET /v1/host/sample/test/otel/spans). Rejected: a seam shows what the host says it emitted, not what reached a collector. The suite already owns an OTLP receiver (lib/otel-collector.ts, HTTP/JSON, HTTP/protobuf and gRPC).
Unresolved questions
- Delete the
observabilitymetadata at v3, or keep it as hints? It carries no obligation after §F. - A host that does not continue an untrusted caller's
traceparent(§Security): add a facet membertraceparent: "continue" | "link", or leave §B.4 unconditional? - Should a replay fork's spans link to the source run's trace?
- Should metrics join the claim once a v2 metric vocabulary exists?
Implementation notes (non-normative)
- openwop-app already registers a MeterProvider and exports traces in production; advertising the family needs §B.4 and the span names checked against its exporter.
- The v2 reference host (
openwop/openwop-examples) needs an OTLP exporter; node:http plus the OTLP/HTTP-JSON encoding is enough for §B. - The production certify run needs the host's exporter pointed at the suite's collector, which is the same host-callback pattern as the webhook receiver (a public front for a deployed host).
Acceptance criteria
- [x] Comment window run (
Draft → Active; RFC 0147 §A.6). (Waived by the maintainer, 2026-11-13.) - [ ] Family row, facet schema and
spec/v2/core/telemetry.mdmerged; capabilities schema and profiles regenerated. - [ ]
SECURITY/invariants.yamlrowtelemetry-export-no-secretwithv2-telemetry-export.test.tsas its test. - [ ]
v2-telemetry-export.test.tsin a published suite. - [ ] CHANGELOG entry.
- [ ] A certified host bundle records
0262.run-span,0262.node-span,0262.traceparent-continuedand0262.no-secret-in-spansexecuted-pass(and0262.gen-ai-attributesif the host advertisesgenAiSemconv), each with a sabotage record that ran red. - [ ] Register sweep (
RFCS/registers/0262-*.gaps.md,.risks.md).
References
spec/v1/observability.md(frozen): span names, run- and node-level attributes, the GenAI mapping table.spec/v2/core/conformance.md(the SHOULD this replaces as the v2 claim),host-services.md§secrets,security-defaults.md§"The rule".docs/KNOWN-LIMITS.md§"Shape-only conformance coverage" (OTel legs major 1 only).conformance/src/lib/otel-collector.ts,otlp-protobuf.ts,trace-context.ts,secret-scan.ts.- OpenTelemetry Protocol (OTLP) specification; OpenTelemetry semantic conventions for generative AI systems; W3C Trace Context.
- August 2026 OpenWOP assessment, finding P-020.