FRD: Tracing / OTel Wrapper

Document Summary

Field	Details
Feature Name	Tracing / OTel Wrapper
Status	Draft
Owner	David Holmes
Contributors	Engineering
Target Release	v2.0.0
Related Links	ADR-051 (Provider Pattern), ADR-023 (Wide Events Logging), ADR-027 (Default Tech Stack), ADR-014 (Open Source First)
Last Updated	2026-06-02
Open Source Libraries	`@opentelemetry/api`, `@opentelemetry/sdk-node`, `@opentelemetry/exporter-trace-otlp-http`, `@opentelemetry/sdk-trace-web`
Documentation	OTel JavaScript Docs · Getting Started · API Reference · OTLP Exporter

This FRD ships @dmwd-io/tracing as an optional package that re-exports @opentelemetry/api and @opentelemetry/sdk-node as the platform standard for distributed tracing via OpenTelemetry, layering only platform-specific conventions on top: span naming, OTLP export defaults, and standard env var names. The value is standards alignment and drift prevention, not a custom abstraction over the library.

Introduction

Overview

ADR-023 mentions distributed tracing and trace_id correlation but no productized tracing solution exists. Each app that wants tracing manually configures OpenTelemetry SDK packages, chooses exporters, and invents its own span naming conventions. Trace context propagation across service boundaries is inconsistent.

Per ADR-014 (Open Source First), this FRD designates @opentelemetry/api and @opentelemetry/sdk-node as the community-standard library for distributed tracing and ships them through @dmwd-io/tracing — a thin re-export package. Platform conventions added on top are limited to: the {domain}.{action} span naming standard from ADR-023, the OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME env var names, and default sampling rates. No custom provider interface is built — the OTel library’s own API is the interface.

Goals

Designate @opentelemetry/api and @opentelemetry/sdk-node as the platform standard for distributed tracing.
Ship @dmwd-io/tracing as a thin re-export of those libraries so teams import from a single canonical package.
Document OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME as the platform-standard env var names.
Define span naming conventions matching the {domain}.{action} pattern from ADR-023.
Correlate traces with wide-event log entries via shared trace_id and span_id fields.
Include documentation covering frontend and backend setup.

Non-Goals

Building a custom provider interface or adapter layer — the library’s own API is the interface (per ADR-014).
Building a custom tracing backend or collector (use Grafana Tempo, Jaeger, or a vendor).
Implementing metrics collection (counters, histograms) — tracing only for v1.
Building a tracing UI or trace viewer.
Auto-instrumenting database queries (app-level concern using OTel ecosystem plugins).
React component-level tracing (render spans).

Scope

In Scope

Area	Description
Bootstrap function	`createTracingProvider(config)` initializing OTel SDK with exporter, service name, and environment
Span naming	Convention: `{domain}.{action}` matching ADR-023 wide events
Context propagation	W3C TraceContext propagation via `traceparent` header
Fetch instrumentation	`instrumentFetch()` wrapping the global `fetch` to create spans and propagate context
HTTP instrumentation	`instrumentHttp()` wrapping Node.js HTTP server to create incoming request spans
Log correlation	Helper to extract `trace_id` and `span_id` from the current span for wide-event logging
Exporters	OTLP (gRPC/HTTP) and console exporter support
Shutdown	`shutdown()` method for graceful flush on process exit
Test adapter	`createTestTracingProvider()` capturing spans in-memory for assertions

Out of Scope

Area	Reason
Metrics (counters, histograms, gauges)	Separate concern; tracing-only for v1
Custom tracing backend	Use standard OTLP-compatible backends
Database instrumentation	App-level; use existing OTel ecosystem plugins
React render tracing	Complex and high-overhead; not in initial scope
Tracing UI / visualization	Vendor-hosted (Grafana, Jaeger)

Users and Pain Points

User Groups

User	Description	Needs
Backend developers	Engineers building services and API routes	Consistent tracing initialization with propagation across service boundaries
Frontend developers	Engineers building client-side apps	Fetch instrumentation with trace context propagation to backend
SRE / on-call engineers	Responders investigating latency and failures	Correlated traces and logs for end-to-end request visibility

Pain Points

User	Pain Point	Impact
Backend developers	Each service initializes OTel differently — different span names, different exporters, inconsistent propagation	Traces break at service boundaries; latency attribution is unreliable
Frontend developers	No frontend tracing — client-side requests are invisible in traces	Backend engineers cannot see the full request lifecycle
SRE engineers	Logs and traces are not correlated — `trace_id` is missing from log entries	Cross-referencing logs and traces requires manual guesswork
Backend developers	Span names vary across services — `handleRequest` vs `api.users.list` vs `GET /users`	Trace viewers are hard to navigate; filtering is unreliable

