skills.rest
dxos
dxosOFFICIAL
Explore all skills by this author →
Website𝕏@dxos_orgGitHub

context-propagation

Enforces ctx parameter propagation rules for connected OpenTelemetry trace hierarchies in DXOS code.

518|49|Updated Apr 7, 2021
Search Tags:#distributed tracing#typeScript#openTelemetry#context propagation#dxos#Observability#trace spans
One-click install
npx skills add https://github.com/dxos/dxos --skill context-propagation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: context-propagation
Source: https://github.com/dxos/dxos/tree/main/.agents/skills/context-propagation
Command: npx skills add https://github.com/dxos/dxos --skill context-propagation

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Distributed traces in the DXOS codebase break when intermediate methods fail to forward the ctx: Context parameter, causing @trace.span() decorators to create orphaned root spans disconnected from the trace hierarchy. This Skill provides the rules for threading context through call chains so traces stay connected.

Core Features & Use Cases

  • Propagation Rules: Defines when and how to pass ctx: Context as the first parameter across direct calls, callbacks, detached async work, and parallel fan-out.
  • Boundary Guidance: Specifies correct context sources for public APIs (Context.default()), RPC service methods (options.ctx), and lifecycle-scoped work (this._ctx).
  • Audit Reference: Includes a compliance audit of context propagation across networking, space lifecycle, and resource open/close paths with prioritized fixes.
  • Use Case: When adding a @trace.span() to an internal method or reviewing a PR that touches Context, use this Skill to verify the full call chain forwards ctx and no orphaned spans are introduced.

Quick Start

Review my changes to DataSpaceManager and check whether ctx is propagated correctly through every method that reaches a @trace.span() decorated call.

Frequently Asked Questions about context-propagation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I propagate trace context through TypeScript methods?▼

Add ctx: Context as the first parameter to every internal method in the call chain and forward it to downstream calls. The @trace.span() decorator reads the parent span from ctx and derives a child context automatically.

Why are my OpenTelemetry spans showing as orphaned roots?▼

Orphaned roots occur when an intermediate method creates Context.default() instead of forwarding the caller's ctx, breaking the trace chain. Fix it by threading ctx from the entry point through every method to the @trace.span() decorated call.

How do RPC service methods receive trace context?▼

RPC service methods cannot add ctx parameters because proto definitions fix their signatures. Instead, read options.ctx, which RpcPeer populates via ContextRpcCodec with the caller's W3C trace context, and forward it to internal methods.

Should I pass ctx to setTimeout or scheduled async tasks?▼

No, detached async work like setTimeout, DeferredTask, and scheduleMicroTask should use the lifecycle context this._ctx from a Resource class. Capturing the caller's ctx risks using a disposed context whose span has already ended.

When should I not add a ctx parameter to a method?▼

Do not add ctx to public user-facing APIs, React components and hooks, proto-generated RPC signatures, pure local operations, leaf utility methods, or test helpers. Public APIs create Context.default() internally at the boundary.

What does trace.spanStart() return and why does it matter?▼

trace.spanStart() returns a derived Context carrying the new span on TRACE_SPAN_ATTRIBUTE. You must reassign ctx to this return value, otherwise downstream @trace.span() methods attach to the old parent and become siblings instead of children.

Related Skills

Explore More Software Engineering Skills→
AgentientAgentient
2

python-backend-opentelemetry-instrumentation

Instrument Python backend services with OpenTelemetry for distributed tracing.

Official
Advanced
githubnextgithubnext
5.1k

otel-queries

Analyze gh-aw OpenTelemetry traces from JSONL mirrors or OTLP backends.

Official
Intermediate
jagreehaljagreehal
3

pattern-enforcement

Enforce architectural boundaries and coding standards in TypeScript projects with ESLint.

Community
Intermediate
honeycombiohoneycombio
20

otel-migration

Guide phased OpenTelemetry retrofitting into existing uninstrumented applications.

Official
Advanced