GO — Healthy across all four use cases

• Last commit 2d ago
• 23+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Scorecard: known vulnerabilities detected (scored 0/10 by OpenSSF)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

OpenTelemetry JavaScript Client is the standardized API and SDK for instrumenting JavaScript/Node.js applications with distributed tracing, metrics, and logs. It provides the @opentelemetry/api package (public API) alongside SDK implementations in companion packages, enabling observability signal collection that integrates with backend systems like Jaeger, Zipkin, and Datadog. Monorepo structure: api/ contains the public API definitions (src/api/{trace,metrics,context,propagation,diag}.ts), sdk/ contains implementations, and packages/ contains instrumentation plugins for specific frameworks. Build outputs (TypeScript, ESM, ESNext) are split into build/{src,esm,esnext}/ directories. Testing uses Mocha + Karma for browser/Node/Worker compatibility. Each package is independently versioned and published to npm.

JavaScript/Node.js developers and DevOps engineers who need to add production observability to web applications and services. Library maintainers building instrumentations for popular frameworks (Express, Fastify, React, etc.) use this to provide zero-config tracing. Enterprise teams standardizing on OpenTelemetry across polyglot services rely on this for JavaScript alignment.

Actively maintained and approaching stability. The monorepo has 5M+ lines of TypeScript, comprehensive CI/CD with GitHub Actions (unit-test, e2e, benchmark, bundler-tests, backcompat workflows), and strong test coverage via nyc. The API package is at v1.9.1. Status badge shows 'beta', indicating stable API contracts but ongoing refinement; this is appropriate for an industry standard still solidifying across implementations.

Low-to-moderate risk: large dependency graph (typical for observability SDKs), but backed by CNCF governance and active community review. No single-maintainer risk due to OpenTelemetry steering committee oversight. Breaking changes are managed via semantic versioning and documented in CHANGELOG.md. Main risk is rapid iteration in experimental/ features and coupling to upstream OpenTelemetry specification changes.

The repo shows active development with workflows for continuous integration (unit-test.yml, e2e.yml, bundler-tests.yml), backcompat validation, and automated release management (create-or-update-release-pr.yml, publish-to-npm.yml). The presence of changelog.yml and version-update.js scripts indicates structured release processes. Experimental features are being validated via the api/src/experimental/ path and peer-api-check.js ensures API stability across package boundaries.

git clone https://github.com/open-telemetry/opentelemetry-js.git
cd opentelemetry-js
npm install
npm run compile  # Builds all packages: tsc --build tsconfig.json tsconfig.esm.json tsconfig.esnext.json
npm test         # Run Mocha tests via nyc
npm run test:browser  # Karma tests for browser environment

Daily commands: No running 'server' — this is a library. For development: npm run compile builds all targets, npm run watch enables incremental builds during development. For testing: npm test (Node), npm run test:browser (Chrome/Firefox via Karma), npm run test:webworker (Web Worker environment). See .mocharc.yml for test config and karma.conf.js for browser runner setup.

• api/src/index.ts — Main entry point exporting all public API surfaces (trace, metrics, context, propagation, diag, baggage).
• api/src/trace-api.ts — Core trace API initialization and global tracer provider management—foundational for all tracing instrumentation.
• api/src/context-api.ts — Context management API enabling async context propagation across all instrumentation domains.
• api/src/metrics-api.ts — Metrics API initialization defining meter provider and metric instrument interfaces.
• api/src/propagation-api.ts — Propagation API for distributed context and baggage transmission across process boundaries.
• api/src/diag-api.ts — Diagnostics API for internal OpenTelemetry logging and debugging.
• api/src/internal/global-utils.ts — Global singleton management utilities critical to API stability and versioning.

Add a New Trace Context Utility

1. Define the utility function in api/src/trace/context-utils.ts following existing patterns like getSpan() and setSpan() (api/src/trace/context-utils.ts)
2. Export the new utility from api/src/index.ts if it's public API, or keep internal to trace module (api/src/index.ts)
3. Add comprehensive JSDoc comments documenting parameters, return type, and usage examples (api/src/trace/context-utils.ts)

Add a New Metric Instrument Type

1. Define the instrument interface and methods in api/src/metrics/Metric.ts (e.g., ObservableCounter) (api/src/metrics/Metric.ts)
2. Add the factory method to the Meter interface in api/src/metrics/Meter.ts (e.g., createObservableCounter()) (api/src/metrics/Meter.ts)
3. Add a corresponding no-op implementation in api/src/metrics/NoopMeter.ts (api/src/metrics/NoopMeter.ts)
4. Export the new types from api/src/index.ts (api/src/index.ts)