Definitions

Term	Definition
Span	A named, timed operation within a trace representing a unit of work
Trace	A tree of spans representing a distributed operation across services
Trace context	Metadata (`trace_id`, `span_id`, `trace_flags`) propagated between services
W3C TraceContext	The standard HTTP header format (`traceparent`) for propagating trace context
OTLP	OpenTelemetry Protocol — the standard wire format for exporting spans to collectors
Instrumentation	Code that automatically creates spans for common operations (fetch, http)
Exporter	A component that sends collected spans to a tracing backend
Wide event	A single structured log entry per ADR-023 containing `trace_id` for correlation

Current State

Existing Behavior

ADR-023 defines wide-event logging with a trace_id field, but no tracing infrastructure populates that field. There are no files under src/lib/observability/. Some apps have experimented with @opentelemetry/sdk-node in their entry points but none share configuration, span naming, or propagation patterns. Frontend services have no tracing at all.

Current Limitations

No shared tracing bootstrap — each app configures OTel from scratch.
No span naming convention — span names are inconsistent across services.
No trace_id in log entries — ADR-023 defines the field but nothing populates it.
No frontend tracing — client-side fetch requests do not create spans or propagate context.
No test adapter — tracing code is not tested because there is no in-memory span capture.
No graceful shutdown — some apps lose final spans on process exit.

Existing Workarounds

Backend apps copy-paste OTel setup from a wiki article.
Log correlation is done manually by searching timestamps across tools.
Frontend observability relies entirely on error tracking and analytics.

Proposed Solution

Summary

Per ADR-014, @dmwd-io/tracing is a thin re-export package. It re-exports @opentelemetry/api and @opentelemetry/sdk-node as peer dependencies and adds only the platform-level conventions listed below. No custom interface is built — the library’s API is the interface.

// All OTel API and SDK exports are available from the canonical platform import
import { trace, context, SpanStatusCode } from '@dmwd-io/tracing';
import { NodeSDK } from '@dmwd-io/tracing/sdk-node';

Platform conventions added on top of the library

Span naming: {domain}.{action} format matching ADR-023 (e.g. http.incoming_request, billing.charge).
Env vars: OTEL_EXPORTER_OTLP_ENDPOINT for the collector URL, OTEL_SERVICE_NAME for the service identifier.
Default sample rates: 0.05 for frontend, 1.0 for backend (configurable via OTEL_TRACES_SAMPLER_ARG).
Log correlation: guidance for extracting trace_id and span_id from the active span to populate ADR-023 wide-event log entries.

User Experience

End users are not directly affected. Tracing is a developer and operations concern. Users benefit indirectly from faster incident resolution.

Developer Experience

Teams import from @dmwd-io/tracing and get the full OTel API. The package enforces no wrapper layer — developers use @opentelemetry/api’s trace.getTracer(), tracer.startActiveSpan(), and trace.getActiveSpan() directly. The platform conventions (span naming, env vars, sample rate defaults) are documented rather than enforced programmatically.

Requirements

ID	Requirement	Priority	Notes
FR-001	Export `createTracingProvider(config)` initializing OTel with configurable exporter, service name, and sample rate	Must	-
FR-002	Export `instrumentFetch()` for client-side fetch instrumentation with context propagation	Must	-
FR-003	Export `instrumentHttp(server)` for Node.js HTTP server instrumentation	Must	-
FR-004	Export `getTraceContext()` returning `{ traceId, spanId }` for log correlation	Must	-
FR-005	Export `withSpan(name, fn)` for wrapping arbitrary operations in a span	Must	-
FR-006	Export `shutdown()` for graceful span flush on process exit	Must	-
FR-007	Export `createTestTracingProvider()` capturing spans in-memory	Must	-
FR-008	Support OTLP (HTTP) and console exporters via config	Should	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	`createTracingProvider({ serviceName: "api", exporter: "otlp" })` initializes OTel and starts collecting spans	One-line tracing setup in service entry points	Must
FUNC-002	`instrumentFetch()` creates a span for each `fetch()` call with the URL and method as span attributes	Client-side requests are visible in traces	Must
FUNC-003	`instrumentFetch()` injects `traceparent` header into outgoing requests	Trace context propagates from frontend to backend	Must
FUNC-004	`instrumentHttp(server)` creates a span for each incoming HTTP request	Backend request latency is visible in traces	Must
FUNC-005	`getTraceContext()` returns the current `traceId` and `spanId` for embedding in log entries	Logs and traces are correlated per ADR-023	Must
FUNC-006	`withSpan("billing.charge", async () => {...})` creates a child span around the operation	Custom operations are traced without manual OTel SDK usage	Must
FUNC-007	Span names follow `{domain}.{action}` convention: `http.request`, `fetch.call`, `billing.charge`	Consistent naming across all services	Must
FUNC-008	Test adapter’s `.spans` array contains all created spans with names, attributes, and durations	Instrumentation is testable	Must

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Tracing overhead does not exceed 5% latency increase on instrumented operations	Performance	Must
NFR-002	Tracing failures (exporter down, span creation error) must not crash the app	Reliability	Must
NFR-003	`instrumentFetch()` must not modify the original `fetch` response or error behavior	Compatibility	Must
NFR-004	Test adapter operates fully in-memory with no network I/O	Testing	Must
NFR-005	OTel SDK packages are peer dependencies, not bundled	Performance	Must
NFR-006	`shutdown()` flushes all pending spans within a configurable timeout (default 5s)	Reliability	Should
NFR-007	Sampling rate is configurable (0.0 to 1.0) to control span volume	Performance	Should

