# open-telemetry/opentelemetry-js architecture

> Architecture diagram of the GitHub repository open-telemetry/opentelemetry-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-telemetry/opentelemetry-js
- Repository: https://github.com/open-telemetry/opentelemetry-js

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application Code"]:::external

    subgraph "Core API Layer"
        TAPI["Telemetry API"]:::api
    end

    subgraph "SDK Implementations"
        NodeSDK["Node SDK"]:::sdk
        BrowserSDK["Browser SDK"]:::sdk
        BaseTrace["Base Tracing SDK"]:::sdk
        MetricsSDK["Metrics SDK"]:::sdk
        LoggingSDK["Logging SDK"]:::sdk
    end

    subgraph "Instrumentation Modules"
        HTTPInst["HTTP Instrumentation"]:::instr
        GrpcInst["gRPC Instrumentation"]:::instr
        FetchInst["Fetch Instrumentation"]:::instr
        XHRInst["XML HTTP Request Instrumentation"]:::instr
    end

    subgraph "Context Management and Propagation"
        APIContext["API Context Manager"]:::context
        AsyncHooks["AsyncHooks Context Manager"]:::context
        ZoneContext["Zone Context Manager"]:::context
    end

    subgraph "Semantic & Resources"
        Semantic["Semantic Conventions"]:::resource
        Resources["Resources"]:::resource
    end

    subgraph "Utility Modules"
        Utility["Utility Modules"]:::utility
    end

    subgraph "Exporters"
        subgraph "Tracing Exporters"
            JaegerExp["Jaeger Exporter"]:::exporter
            ZipkinExp["Zipkin Exporter"]:::exporter
        end
        subgraph "Metrics & Logs Exporters"
            MetricsOTLPHTTP["OTLP HTTP Metrics Exporter"]:::exporter
            MetricsOTLPGRPC["OTLP gRPC Metrics Exporter"]:::exporter
            LogsOTLPHTTP["OTLP HTTP Logs Exporter"]:::exporter
            LogsOTLPGRPC["OTLP gRPC Logs Exporter"]:::exporter
        end
    end

    External["Backends/External Systems"]:::external

    %% Data Flow Connections
    A -->|"invokes"| TAPI

    %% Instrumentation hooks into API
    HTTPInst -->|"instruments"| TAPI
    GrpcInst -->|"instruments"| TAPI
    FetchInst -->|"instruments"| TAPI
    XHRInst -->|"instruments"| TAPI

    %% API routes calls to SDK Implementations
    TAPI -->|"routes"| NodeSDK
    TAPI -->|"routes"| BrowserSDK
    TAPI -->|"routes"| BaseTrace
    TAPI -->|"routes"| MetricsSDK
    TAPI -->|"routes"| LoggingSDK

    %% SDK Processing to Exporters
    NodeSDK -->|"processes"| JaegerExp
    NodeSDK -->|"processes"| ZipkinExp
    BrowserSDK -->|"processes"| JaegerExp
    BrowserSDK -->|"processes"| ZipkinExp
    BaseTrace -->|"processes"| JaegerExp
    BaseTrace -->|"processes"| ZipkinExp
    MetricsSDK -->|"processes"| MetricsOTLPHTTP
    MetricsSDK -->|"processes"| MetricsOTLPGRPC
    LoggingSDK -->|"processes"| LogsOTLPHTTP
    LoggingSDK -->|"processes"| LogsOTLPGRPC

    %% Exporters push data to External Systems
    JaegerExp -->|"exports"| External
    ZipkinExp -->|"exports"| External
    MetricsOTLPHTTP -->|"exports"| External
    MetricsOTLPGRPC -->|"exports"| External
    LogsOTLPHTTP -->|"exports"| External
    LogsOTLPGRPC -->|"exports"| External

    %% Context Management Associations
    APIContext -->|"manages"| TAPI
    AsyncHooks -->|"supports"| NodeSDK
    ZoneContext -->|"supports"| NodeSDK

    %% Semantic & Resources influences API Layer
    Semantic -->|"defines"| TAPI
    Resources -->|"defines"| TAPI

    %% Utility Modules support SDK implementations
    Utility -->|"supports"| NodeSDK
    Utility -->|"supports"| BaseTrace

    %% Click Events
    click TAPI "https://github.com/open-telemetry/opentelemetry-js/tree/main/api/src/api/"
    click NodeSDK "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-node/"
    click BrowserSDK "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-web/"
    click BaseTrace "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-base/"
    click MetricsSDK "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/sdk-metrics/"
    click LoggingSDK "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/sdk-logs/"
    click HTTPInst "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http/"
    click GrpcInst "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc/"
    click FetchInst "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-fetch/"
    click XHRInst "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-xml-http-request/"
    click JaegerExp "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-exporter-jaeger/"
    click ZipkinExp "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-exporter-zipkin/"
    click MetricsOTLPHTTP "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-exporter-metrics-otlp-http/"
    click MetricsOTLPGRPC "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-exporter-metrics-otlp-grpc/"
    click LogsOTLPHTTP "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-logs-otlp-http/"
    click LogsOTLPGRPC "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/exporter-logs-otlp-grpc/"
    click APIContext "https://github.com/open-telemetry/opentelemetry-js/tree/main/api/src/context/"
    click AsyncHooks "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-async-hooks/"
    click ZoneContext "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-zone/"
    click Semantic "https://github.com/open-telemetry/opentelemetry-js/tree/main/semantic-conventions/"
    click Resources "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-resources/"
    click Utility "https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-core/"

    %% Styles
    classDef api fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef sdk fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef instr fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef exporter fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef external fill:#f7cac9,stroke:#333,stroke-width:2px;
    classDef context fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef resource fill:#fcf3cf,stroke:#333,stroke-width:2px;
    classDef utility fill:#d6eaf8,stroke:#333,stroke-width:2px;
```
