Project setup

1. Copy the source/ directory into your project root (e.g., ./otel-source/).
2. Install dependencies listed above via npm.
3. Extend your tsconfig.json from the provided base:

   {
     "extends": "./otel-source/tsconfig.base.json",
     "compilerOptions": {
       "outDir": "./dist",
       "rootDir": "./src"
     }
   }
   

4. For ESM output, use tsconfig.base.esm.json instead.
5. Set the OTLP exporter endpoint via environment variable before starting your process:

   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
   OTEL_SERVICE_NAME=my-service
   

6. Register your SDK providers at application startup (before any other imports that may use the API) - see examples below.
7. For browser bundling, copy the relevant bundler-tests/browser/webpack-5/ webpack config as a starting point.

Public API

DiagConsoleLogger

import { DiagConsoleLogger, diag, DiagLogLevel } from '@opentelemetry/api';

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);

A built-in diagnostic logger that writes OpenTelemetry internal messages to console. Use it during development to debug SDK initialization, exporter connectivity, and instrumentation registration. Pass a DiagLogLevel to control verbosity.

createContextKey

import { createContextKey, ROOT_CONTEXT } from '@opentelemetry/api';

const MY_KEY = createContextKey('my-service.myKey');
const ctx = ROOT_CONTEXT.setValue(MY_KEY, 'some-value');
const value = ctx.getValue(MY_KEY); // 'some-value'

Creates an immutable, unique key for storing typed values inside an OpenTelemetry Context. Use it when you need to propagate request-scoped data (user IDs, tenant IDs, feature flags) alongside traces without polluting global state.

ValueType

import { ValueType } from '@opentelemetry/api';

meter.createHistogram('http.request.duration', {
  description: 'HTTP request latency',
  unit: 'ms',
  valueType: ValueType.DOUBLE,
});

Enum with values INT and DOUBLE that controls how metric values are recorded and exported. Use ValueType.INT for counters and ValueType.DOUBLE for measurements that require fractional precision.

wrapTracer / SugaredTracer (experimental)

import { wrapTracer } from '@opentelemetry/api/experimental';
import { trace } from '@opentelemetry/api';

const tracer = wrapTracer(trace.getTracer('my-service', '1.0.0'));
await tracer.withActiveSpan('my-operation', async (span) => {
  // span is active for the duration of the callback
});

wrapTracer returns a SugaredTracer that adds convenience methods (withActiveSpan, startActiveSpan variants) on top of the standard Tracer. Useful for reducing boilerplate when you always want a span active for the duration of an async callback. The experimental sub-path export may change between minor versions.

Working examples

Scenario - Bootstrap tracing for a Node.js Express server

Configure a BasicTracerProvider with an OTLP HTTP exporter at application startup, before requiring Express or any business logic.

import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { W3CTraceContextPropagator } from '@opentelemetry/core';

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.WARN);

const exporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318/v1/traces',
});

const provider = new BasicTracerProvider({
  // resource and sampler options go here
});

provider.addSpanProcessor(
  // BatchSpanProcessor from @opentelemetry/sdk-trace-base
  new (require('@opentelemetry/sdk-trace-base').BatchSpanProcessor)(exporter)
);
provider.register({
  propagator: new W3CTraceContextPropagator(),
});

Scenario - Emit structured log records

Use the Logs API and SDK to emit structured log records that are correlated with active trace context.

import { logs } from '@opentelemetry/api-logs';
import { LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';

const loggerProvider = new LoggerProvider();
loggerProvider.addLogRecordProcessor(
  new SimpleLogRecordProcessor(new OTLPLogExporter())
);
logs.setGlobalLoggerProvider(loggerProvider);

const logger = logs.getLogger('my-service', '1.0.0');
logger.emit({
  body: 'User signed in',
  attributes: { 'user.id': '42', 'user.role': 'admin' },
});

Scenario - Record metrics with a histogram

Create a MeterProvider, register it globally, and record HTTP latency measurements.

import { metrics, ValueType } from '@opentelemetry/api';
import { MeterProvider } from '@opentelemetry/sdk-metrics';
import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';

const meterProvider = new MeterProvider({
  readers: [
    new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter(),
      exportIntervalMillis: 15000,
    }),
  ],
});
metrics.setGlobalMeterProvider(meterProvider);