Add a New Sampler Decision Type

1. Extend the SamplingDecision enum in api/src/trace/SamplingResult.ts with the new decision value (api/src/trace/SamplingResult.ts)
2. Document the new decision in JSDoc comments explaining when and why it should be used (api/src/trace/SamplingResult.ts)
3. Create example sampler implementations in documentation or update api/src/trace/Sampler.ts with guidance (api/src/trace/Sampler.ts)

Add a New Baggage Metadata Field

1. Extend the BaggageEntryMetadata interface in api/src/baggage/types.ts with the new property (api/src/baggage/types.ts)
2. Update the baggage implementation in api/src/baggage/internal/baggage-impl.ts to handle the new field (api/src/baggage/internal/baggage-impl.ts)
3. Update helper utilities in api/src/baggage/utils.ts if parsing/serialization is needed (api/src/baggage/utils.ts)
4. Export updated types from api/src/index.ts if public (api/src/index.ts)

• TypeScript — Provides type safety across distributed instrumentation and SDK implementations, critical for a public API surface.
• Singleton pattern for global APIs — Ensures single TracerProvider, MeterProvider, etc. across the entire application, allowing SDKs to register once.
• No-op implementations (NoopTracer, NoopMeter) — Zero-cost abstraction when instrumentation is disabled, preventing performance overhead in unsampled traces.
• Context as immutable key-value store — Enables safe propagation through async boundaries without shared mutable state.
• Text-based propagators (TextMapPropagator) — Supports diverse transport protocols (HTTP headers, message metadata, etc.) for distributed tracing.

• API only defines interfaces; SDKs implement actual instrumentation

  • Why: Decouples telemetry definition from collection, allowing multiple competing SDK implementations.
  • Consequence: Users must install both @opentelemetry/api and an SDK (e.g., @opentelemetry/sdk-node); confusion if SDK is missing.

• Global singleton providers (trace.getTracerProvider())

  • Why: Single initialization point simplifies application code; automatic context propagation.
  • Consequence: Not testable in parallel; requires careful test isolation and global state reset between tests.

• Span sampling at tracer level, not at creation

  • Why: Reduces overhead for high-cardinality trace IDs; sampling decision made before span
  • Consequence: undefined

Multi-target compilation: TypeScript compiles to three targets (CommonJS, ESM, ESNext) via separate tsconfigs; npm run compile must finish before npm test works. Context is async-aware: the Context API uses AsyncLocalStorage (Node 13+) which has subtle semantics around async_hooks; test failures can appear flaky if context isolation is incomplete. Experimental APIs: anything under api/src/experimental/ can break between minor versions — do not depend on it in production. Peer API enforcement: npm run peer-api-check validates that all packages export compatible APIs; if skipped, downstream users may encounter unexpected version conflicts. dpdm cycle check: npm run cycle-check enforces acyclic imports from src/index.ts; circular dependencies silently break tree-shaking.

• Trace Context Propagation — Distributed tracing requires passing context (trace ID, span ID, flags) across service boundaries; the propagation API (api/src/api/propagation.ts) implements standards like W3C Trace Context that this SDK uses to correlate requests across services.
• AsyncLocalStorage and Async Context Isolation — JavaScript is single-threaded with async concurrency; the Context API uses AsyncLocalStorage to automatically isolate trace context per async task, preventing context leaks between concurrent requests in the same process.
• Plugin/Instrumentation Architecture — Rather than modifying framework source code, OpenTelemetry provides patches via require-time instrumentation modules; this design allows zero-config tracing and framework updates without breaking observability.
• Carrier Propagation (HTTP Headers, Message Metadata) — Context must be serialized into request/message metadata for cross-service propagation; the Propagator interface handles extraction and injection of trace context into arbitrary carrier formats.
• Dual CommonJS/ESM Build Targets — JavaScript ecosystem spans Node.js (CommonJS-first), bundlers (ESM-preferred), and legacy browsers; the build system (three tsconfig files) produces compatible outputs for all, enabling this SDK to work in web, Node, and Worker environments.
• Baggage (Trace Metadata Context) — Beyond trace context, OpenTelemetry allows passing application-level metadata (baggage) across service boundaries; the API abstracts baggage propagation separately from trace context, enabling feature flags, tenant IDs, and user context to flow without being part of the critical trace.
• Circular Dependency Detection (dpdm) — The monorepo enforces acyclic imports via dpdm to ensure tree-shakability and prevent dead-code elimination failures in consuming bundles; npm run cycle-check is required before merging to maintain library performance characteristics.

