Align observe instrumentation with OpenTelemetry conventions

[Copilot]

This updates the library’s tracing behavior to better match OpenTelemetry expectations without requiring a public API rewrite. The change focuses on standards-compliant propagation, additive semantic/resource metadata, and more accurate error/status reporting across the existing Observe instrumentation surface.

• W3C trace context + baggage

  • Accept inbound traceparent/baggage and prefer traceparent over legacy x-request-id
  • Add tracer helpers for downstream propagation and baggage access/update
  • Harden parsing/formatting to reject invalid traceparent values and zero trace IDs

• OTel semantic/resource metadata

  • Add OTel-style tags to emitted HTTP, RPC/gRPC, GraphQL, queue, and scheduler snapshots
  • Populate resource-style fields from config/env: service.name, service.version, deployment.environment
  • Keep existing telemetry shape intact by adding metadata rather than replacing current fields

• Error/status alignment

  • Record exception-oriented metadata (exception.type, exception.message) on captured errors
  • Set otel.status_code consistently, including HTTP server behavior that treats 5xx as errors without over-reporting 4xx responses
  • Preserve meaningful failure context without broadening sensitive payload capture

• Configuration/documentation

  • Extend observe options with OTel-oriented resource configuration hooks
  • Document propagation behavior, OTel-compatible setup, and migration notes
  • Add a minimal Nest usage example for downstream header propagation

• Coverage updates

  • Add focused tests for propagation precedence, baggage handling, semantic tags, and exception/status metadata
  • Update integration coverage to assert additive OTel metadata in real protocol flows

Example:

@Injectable()
export class OrdersService {
  constructor(private readonly tracer: TracerService) {}

  async createOrder() {
    const headers = this.tracer.currentPropagationHeaders();

    await fetch("https://inventory.internal/reserve", {
      method: "POST",
      headers,
    });
  }
}

[Copilot]

🟡 Changes recommended

There are a few correctness/contract issues (notably propagation header behavior and resource-attribute merge semantics) that should be addressed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR aligns Observe’s existing NestJS instrumentation with common OpenTelemetry conventions by adopting W3C Trace Context + baggage, emitting additive OTel-style semantic/resource tags on snapshots/logs, and improving status/error metadata without changing the public ingestion payload shape.

Changes:

• Added OpenTelemetry utility helpers for W3C traceparent/baggage parsing/formatting and for generating resource/severity attributes.
• Updated HTTP/RPC/gRPC/GraphQL/queue/scheduler instrumentation to adopt inbound propagation, store baggage in async context, and emit OTel semantic/resource tags.
• Enhanced log forwarding to preserve structured timestamps/trace/span IDs and to merge canonical OTel log attributes while preserving conflicting source values under log.source.*.

File summaries

File	Description
src/utils/opentelemetry.util.ts	Adds W3C propagation parsing/formatting, baggage helpers, and OTel resource/log attribute generation.
src/utils/opentelemetry.util.spec.ts	Unit tests for traceparent/baggage parsing, formatting, and mixed-carrier extraction behavior.
src/utils/log-line.parser.ts	Expands structured log parsing to support OTel/OpenObserve-style aliases (severity, trace/span IDs, timestamps).
src/utils/log-line.parser.spec.ts	Tests for new structured log aliases and timestamp/trace/span parsing.
src/utils/default-trace-id-generator.util.ts	Prefers inbound traceparent trace-id before legacy x-request-id.
src/utils/default-trace-id-generator.util.spec.ts	Tests that inbound W3C trace context is adopted.
src/services/tracer.service.ts	Adds helpers to read propagation headers and to get/set baggage on the current async context.
src/services/tracer.service.spec.ts	Tests for propagation header formatting, baggage behavior, and span-id fallback rules.
src/services/stdout-forwarder.service.ts	Preserves parsed timestamps/span IDs and merges canonical OTel log attributes while preserving source conflicts.
src/services/stdout-forwarder.service.spec.ts	Tests for timestamp preservation, additive OTel metadata, and conflict preservation under log.source.*.
src/services/operation-trace.registry.ts	Adds exception and otel.status_code tagging, sets HTTP semantic status tags, and switches span-id generation to 16-hex.
src/services/operation-trace.registry.spec.ts	Updates expectations for exception/status tags and additional OTel-aligned metadata.
src/protocols/schedule-observe-agent.service.ts	Adds OTel resource + scheduler semantic tags to scheduled job snapshots.
src/protocols/schedule-collection.int-spec.ts	Integration assertions for additive scheduler + service tags.
src/protocols/rpc-observe-agent.service.ts	Adopts W3C propagation/baggage and adds OTel RPC semantic/resource tags for RPC + gRPC.
src/protocols/rpc-observe-agent.service.spec.ts	Tests that gRPC calls adopt traceparent/baggage and emit expected semantic/resource tags.
src/protocols/queue-observe-agent.service.ts	Adds OTel resource + messaging semantic tags to queue job snapshots.
src/protocols/http-observe-agent.service.ts	Adopts W3C propagation/baggage and adds OTel HTTP/url semantic/resource tags (including path/query/scheme).
src/protocols/http-observe-agent.service.spec.ts	Tests URL parsing/scheme normalization and W3C propagation + semantic tag behavior.
src/protocols/http-collection.int-spec.ts	Integration test for adopting inbound traceparent + baggage and emitting OTel tags.
src/protocols/graphql-observe-agent.service.ts	Applies propagation to store and adds OTel GraphQL semantic/resource tags plus baggage tags.
src/protocols/graphql-collection.int-spec.ts	Integration assertions for GraphQL semantic tags on snapshots.
src/interfaces/observe-options.interface.ts	Extends options with serviceName, deploymentEnvironment, and resourceAttributes for OTel-style resource metadata.
README.md	Documents OTel compatibility, resource config, W3C propagation, and log forwarding behavior/migration notes.

Review details

• Files reviewed: 24/24 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.