const meter = metrics.getMeter('http-server', '1.0.0');
const latency = meter.createHistogram('http.server.duration', {
  unit: 'ms',
  valueType: ValueType.DOUBLE,
});

// In your request handler:
const start = Date.now();
// ... handle request ...
latency.record(Date.now() - start, { 'http.method': 'GET', 'http.status_code': 200 });

File walkthrough

• .github/ - Contains all GitHub Actions CI workflows (unit tests, lint, publish, bundler tests, e2e, W3C integration) and issue/PR templates.
• api/ - Self-contained @opentelemetry/api package. All stable API contracts (tracing, metrics, context, baggage, diagnostics) live here; application code should depend only on this package at runtime.
• bundler-tests/ - Smoke-test entry points for Webpack 4/5 (browser and Node) that verify all SDK packages can be bundled together without errors.
• doc/ - Architecture decision records and contributor documentation not published to npm.
• e2e-tests/ - Full end-to-end test scenarios run against a live collector.
• examples/ - Standalone runnable demos (HTTP server, gRPC, Prometheus, etc.).
• experimental/ - Packages under active development with no stability guarantees; includes the SugaredTracer helper.
• integration-tests/ - Tests that verify backwards compatibility between API and SDK versions.
• packages/ - All stable SDK packages (sdk-trace-base, sdk-metrics, sdk-logs, core, exporters, propagators, resources, etc.).
• scripts/ - Release scripting, changelog generation, and monorepo maintenance utilities.
• semantic-conventions/ - Type-safe constants for OTel semantic conventions (attribute names, etc.).
• tsconfig.base.json / tsconfig.base.esm.json / tsconfig.base.esnext.json - Shared TypeScript compiler options extended by each package.
• lerna.json / nx.json - Monorepo orchestration: versioning, task caching, and pipeline dependencies.

Common pitfalls and fixes

• Provider registered after first use: The global trace/metrics/logs API returns a no-op if accessed before provider.register() is called. Fix: import and register providers in a dedicated instrumentation.ts file that is the very first import in index.ts.
• ESM/CJS interop with @opentelemetry/api: Some bundlers resolve both the CJS and ESM copy, creating two separate API singletons. Fix: add resolve.alias in webpack or moduleNameMapper in Jest to force a single copy of @opentelemetry/api.
• OTEL_EXPORTER_OTLP_ENDPOINT includes /v1/traces suffix: The OTLP HTTP exporter appends the signal path automatically. Fix: set the base URL only (e.g., http://localhost:4318), not http://localhost:4318/v1/traces.
• Experimental sub-path import failing in older Node: @opentelemetry/api/experimental requires Node 12+ exports field support. Fix: ensure "moduleResolution": "node16" or "bundler" in tsconfig.json.
• DiagLogLevel not imported when calling diag.setLogger: The second argument is required to activate logging; omitting it defaults to NONE. Fix: always pass DiagLogLevel.DEBUG or DiagLogLevel.INFO explicitly.
• Missing @types/node for Node.js SDK packages: Several SDK packages reference Node built-ins. Fix: npm install --save-dev @types/node and add "types": ["node"] to tsconfig.json.

Vibe-coding prompt template

I have the OpenTelemetry JS SDK monorepo source in the `source/` directory of
this project, and a usage guide at `USAGE.md`. The upstream npm package is
`user@example.com` (open-telemetry/opentelemetry-js on GitHub).

Please help me integrate OpenTelemetry into my existing Node.js TypeScript
project step by step:

1. Read `USAGE.md` and the relevant files under `source/api/src/` and
   `source/packages/` to understand the real exported symbols and types.
2. Create a `src/instrumentation.ts` file that initialises a
   BasicTracerProvider (with OTLP HTTP exporter), a MeterProvider (with
   PeriodicExportingMetricReader), and a LoggerProvider (with
   SimpleLogRecordProcessor). Register all three global providers.
3. Update `src/index.ts` to import `./instrumentation` as the very first line.
4. Add a typed helper that wraps an Express request handler in an active span,
   using only the real exports visible in `USAGE.md`.
5. Show the required `tsconfig.json` changes and environment variables.
6. Do not invent any API symbols - use only names documented in `USAGE.md`.

License and credit

The source is licensed under the Apache License 2.0. See source/LICENSE for the full text.

Upstream project: open-telemetry/opentelemetry-js, published on npm as @opentelemetry/api and related scoped packages.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。