• open-telemetry/opentelemetry-python — Python reference implementation of the same OpenTelemetry specification; useful for comparing API design decisions and understanding specification intent.
• open-telemetry/opentelemetry-go — Go implementation; establishes the canonical trace context semantics and propagation formats that the JS SDK must align with.
• open-telemetry/opentelemetry-js-contrib — Companion repository containing community-maintained instrumentations for Express, Fastify, Nest.js, AWS SDK, and others — primary consumer of this core API/SDK.
• open-telemetry/semantic-conventions — Shared specification for trace attribute names, metric units, and event semantics — referenced by all SDK implementations including this one.
• open-telemetry/opentelemetry-specification — Canonical specification document that defines the API contracts, context propagation, and requirements that this codebase implements.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for baggage context helpers (api/src/baggage/context-helpers.ts)

The baggage context helpers module lacks visible test coverage in the file structure. Given that baggage is a critical OpenTelemetry feature for propagating key-value pairs across service boundaries, comprehensive tests for context-helpers.ts would ensure reliability. This includes edge cases like empty baggage, invalid characters, and context isolation scenarios.

• [ ] Create test/baggage/context-helpers.test.ts with tests for all exported functions
• [ ] Add tests for baggage creation, retrieval, and modification in different context states
• [ ] Test error handling for malformed baggage entries
• [ ] Add tests ensuring baggage doesn't leak between concurrent contexts
• [ ] Verify compatibility with both Node.js and browser environments via karma tests

Implement missing W3C Baggage specification compliance tests

The repo has a w3c-integration-test.yml workflow, but the baggage utilities (api/src/baggage/utils.ts) need explicit W3C Baggage spec compliance tests. The W3C spec defines serialization/deserialization requirements that should be validated against the official test suite to ensure interoperability with other OpenTelemetry implementations.