API / Interface Requirements

Public API

Name	Type	Description	Required
`TracingProvider`	interface	Core contract with `withSpan`, `getTraceContext`, `shutdown`	Yes
`TracingConfig`	type	`{ serviceName, environment, exporter, sampleRate, otlpEndpoint? }`	Yes
`TraceContext`	type	`{ traceId: string, spanId: string }`	Yes
`SpanRecord`	type	`{ name, attributes, startTime, endTime, status, parentSpanId? }` (test adapter)	Yes
`createTracingProvider`	function	Bootstrap factory returning `TracingProvider`	Yes
`instrumentFetch`	function	Wraps global `fetch` with span creation and context propagation	Yes
`instrumentHttp`	function	Wraps Node.js HTTP server with incoming request spans	Yes
`getTraceContext`	function	Returns `TraceContext` from active span	Yes
`withSpan`	function	`<T>(name: string, fn: () => Promise<T>) => Promise<T>`	Yes
`createTestTracingProvider`	function	Returns `TracingProvider & { spans: SpanRecord[] }`	Yes

Example Usage

// Backend entry point
import { createTracingProvider, instrumentHttp, getTraceContext } from "@dmwd/design-system/observability/tracing";

const tracing = createTracingProvider({
  serviceName: "billing-api",
  environment: "production",
  exporter: "otlp",
  otlpEndpoint: "http://collector:4318",
  sampleRate: 0.1,
});

// Auto-instrument incoming requests
instrumentHttp(server);

// Manual span
const result = await tracing.withSpan("billing.create_invoice", async () => {
  return await createInvoice(customerId);
});

// Log correlation
const { traceId, spanId } = getTraceContext();
logger.info({ msg: "invoice.created", trace_id: traceId, span_id: spanId });

// Graceful shutdown
process.on("SIGTERM", () => tracing.shutdown());

// Frontend
import { createTracingProvider, instrumentFetch } from "@dmwd/design-system/observability/tracing";

createTracingProvider({ serviceName: "web-app", exporter: "otlp", sampleRate: 0.05 });
instrumentFetch(); // All subsequent fetch() calls are traced

API Notes

instrumentFetch() patches the global fetch; call it once at app startup.
instrumentHttp() accepts a Node.js http.Server or compatible object.
withSpan propagates the span context to child operations automatically.
OTel SDK packages (@opentelemetry/sdk-trace-base, @opentelemetry/api) are peer dependencies.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Package is a backend/infrastructure utility with no UI — accessibility requirements do not apply	No UI components

Checklist

Keyboard support is defined. (N/A — no UI)
Focus behavior is defined. (N/A — no UI)
Screen reader behavior is defined. (N/A — no UI)
Color contrast requirements are met. (N/A — no UI)
Reduced motion behavior is considered. (N/A — no UI)
Semantic HTML expectations are documented. (N/A — no UI)
ARIA usage is defined only where needed. (N/A — no UI)

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page explaining tracing setup for frontend and backend	Storybook	Must
DOC-002	Inline JSDoc on every exported function and type	Source code	Must
DOC-003	Example: backend service setup with `instrumentHttp` and log correlation	Storybook	Must
DOC-004	Example: frontend setup with `instrumentFetch`	Storybook	Must
DOC-005	Example: custom span with `withSpan`	Storybook	Should
DOC-006	Example: test assertions using the test adapter	Storybook	Should

Dependencies

