Skip to main content
Version: v0.16.3

Correlating PEAC records with OpenTelemetry traces

Status

Informative guide, introduced in v0.16.2. Telemetry is operational signal; a PEAC record is signed, portable evidence. PEAC composes with OpenTelemetry and W3C Trace Context; it does not replace, own, or standardize them.

peac.record.ref is a PEAC custom span attribute, not an OpenTelemetry semantic convention. W3C traceparent / tracestate are correlation carriers, not PEAC proof.

Two correlation directions​

1. W3C Trace Context header to PEAC record​

W3C Trace Context propagates a trace across services via the traceparent and tracestate HTTP headers. @peac/telemetry-otel reads those headers and returns a vendor-neutral extension object you can carry inside a record's org.peacprotocol/correlation extension.

trace-context.ts
import { createTraceContextExtensions } from '@peac/telemetry-otel';

// headers from the inbound HTTP request
const correlation = createTraceContextExtensions(headers);
// -> { "w3c/traceparent": "...", "w3c/tracestate": "..." } when a valid traceparent is present,
//    otherwise undefined

The keys are w3c/traceparent and w3c/tracestate (a vendor-neutral w3c/ namespace, not io.opentelemetry). They are correlation references only; the record's own binding and signature are unchanged.

2. PEAC record to OpenTelemetry span​

When an active OpenTelemetry span exists, @peac/telemetry-otel adds a span event whose attributes include the record reference. New emitters use peac.record.ref; the legacy peac.receipt.ref is dual-emitted for one minor-release compatibility window (read peac.record.ref).

span event peac.receipt.issued
peac.record.ref  = sha256:<hex>   # preferred
peac.receipt.ref = sha256:<hex>   # deprecated, compatibility only

These are PEAC custom attributes, and they are span event attributes, never metric labels (a record reference is high-cardinality).

Boundary (what this is not)​

  • peac.record.ref is a PEAC custom span attribute, not an OpenTelemetry semantic convention. It is not an OpenTelemetry semantic convention unless and until OpenTelemetry adopts it.
  • PEAC ships no OpenTelemetry SDK, exporter, collector, or semantic-convention package. @peac/telemetry defines PEAC attribute names; @peac/telemetry-otel maps PEAC telemetry onto OpenTelemetry span events.
  • W3C traceparent / tracestate are carried as correlation references; they do not establish payment, authorization, or any PEAC finality.

Reference​