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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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