# open-telemetry/opentelemetry-swift architecture

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

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

## Overview

##### Project type and purpose
- This is a multi‐module Swift client library for [OpenTelemetry](https://opentelemetry.io).
- It provides:
- OpenTelemetryApi – protocol definitions and no‐ops (the public API)
- OpenTelemetrySdk – reference implementation of the API (traces, metrics, logs)
- Instrumentation libraries (URLSession, NetworkStatus, SDKResourceExtension, SignPostIntegration)
- Exporters (Stdout, Jaeger, Zipkin, Prometheus, OTLP over gRPC/HTTP, Persistence)
- Importers (OpenTracingShim, SwiftMetricsShim)
- Contrib modules and language bridges (e.g. SwiftLog)

##### File structure
- Top‐level folders:
- Sources – holds each Swift module grouped by domain (Api, Sdk, Exporters, Importers, Instrumentation, Contrib, Bridges, Concurrency)
- Examples – standalone demo apps showing usage patterns
- Tests – per‐module automated tests
- Scripts – code‐generation, pre-commit hooks, semantic-convention template generation
- Key config: Package.swift (SwiftPM entry), .github/workflows (CI/CD), Makefile

##### Readme insights
- Clear separation of API vs SDK – applications and instrumentation libs depend only on APIs
- Supported telemetry signals: Traces (stable), Logs (beta), Metrics (functional but spec-draft)
- Export paths: external backends via exporters (OTLP, Jaeger, Zipkin, Prometheus, Persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    App["Example App"]:::app

    %% API Layer
    subgraph "API Module"
        Api["OpenTelemetryApi"]:::api
    end

    %% Instrumentation & Importers Layer
    subgraph "Instrumentation & Importers"
        URLSession["URLSessionInstrumentation"]:::instr
        NetworkStatus["NetworkStatus"]:::instr
        SDKResourceExtension["SDKResourceExtension"]:::instr
        SignPost["SignPostIntegration"]:::instr
        OpenTracingShim["OpenTracingShim"]:::importer
        SwiftMetricsShim["SwiftMetricsShim"]:::importer
    end

    %% SDK Core Layer
    subgraph "SDK Core"
        ResourceProvider["SDKResourceExtension"]:::sdk
        ContextManager["ContextManager"]:::sdk
        TracerProvider["TracerProvider"]:::sdk
        SpanProcessor["BatchSpanProcessor/SimpleSpanProcessor"]:::sdk
    end

    %% Exporters Layer
    subgraph "Exporters"
        Stdout["StdoutExporter"]:::exp
        Persistence["PersistenceExporter"]:::exp
        InMemory["InMemoryExporter"]:::exp
        Jaeger["JaegerExporter"]:::exp
        Zipkin["ZipkinExporter"]:::exp
        Prometheus["PrometheusExporter"]:::exp
        OTLPGrpc["OTLP gRPC Exporter"]:::exp
        OTLPHttp["OTLP HTTP Exporter"]:::exp
        Common["OTLP Common Utilities"]:::exp
    end

    %% External Systems
    subgraph "External Systems"
        JaegerAgent["Jaeger Agent"]:::external
        ZipkinCollector["Zipkin Collector"]:::external
        PromServer["Prometheus Server"]:::external
        OTLPCollector["OTLP Collector"]:::external
        FileSystem["Local File System"]:::external
    end

    %% Connections
    App -->|"uses"| Api
    URLSession --> Api
    NetworkStatus --> Api
    SDKResourceExtension --> Api
    SignPost --> Api
    OpenTracingShim --> Api
    SwiftMetricsShim --> Api

    Api -->|delegates to| TracerProvider
    TracerProvider -->|detects resources| ResourceProvider
    TracerProvider -->|manages context| ContextManager
    TracerProvider -->|provides tracer| SpanProcessor
    SpanProcessor -->|exports to| Stdout
    SpanProcessor -->|exports to| Persistence
    SpanProcessor -->|exports to| InMemory
    SpanProcessor -->|exports to| Jaeger
    SpanProcessor -->|exports to| Zipkin
    SpanProcessor -->|exports to| Prometheus
    SpanProcessor -->|exports to| OTLPGrpc
    SpanProcessor -->|exports to| OTLPHttp
    Common -.-> OTLPGrpc
    Common -.-> OTLPHttp

    Stdout -->|writes to| FileSystem
    Persistence -->|persists to| FileSystem
    Jaeger -->|sends to| JaegerAgent
    Zipkin -->|sends to| ZipkinCollector
    Prometheus -->|serves metrics to| PromServer
    OTLPGrpc -->|sends to| OTLPCollector
    OTLPHttp -->|sends to| OTLPCollector

    %% Click Events
    click Api "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/OpenTelemetryApi"
    click TracerProvider "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/OpenTelemetrySdk"
    click ResourceProvider "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Instrumentation/SDKResourceExtension"
    click URLSession "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Instrumentation/URLSession"
    click NetworkStatus "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Instrumentation/NetworkStatus"
    click SignPost "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Instrumentation/SignPostIntegration"
    click Stdout "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/Stdout"
    click Jaeger "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/Jaeger"
    click Zipkin "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/Zipkin"
    click Prometheus "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/Prometheus"
    click OTLPGrpc "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/OpenTelemetryProtocolGrpc"
    click OTLPHttp "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/OpenTelemetryProtocolHttp"
    click Persistence "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/Persistence"
    click Common "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/OpenTelemetryProtocolCommon"
    click InMemory "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Exporters/InMemory"
    click OpenTracingShim "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Importers/OpenTracingShim"
    click SwiftMetricsShim "https://github.com/open-telemetry/opentelemetry-swift/tree/main/Sources/Importers/SwiftMetricsShim"

    %% Styles
    classDef app fill:#e8f0fe,stroke:#1a73e8,color:#185abc
    classDef api fill:#e3f2fd,stroke:#42a5f5,color:#1e88e5
    classDef sdk fill:#e8f5e9,stroke:#66bb6a,color:#388e3c
    classDef instr fill:#f3e5f5,stroke:#ab47bc,color:#8e24aa
    classDef importer fill:#f3e5f5,stroke:#ab47bc,color:#8e24aa
    classDef exp fill:#fff3e0,stroke:#ffa726,color:#fb8c00
    classDef external fill:#eceff1,stroke:#90a4ae,color:#546e7a
```