Dependency	Type	Owner	Status	Notes
ADR-051 provider pattern	Architecture	Engineering	Ready	General structure guidance
ADR-023 wide events logging	Architecture	Engineering	Ready	Defines `trace_id` field and `{domain}.{action}` naming
`@opentelemetry/api`	Peer dependency	OTel project	Ready	Core OTel API
`@opentelemetry/sdk-trace-base`	Peer dependency	OTel project	Ready	Span processing
`@opentelemetry/exporter-trace-otlp-http`	Peer dependency	OTel project	Ready	OTLP exporter

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
OTel SDK is large — peer dependencies increase app bundle for frontend	Frontend bundle size increases	Tree-shakeable imports; sampling rate 0.0 effectively disables tracing; document bundle impact
Patching global `fetch` may conflict with other libraries that also patch fetch	Unpredictable behavior if multiple patches stack	Document the patching approach; provide a non-patching `tracedFetch()` wrapper alternative
OTel SDK API changes could break the wrapper	Maintenance burden	Pin to a stable OTel API version; abstract the OTel API behind the `TracingProvider` interface
Sampling rate 0.0 still initializes OTel infrastructure	Wasted resources when tracing is effectively disabled	Document that omitting `createTracingProvider()` entirely is the zero-overhead path
Frontend tracing at high sample rates generates many spans	Collector capacity may be overwhelmed	Default sample rate is 0.05 (5%) for frontend; document tuning guidance

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the wrapper support OTLP gRPC in addition to HTTP?	David Holmes	Open	—
Q-002	Should `instrumentFetch` support filtering which URLs are traced (e.g. exclude analytics calls)?	David Holmes	Open	—
Q-003	Should the wrapper include a `baggage` helper for propagating custom key-value pairs across services?	David Holmes	Open	—
Q-004	Should the frontend wrapper support `PerformanceObserver` integration for Web Vitals correlation?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	`createTracingProvider({ serviceName: "test", exporter: "console" })` initializes without error	FR-001
AC-002	`instrumentFetch()` adds a `traceparent` header to outgoing fetch requests	FR-002, FUNC-003
AC-003	`getTraceContext()` returns a valid `traceId` and `spanId` within an active span	FR-004
AC-004	`withSpan("test.op", fn)` creates a span visible in the test adapter’s `.spans` array	FR-005, FUNC-008
AC-005	Span names follow `{domain}.{action}` convention	FUNC-007
AC-006	`shutdown()` flushes pending spans without error	FR-006
AC-007	Test adapter captures spans with names, attributes, and durations	FR-007
AC-008	Tracing failures do not throw — they are silently handled	NFR-002
AC-009	Unit tests cover provider creation, withSpan, fetch instrumentation, log correlation, and shutdown	FR-001 through FR-008
AC-010	OTel SDK packages are listed as peer dependencies, not direct dependencies	NFR-005

LLM Handoff Instructions

Expected LLM Behavior

Create the package under packages/tracing/ (or the repo’s established packages directory).
Add a package.json naming the package @dmwd-io/tracing with @opentelemetry/api and @opentelemetry/sdk-node as peer dependencies (not direct dependencies).
Create src/index.ts that re-exports the full OTel API surface: export * from '@opentelemetry/api'.
Add a src/sdk-node.ts entry that re-exports @opentelemetry/sdk-node: export * from '@opentelemetry/sdk-node'.
Document OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, and OTEL_TRACES_SAMPLER_ARG as the platform env var names in the package README or Storybook docs page.
Document the {domain}.{action} span naming convention from ADR-023.
Run pnpm typecheck to confirm the package compiles cleanly.

LLM Should Not

Build a custom TracingProvider interface, factory function, or adapter layer.
Bundle OTel SDK packages as direct dependencies.
Implement metrics or logging (tracing only).
Build framework-specific middleware (Express, Hono, Astro).
Invent helper functions that duplicate what the OTel library already provides natively.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	OTel SDK as peer dependencies, not bundled	Avoids version conflicts and reduces bundle size for apps that already use OTel	David Holmes
2026-05-26	`{domain}.{action}` span naming matching ADR-023	Consistent naming across logs and traces enables cross-tool queries	David Holmes
2026-05-26	Separate frontend and backend instrumentation functions	Different runtimes (browser vs Node.js) require different OTel providers and instrumentations	David Holmes
2026-06-02	Reframed per ADR-014 (Open Source First): adopt `@opentelemetry/api` / `@opentelemetry/sdk-node` as thin re-export rather than building a custom provider interface. Library API is the interface.	ADR-014 mandates designating community libraries as the standard rather than wrapping them	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft
2026-06-02	David Holmes	Reframed per ADR-014: ship as thin re-export of `@opentelemetry/api` / `@opentelemetry/sdk-node`, drop custom interface.