Add support for async context propagation and baggage in tracing service.

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

packages/backend-plugin-api/report-alpha.api.md

@@ -292,11 +292,16 @@ export const rootSystemMetadataServiceRef: ServiceRef<
 
 // @alpha
 export interface TracingService {
+  getActiveBaggage(): TracingServiceBaggage | undefined;
   startActiveSpan<T>(
     name: string,
     fn: (span: TracingServiceSpan) => T | Promise<T>,
     options?: TracingServiceSpanOptions,
   ): Promise<T>;
+  withPropagatedContext<T>(
+    headers: Record<string, string | string[] | undefined>,
+    fn: () => T | Promise<T>,
+  ): Promise<T>;
 }
 
 // @alpha
@@ -314,6 +319,20 @@ export type TracingServiceAttributeValue =
   | Array<null | undefined | number>
   | Array<null | undefined | boolean>;
 
+// @alpha
+export interface TracingServiceBaggage {
+  // (undocumented)
+  getAllEntries(): Array<[string, TracingServiceBaggageEntry]>;
+  // (undocumented)
+  getEntry(key: string): TracingServiceBaggageEntry | undefined;
+}
+
+// @alpha
+export interface TracingServiceBaggageEntry {
+  // (undocumented)
+  value: string;
+}
+
 // @alpha
 export const tracingServiceRef: ServiceRef<
   TracingService,

packages/backend-plugin-api/src/alpha/TracingService.ts

@@ -106,4 +106,39 @@ export interface TracingService {
     fn: (span: TracingServiceSpan) => T | Promise<T>,
     options?: TracingServiceSpanOptions,
   ): Promise<T>;
+
+  /**
+   * Extracts propagated context from HTTP headers and runs `fn` within
+   * it. Use this to bridge context across async boundaries where
+   * automatic propagation is lost.
+   */
+  withPropagatedContext<T>(
+    headers: Record<string, string | string[] | undefined>,
+    fn: () => T | Promise<T>,
+  ): Promise<T>;
+
+  /**
+   * Returns the active baggage from the current context, or `undefined`
+   * when none is present.
+   */
+  getActiveBaggage(): TracingServiceBaggage | undefined;
+}
+
+/**
+ * A read-only view of propagated baggage entries.
+ *
+ * @alpha
+ */
+export interface TracingServiceBaggage {
+  getEntry(key: string): TracingServiceBaggageEntry | undefined;
+  getAllEntries(): Array<[string, TracingServiceBaggageEntry]>;
+}
+
+/**
+ * A single baggage entry.
+ *
+ * @alpha
+ */
+export interface TracingServiceBaggageEntry {
+  value: string;
 }

packages/backend-plugin-api/src/alpha/index.ts

@@ -50,6 +50,8 @@ export type {
   TracingService,
   TracingServiceAttributeValue,
   TracingServiceAttributes,
+  TracingServiceBaggage,
+  TracingServiceBaggageEntry,
   TracingServiceSpan,
   TracingServiceSpanKind,
   TracingServiceSpanOptions,

packages/backend-plugin-api/src/alpha/refs.ts

@@ -71,7 +71,7 @@ export const metricsServiceRef = createServiceRef<
 /**
  * Service for managing trace spans.
  *
- * See {@link TracingService} for the API surface.
+ * See `TracingService` for the API surface.
  *
  * @alpha
  */