# vercel/otel architecture

> Architecture diagram of the GitHub repository vercel/otel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vercel/otel
- Repository: https://github.com/vercel/otel

## Overview

##### Main Components
- Packages:
- Instrumentation Core (packages/otel): This is the main package providing OpenTelemetry capabilities for Vercel.
- Alternative Implementation (packages/otelzero): A variant or lightweight version.
- Collector (packages/collector): Likely provides a way to collect or process traces/data.
- Bridge Emulator (packages/bridge-emulator): Emulates parts of the Vercel environment, probably for local testing or bridging server/client contexts.
- Shared configurations (packages/eslint-config and packages/typescript-config): These support code quality and consistency across the project.
- Sample Applications:
- apps/multiple-exporters and apps/sample: These are examples (possibly built with Next.js) demonstrating how to integrate and use the instrumentation libraries. Notice that each app includes API routes, middleware implementations, “edge” functions, and custom route handling.
- CI/CD and Testing Infrastructure:
- GitHub workflows (in .github/workflows) for linting, testing, release processes, etc.
- The tests directory provides end-to-end testing configurations and scripts for verifying deployment behavior on Vercel.

##### Component Relationships and Interactions
- The Sample Applications use the instrumentation libraries (from packages/otel and packages/otelzero) to implement distributed tracing and telemetry.
- The Collector package may interact with the instrumentation packages to collect and process telemetry data.
- The Bridge Emulator might simulate or emulate environments enabling developers or CI/CD pipelines to test how their services interact with Vercel telemetry hooks.
- CI/CD pipelines (GitHub workflows) are set up to run automated tests (unit, integration, and e2e) and enforce code quality, interacting with the testing suite in the tests directory.
- Shared configurations (ESLint/TypeScript) ensure consistency across all apps and packages.

##### Architectural Patterns & Design Principles
- Modular Monorepo Design: Different apps and libraries are organized into independent packages to ensure reusability and clear separation of concerns.
- Sample Driven Development: Inclusion of sample apps demonstrates usage patterns and provides examples for users integrating the OpenTelemetry for Vercel libraries.
- Edge Functionality: By having directories for “edge” functions (in API routes and middleware), the project emphasizes integration with Vercel’s edge networks.
- Test-Driven Integration: An organized e2e test suite enforces end-to-end functionality across different environments (e.g., when deployed on Vercel).

##### Essential Details
- Each major component should have a clear label (e.g., “Instrumentation Core (@vercel/otel)”, “Sample App – Multiple Exporters”, “Bridge Emulator”, etc.).
- Application code (sample apps),
- Core libraries/packages,
- Supporting infrastructure (CI/CD, tests),
- Configuration/shared utilities.
- Annotations or notes to components like "Middleware", "Edge Routes", etc., to indicate how these might be deployed on the Vercel platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo"
        subgraph "Packages"
            IC["Instrumentation Core (@vercel/otel)"]:::package
            Alt["Alternative Implementation (otelzero)"]:::package
            Coll["Collector"]:::package
            BE["Bridge Emulator"]:::package
            ESL["Shared ESLint Configuration"]:::config
            TS["Shared TypeScript Configuration"]:::config
        end

        subgraph "Sample Applications"
            MA["Sample Application – Multiple Exporters"]:::app
            SA["Sample Application – Sample"]:::app
        end

        subgraph "CI/CD and Testing"
            CD["CI/CD Pipelines"]:::infra
            E2E["End-to-End Testing Infrastructure"]:::infra
        end
    end

    %% Relationships between Sample Apps and Instrumentation Libraries
    MA -->|"uses"| IC
    SA -->|"uses"| IC
    MA -->|"uses"| Alt
    SA -->|"uses"| Alt

    %% Instrumentation libraries report telemetry to Collector
    IC -->|"reportsTelemetry"| Coll
    Alt -->|"reportsTelemetry"| Coll

    %% Bridge Emulator emulates environment for Sample Applications
    BE -->|"emulates"| MA
    BE -->|"emulates"| SA

    %% CI/CD pipelines trigger end-to-end tests that validate components
    CD -->|"triggers"| E2E
    E2E -->|"validates"| MA
    E2E -->|"validates"| SA
    E2E -->|"validates"| IC
    E2E -->|"validates"| Alt
    E2E -->|"validates"| Coll

    %% Shared configuration supports Packages and Sample Applications
    ESL ---|"supports"| IC
    ESL ---|"supports"| Alt
    ESL ---|"supports"| MA
    ESL ---|"supports"| SA
    TS ---|"supports"| IC
    TS ---|"supports"| Alt
    TS ---|"supports"| MA
    TS ---|"supports"| SA

    %% Click Events
    click IC "https://github.com/vercel/otel/tree/main/packages/otel"
    click Alt "https://github.com/vercel/otel/tree/main/packages/otelzero"
    click Coll "https://github.com/vercel/otel/tree/main/packages/collector"
    click BE "https://github.com/vercel/otel/tree/main/packages/bridge-emulator"
    click ESL "https://github.com/vercel/otel/tree/main/packages/eslint-config"
    click TS "https://github.com/vercel/otel/tree/main/packages/typescript-config"
    click MA "https://github.com/vercel/otel/tree/main/apps/multiple-exporters"
    click SA "https://github.com/vercel/otel/tree/main/apps/sample"
    click CD "https://github.com/vercel/otel/tree/main/.github/workflows"
    click E2E "https://github.com/vercel/otel/tree/main/tests/e2e"

    %% Styles
    classDef package fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef app fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef infra fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#F5CBA7,stroke:#9C640C,stroke-width:2px;
```
