Distributed Request Context Manager

Build a request context manager that propagates trace information across asynchronous operations. The manager should maintain immutable context state and provide utilities for managing trace metadata throughout a request lifecycle.

Requirements

Implement a context manager with the following capabilities:

Context Creation and Management

Create a utility function createRequestContext() that initializes a new empty tracing context. This will serve as the base context for tracking request metadata.

Trace ID Propagation

Implement a function setTraceId(context, traceId) that accepts a tracing context and a trace ID string, returning a new context with the trace ID stored. The trace ID should be associated with a Symbol key named TRACE_ID_KEY.

Implement a function getTraceId(context) that retrieves the trace ID from a context, returning the string value or undefined if not present.

Span Context Management

Implement a function setSpanContext(context, spanData) that accepts a tracing context and an object containing span information (such as spanId, parentSpanId, and timestamp), returning a new context with this data stored under a Symbol key named SPAN_CONTEXT_KEY.

Implement a function getSpanContext(context) that retrieves the span context data from a context.

Context Cleanup

Implement a function removeSpanContext(context) that accepts a tracing context and returns a new context with the span context removed, while preserving other metadata like trace IDs.

Context Validation

Implement a function hasTraceId(context) that checks whether a context contains a trace ID, returning a boolean value.

Test Cases

• Calling createRequestContext() returns a valid TracingContext instance @test
• Setting a trace ID on an empty context and retrieving it returns the same trace ID value @test
• Setting a span context with { spanId: "span-123", parentSpanId: "parent-456", timestamp: 1234567890 } and retrieving it returns the same object @test
• After removing span context from a context that has both trace ID and span context, getTraceId still returns the trace ID but getSpanContext returns undefined @test
• hasTraceId returns true for a context with a trace ID and false for an empty context @test

Implementation

@generates

API

import { TracingContext } from '@azure/core-auth';

export const TRACE_ID_KEY: symbol;
export const SPAN_CONTEXT_KEY: symbol;

export function createRequestContext(): TracingContext;

export function setTraceId(context: TracingContext, traceId: string): TracingContext;

export function getTraceId(context: TracingContext): string | undefined;

export function setSpanContext(
  context: TracingContext,
  spanData: { spanId: string; parentSpanId?: string; timestamp: number }
): TracingContext;

export function getSpanContext(
  context: TracingContext
): { spanId: string; parentSpanId?: string; timestamp: number } | undefined;

export function removeSpanContext(context: TracingContext): TracingContext;

export function hasTraceId(context: TracingContext): boolean;

Dependencies { .dependencies }

@azure/core-auth { .dependency }

Provides the TracingContext interface for distributed tracing support.

@satisfied-by