How open-telemetry/opentelemetry-js works
Main Components
• API Layer: Represent the core interfaces and types defined under directories such as “api” and in the packages (e.g., @opentelemetry/api in the “api” folder). This layer defines the contracts and no-op implementations for tracing, metrics, and logging.
• SDK Implementations: There are several SDKs for different runtimes. For example, “@opentelemetry/sdk-trace-base” in the core and SDK packages in the “packages” directory, as well as Node-specific SDKs (“@opentelemetry/sdk-trace-node”) and browser tracing (“@opentelemetry/sdk-trace-web”). Also, the metrics SDK is available under the packages.
• Context Management and Propagation: There are components for managing context (e.g., “context”, “AsyncHooksContextManager”, “ZoneContextManager”) and for propagating trace contexts (e.g., propagators like B3, W3CTraceContextPropagator) that ensure correct correlation between telemetry events.
• Semantic Conventions and Resources: The project includes semantic-conventions and resource modules that define standard attributes and resource detection mechanisms.
• Utility and Base Modules: A large part of the codebase (in both “packages” and “experimental”) consists of common utilities, aggregators, and exporter base implementations that provide low-level support functionality.
Relationships and Interactions
• At the top level, an application (or user code) integrates with the API. The API exposes methods for starting spans, recording metrics, and creating logs.
• The API then routes calls to the appropriate SDK implementation (for Node or web) which manages instrumentation.
• Instrumentation modules (auto or manual) “hook into” application libraries (HTTP, gRPC, etc.) and invoke the API methods to create telemetry data.
• The SDK layers “process” this telemetry data – for example applying sampling, context propagation, and span processing – and then hand it off to Exporters.
• Exporters are responsible for sending the processed telemetry data to external systems (e.g., telemetry backends, consoles, or even Prometheus).
Architectural Patterns and Design Principles
• Modularity: The project is divided into multiple independent packages (API, SDKs, instrumentations, exporters), which promotes separation of concerns.
• Extensibility via Instrumentation: Using auto-instrumentation and shims (such as the OpenTracing shim), the system is designed to work with existing libraries without coupling.
• Pluggability: Exporters and context managers can be configured at initialization to change how telemetry data is delivered or managed.
• Runtime Adaptability: Separate packages for Node and browser allow customized behavior depending on the environment’s requirements.
Relevant Technologies/Frameworks
• JavaScript/TypeScript, Node.js, and browser environments.
• The use of Node core modules like “process” and in Node SDK auto-instrumentation.
• Build, lint, and configuration files indicate that automated toolchains (e.g., ESLint, Prettier, TypeScript configurations) support the development process.