OpenTelemetry and Subtext: From a Trace to the Session

import { WebTracerProvider } from '@opentelemetry/sdk-trace-web'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { ZoneContextManager } from '@opentelemetry/context-zone'
import {
  CompositePropagator,
  W3CTraceContextPropagator,
  W3CBaggagePropagator,
} from '@opentelemetry/core'
import { registerInstrumentations } from '@opentelemetry/instrumentation'
import { FetchInstrumentation } from '@opentelemetry/instrumentation-fetch'

const provider = new WebTracerProvider({
  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url: '/v1/traces' }))],
})

provider.register({
  contextManager: new ZoneContextManager(),
  propagator: new CompositePropagator({
    propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],
  }),
})

registerInstrumentations({
  instrumentations: [
    new FetchInstrumentation({
      // Only inject traceparent/baggage to your own API origins (never third-party).
      propagateTraceHeaderCorsUrls: [/^https:\/\/api\.yourapp\.com/],
    }),
  ],
})

import { propagation, context } from '@opentelemetry/api'

// Wrap this around the code that should carry the session id forward — e.g.
// your app's render/bootstrap call, or a request handler. context.with()
// only threads the baggage into the callback you pass it (and, with
// ZoneContextManager, into async work scheduled from inside that callback —
// fetches, timers, promise chains). Code that runs after context.with()
// returns, outside the callback, never sees it.
export function attachSubtextSession(next) {
  const sessionId = FS('getSession', { format: 'id' })
  if (!sessionId) return next()

  const baggage = (propagation.getActiveBaggage() ?? propagation.createBaggage()).setEntry(
    'subtext.session.id',
    { value: String(sessionId) } // W3C Baggage values must be strings
  )
  return context.with(propagation.setBaggage(context.active(), baggage), next)
}

FS('observe', {
  type: 'start',
  callback: () => attachSubtextSession(() => renderApp()),
})

import { trace } from '@opentelemetry/api'

class SubtextRootAttributeProcessor {
  onStart(span, parentContext) {
    // Root span only: no parent span in the context the SDK resolved for this span.
    if (trace.getSpan(parentContext)) return
    const url = FS('getSession', { format: 'url.now' })
    if (url) span.setAttribute('subtext.session.url', url)
  }
  onEnd() {}
  shutdown() {
    return Promise.resolve()
  }
  forceFlush() {
    return Promise.resolve()
  }
}
// Add alongside BatchSpanProcessor in WebTracerProvider({ spanProcessors: [...] }).

npm i @opentelemetry/baggage-span-processor

import { BaggageSpanProcessor } from '@opentelemetry/baggage-span-processor'

// Copy only the Subtext session id onto spans. ALLOW_ALL_BAGGAGE_KEYS (also
// exported by this package) copies every baggage entry — skip it here so a
// key some other tool later adds to baggage doesn't silently land on every
// span attribute too.
const subtextBaggageProcessor = new BaggageSpanProcessor((key) => key === 'subtext.session.id')
// Add subtextBaggageProcessor alongside your other span processors on the
// NodeTracerProvider / NodeSDK spanProcessors array.

import { context, trace } from '@opentelemetry/api'

const span = trace.getSpan(context.active())
const ctx = span?.spanContext()
if (ctx) {
  FS('trackEvent', {
    name: 'otel_trace',
    properties: { trace_id: ctx.traceId, span_id: ctx.spanId },
  })
}

{ span.subtext.session.id = "<id>" }