Skip to content

[Context]: add distributed context propagation for cross-boundary correlation #10

Description

@rian-be

Summary

Add a lightweight, opt-in propagation and tracing surface so context metadata
survives the process boundary (HTTP, gRPC, queues) and can be correlated
end-to-end.

Goal

Make the package observable and transportable across process boundaries without
turning it into a telemetry framework.

Problem

The context lives in AsyncLocal<T> and flows through await/Task within one
process, but it is lost at network boundaries (HTTP, gRPC, queues). There is no
simple, library-level way to write the current context into an outbound carrier
and rebuild it on the receiving side.

While the package now exposes the core serializer and propagator contracts
(IContextSerializer<T>, IContextPropagator<TCarrier>, ContextPayload),
there is no ready-made adapter for header carriers and no illustration of how
to rebuild context on the receiving side, so tracing an operation's flow across
services is awkward for:

  • tracing
  • auditing
  • debugging
  • integration with observability pipelines
  • custom instrumentation in larger applications

Scope

  • Add a header-based propagator adapter (e.g. X-Correlation-Id, X-Tenant-Id)
    built on IContextPropagator<TCarrier>.
  • Add example(s) showing a client shipping context and a server middleware
    rebuilding it with BeginContext.
  • Document the IContextPropagator/IContextSerializer usage against the new
    ContextPayload contract.
  • Keep the tracing/Activity side as an observer (no change to the core
    execution path).

Design Expectations

  • Propagation is opt-in and explicit; the library never auto-exports context.
  • The propagator does not know the serializer or the concrete context type.
  • The API focuses on observation/transport, not on policy.
  • Consumers can ignore the propagation layer entirely.
  • Context stays immutable; tracing is built on lifecycle events, never on the
    context object.

Acceptance Criteria

  • The package exposes a usable header-based propagator and round-trip example.
  • The lifecycle observer receives the already-present Previous/Current
    transitions for correlation.
  • Actor execution behavior stays unchanged when no propagator is registered.
  • The model stays small, structured, and format-neutral.

Non-Goals

  • No W3C traceparent/tracestate or B3 support in v1.
  • No APM/OpenTelemetry-specific sink.
  • No background event bus.
  • No retry/persistence/compliance layer.
  • No changes to the core runtime execution path.

Notes

This issue covers distributed propagation (cross-boundary correlation) only.
Full OpenTelemetry/APM integration is out of scope here.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestextensionExtension behaviors / helperspropagationContext across process boundaries

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions