OpenTelemetry tracing and metrics #264

Context

Only correlationId exists today, with no tracing or metrics. #322 adds messageId, sentAt and endpointName; #263 adds middleware and a headers bag that every transport carries.

This is also the foundation for the dashboard in Phase 4.

Decisions

Answered by the maintainer:

1. A separate package, @node-ts/bus-opentelemetry, with only @opentelemetry/api as a peer dependency. Core stays dependency-free, and churn in the messaging semantic conventions stays out of core.

Proposed:

2. One function, openTelemetry(options?), returns the { incoming, handler, outgoing } middleware to pass to withMiddleware(). No classes, no global registration; each bus is instrumented separately.
3. Trace context is propagated as W3C traceparent/tracestate in the headers bag.
4. Semantic conventions. Span and metric names and attributes follow the OpenTelemetry messaging conventions. Those aren't stable yet, so the names are kept in one file, pinned to one version of the conventions.

Non-goals

• Queue-depth metrics. They're transport-specific and move to Monitoring dashboard: failed messages, endpoint health and workflow inspection #270.
• SDK and exporter setup.
• A logs bridge.
• Baggage.
• An @opentelemetry/instrumentation auto-instrumentation plugin.

Approach

• Spans:
  • Outgoing middleware: a PRODUCER span send <$name> or publish <$name>, which injects the context into headers.
  • Incoming middleware: a CONSUMER span process <$name>, a child of the extracted context.
  • Per-handler middleware: an INTERNAL span per handler or workflow, named after it.
  • Errors are recorded on the span.
  • Attributes: messaging.system, messaging.destination.name, messaging.message.id (messageId) and messaging.message.conversation_id (correlationId).
• Metrics: process duration, plus sent, consumed, failed and retried counts, plus critical time (time since sentAt). Failed and retried come from the outcome of Configurable recoverability policy and error queue with failure metadata #262's recoverability policy once it has landed; until then, failed only.

Acceptance criteria

• A test with an in-memory span exporter shows send → process → handler parentage and the semantic-convention attributes
• Trace context propagates over every transport (the headers round trip in transportTests, added by Incoming and outgoing pipeline behaviours (middleware) #263)
• Metrics recorded and tested with an in-memory metric reader
• Package published with the same packaging as the others (check:packages); docs page /guide/opentelemetry; changeset