• [ ] Review W3C Baggage specification (https://www.w3.org/TR/baggage/)
• [ ] Add test/baggage/w3c-compliance.test.ts for spec-mandated serialization formats
• [ ] Test property list parsing with various delimiters and encoding edge cases
• [ ] Validate metadata handling (with/without quotes and special characters)
• [ ] Create reference vectors for common baggage headers and verify round-trip serialization

Add diagnostic logger tests for diag module (api/src/diag/)

The diagnostics API (api/src/diag/ComponentLogger.ts and consoleLogger.ts) is critical for internal OpenTelemetry debugging but appears to lack comprehensive unit tests. The diag-api.ts is the primary diagnostic entry point that many components depend on, making robust logging tests essential for maintainability.

• [ ] Create test/diag/component-logger.test.ts testing log level filtering and message formatting
• [ ] Create test/diag/console-logger.test.ts verifying console output behavior across different log levels
• [ ] Add tests for diag-api.ts initialization and logger registration/deregistration
• [ ] Test that diagnostic logs don't interfere with normal telemetry collection
• [ ] Validate browser compatibility (ensure console.log patterns work in karma tests)

• Add TypeScript strict null checks to api/src/api/diag.ts (diagnostics API) — currently missing in several diagnostic helper methods and would improve type safety for instrumentation package developers.
• Write integration tests for W3C Trace Context propagation in sdk/src/propagator/ covering edge cases like multiple trace-parent headers and trace-state validation — current test coverage has gaps for malformed inputs.
• Document the AsyncLocalStorage vs WeakMap trade-off in api/src/api/context.ts with concrete examples showing when each is used — new contributors are confused about context scoping in browser vs Node environments.

The OpenTelemetry JavaScript API package demonstrates good security practices with comprehensive CI/CD workflows (CodeQL analysis, SBOM generation, OSSF scorecard checks, dependency scanning via FOSSA). However, three low-severity issues were identified: (1) outdated minimum Node.js version requirement allowing unmaintained 8.x runtimes, (2) unclear SBOM distribution in npm packages, and (3) incomplete package.json files configuration. No critical vulnerabilities, hardcoded secrets, injection risks, or infrastructure misconfigurations were detected. The project follows security best practices with multiple automated security checks in place. Recommend updating Node.js engine requirements and completing the package distribution configuration.

• Low · Overly Permissive Node Engine Specification — api/package.json - engines field. The package.json specifies 'engines': { 'node': '>=8.0.0' }, allowing Node.js versions 8.x and older. Node.js 8 reached end-of-life in December 2019 and no longer receives security updates. This allows the package to be installed and used with unmaintained, vulnerable runtime environments. Fix: Update the minimum Node.js version requirement to at least 16.x (current LTS) or 18.x. Use 'node': '>=16.0.0' to ensure users have access to recent security patches and features.
• Low · Missing SBOM Generation Verification — api/package.json - files field (incomplete). The codebase includes a .github/workflows/sbom.yml workflow for Software Bill of Materials generation, but there's no evidence of SBOM distribution in the npm package configuration. The 'files' array in package.json appears truncated and may not include SBOM artifacts, making it difficult for downstream consumers to verify dependencies. Fix: Ensure SBOM files (in CycloneDX or SPDX format) are generated and included in the npm package distribution. Add SBOM files to the 'files' array in package.json and verify they're properly generated during the build process.
• Low · Incomplete Package.json Configuration — api/package.json - files field. The 'files' array in package.json appears to be truncated (ends with 'build/src//*), which may result in incomplete package distribution. This could lead to missing type definitions or source maps needed for security auditing and debugging. Fix: Complete the 'files' array to include all necessary distribution files: build artifacts, type definitions (.d.ts), source maps (.js.map), and LICENSE. Verify the complete configuration is: ['build/esm//.js', 'build/esm/**/.js.map', 'build/esm//*.d.ts', 'build/esnext//.js', 'build/esnext/**/.js.map', 'build/esnext//*.d.ts', 'build/src//.js', 'build/src/**/.js.map', 'build/src/**/*.d.ts', 'LICENSE']

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Read in the suggested order before editing unfamiliar code. The reading-order list is computed from the actual import graph, not LLM guesses; reading bottom-up materially reduces wrong-edit risk.
3. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
4. Cite source on changes. When proposing an edit, cite the specific path/to/file.ext:Lstart-Lend you're reasoning about, the same way RepoPilot's own RAG cites code in https://repopilot.app/r/open-telemetry/opentelemetry-js.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live open-telemetry/opentelemetry-js repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/open-telemetry/opentelemetry-js.

What it runs against: a local clone of open-telemetry/opentelemetry-js — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in open-telemetry/opentelemetry-js | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of open-telemetry/opentelemetry-js. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/open-telemetry/opentelemetry-js.git
#   cd opentelemetry-js
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of open-telemetry/opentelemetry-js and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "open-telemetry/opentelemetry-js(\\.git)?\\b" \\
  && ok "origin remote is open-telemetry/opentelemetry-js" \\
  || miss "origin remote is not open-telemetry/opentelemetry-js (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "api/src/index.ts" \\
  && ok "api/src/index.ts" \\
  || miss "missing critical file: api/src/index.ts"
test -f "api/src/trace-api.ts" \\
  && ok "api/src/trace-api.ts" \\
  || miss "missing critical file: api/src/trace-api.ts"
test -f "api/src/context-api.ts" \\
  && ok "api/src/context-api.ts" \\
  || miss "missing critical file: api/src/context-api.ts"
test -f "api/src/metrics-api.ts" \\
  && ok "api/src/metrics-api.ts" \\
  || miss "missing critical file: api/src/metrics-api.ts"
test -f "api/src/propagation-api.ts" \\
  && ok "api/src/propagation-api.ts" \\
  || miss "missing critical file: api/src/propagation-api.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/open-telemetry/opentelemetry-js"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Computed from the actual import graph (no LLM). Read in this order to learn the codebase from the foundation up — each step builds on the previous ones.

1. api/src/context/types.ts — Foundation: doesn't import anything internally and is imported by 14 other files. Read first to learn the vocabulary.
2. eslint.base.js — Foundation: imported by 11, no internal dependencies of its own.
3. api/src/trace/span_context.ts — Built on the foundation; imported by 7 downstream files.
4. api/src/trace/attributes.ts — Built on the foundation; imported by 5 downstream files.
5. experimental/packages/api-logs/src/types/Logger.ts — Layer 2 — composes lower-level code into reusable abstractions (imported 6×).
6. api/src/trace/span.ts — Layer 3 — composes lower-level code into reusable abstractions (imported 6×).
7. api/src/trace/tracer.ts — Layer 4 — composes lower-level code into reusable abstractions (imported 6×).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.