feat(trace): support remote W3C parent context

[Savid]

Description

Add support for parenting plugin spans under an external W3C trace context.

This adds OPENCODE_TRACEPARENT and OPENCODE_TRACESTATE, parses them with OpenTelemetry’s W3C trace-context propagator, threads the resulting root context through HandlerContext, and uses it when creating session, LLM, and tool spans.

The README documents the default parent-based sampler behavior where a valid unsampled remote parent (...-00) suppresses span export by design.

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Chore (dependency updates, etc.)

Checklist

• I have read the CONTRIBUTING.md document
• My code follows the style guidelines of this project
• bun run lint passes with no errors
• bun run check:jsdoc-coverage passes with no errors
• bun run typecheck passes with no errors
• bun test passes with no errors
• I have added tests that prove my fix is effective or that my feature works
• I have updated the documentation accordingly
• My commits follow the Conventional Commits specification

Related issues

None.

Additional context

This intentionally uses OPENCODE_-prefixed environment variables rather than automatically reading bare TRACEPARENT / TRACESTATE, keeping plugin configuration explicit and consistent with the rest of the project.

With the default ParentBased sampler, passing a traceparent with the sampled flag off (...-00) causes spans to be non-recording and suppresses trace export. This is expected OpenTelemetry behavior and is documented in the README.

Summary by CodeRabbit

• New Features

  • Added support for OpenTelemetry distributed tracing via OPENCODE_TRACEPARENT and OPENCODE_TRACESTATE environment variables.
  • Plugin can now receive and propagate remote trace context from incoming requests.

• Documentation

  • Updated README with new tracing environment variable configuration options.

• Dependencies

  • Added OpenTelemetry core library dependency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 553c2533-6195-4d2f-9a8e-e8fc5899ddc6

📥 Commits

Reviewing files that changed from the base of the PR and between e50a9ed and 83e3d42.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock, !**/*.lock

📒 Files selected for processing (12)

• README.md
• package.json
• src/config.ts
• src/handlers/message.ts
• src/handlers/session.ts
• src/index.ts
• src/trace-context.ts
• src/types.ts
• tests/config.test.ts
• tests/handlers/spans.test.ts
• tests/helpers.ts
• tests/trace-context.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds W3C Trace Context propagation for OpenTelemetry by extracting remote parent span context from environment variables, storing it in the handler context, and updating all span creation to use this stored context instead of the active context, enabling distributed tracing with upstream systems.

Changes

W3C Trace Context Remote Parent Propagation

Layer / File(s)	Summary
Configuration and remote parent extraction src/config.ts, src/trace-context.ts, package.json, README.md, tests/config.test.ts, tests/trace-context.test.ts	PluginConfig adds optional traceparent and tracestate fields; loadConfig() reads OPENCODE_TRACEPARENT and OPENCODE_TRACESTATE from environment; new remoteParentContext() function uses OpenTelemetry's W3CTraceContextPropagator to extract remote parent context from W3C headers, returning undefined for invalid/missing input; comprehensive tests validate parsing, ID validation, and version handling.
HandlerContext type and root context storage src/types.ts, src/index.ts, tests/helpers.ts	HandlerContext gains rootContext: () => Context property; in index.ts, extracted remote context (or ROOT_CONTEXT fallback) is computed and attached to the ctx object for downstream use; test helpers updated to provide rootContext function in mock context.
Span parenting refactoring in handlers src/handlers/session.ts, src/handlers/message.ts, tests/handlers/spans.test.ts	Session and message handlers replace context.active()-based parent context with ctx.rootContext(), optionally applying trace.setSpan() when a session/parent span exists; updated tests validate that session root spans are correctly parented to injected remote context and that root context is resolved at span creation time.

Sequence Diagram(s)

sequenceDiagram
  participant Remote as Upstream System
  participant Plugin as Plugin (index.ts)
  participant Config as loadConfig
  participant Propagator as W3CTraceContextPropagator
  participant Handler as Message/Session Handler
  participant Span as OpenTelemetry Span
  
  Remote->>Plugin: HTTP with traceparent/tracestate headers
  Plugin->>Config: Load env vars OPENCODE_TRACEPARENT, OPENCODE_TRACESTATE
  Config-->>Plugin: traceparent, tracestate values
  Plugin->>Propagator: Extract remote parent context
  Propagator-->>Plugin: Remote parent Context or undefined
  Plugin->>Plugin: Store rootContext in ctx
  Handler->>Handler: Create child span
  Handler->>Span: Use ctx.rootContext() with setSpan(parentCtx, sessionSpan)
  Span-->>Handler: Child span parented to remote context

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• DEVtheOPS/opencode-plugin-otel#20: Spans parenting logic in session and message handlers directly builds on and refactors changes related to OpenTelemetry span parent/child relationships.

Suggested reviewers

• dialupdisaster

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(trace): support remote W3C parent context' directly and clearly summarizes the main change: adding support for parenting plugin spans under an external W3C trace context, which is the core objective of the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}