# grafana/otel-profiling-java architecture

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

- Interactive diagram: https://gitdiagram.com/grafana/otel-profiling-java
- Repository: https://github.com/grafana/otel-profiling-java

## Overview

##### Project type and purpose
- This is an open-source Java library (not a standalone app) whose purpose is to integrate Pyroscope’s CPU profiler with any Java application using the OpenTelemetry (OTel) standard.

##### File structure
- Top-level build files: build.gradle, Gradle wrapper, Makefile, GitHub workflows → indicates a Gradle-based Java library with CI for testing & releases.
- src/main/java/io/otel/pyroscope → core bridge code:
- OtelCompat.java
- OtelProfilerSdkBridge.java
- PyroscopeOtelAutoConfigurationCustomizerProvider.java (SPI entry)
- PyroscopeOtelConfiguration.java
- PyroscopeOtelSpanProcessor.java
- src/main/resources/META-INF/services → declares the AutoConfigurationCustomizerProvider service so that OTel’s SDK-autoconfigure picks up this extension.
- src/test/java → unit tests for the SpanProcessor.

##### README for additional insights
- References the OpenTelemetry Java instrumentation guide and points to a full example in another repo.

##### Elements
- “Profiles → Bridge → Pyroscope Server”
- “Traces → OTel Exporter → Tracing Backend”
- Application vs. Library vs. External Service
- Data paths (traces vs. profiling)
- Notes or callouts for the SPI registration (META-INF/services) and the sampling rate caveat (~100Hz).

##### Final recommendations
- Be very detailed: capture both the startup/registration sequence (SPI auto-configure) and the run-time data-flow (span begin/end, sample tagging, export).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        App["Java Application"]:::app
    end

    %% OTel SDK & Auto-Configuration Layer
    subgraph "OTel SDK & Auto-Configuration" 
        direction TB
        SDK["OpenTelemetry Java SDK"]:::library
        MetaInf["SPI Declaration\n(META-INF/services)"]:::config
        AutoConfig["AutoConfigurationCustomizerProvider"]:::library
    end

    %% Pyroscope-OTel Bridge Library
    subgraph "Pyroscope-OTel Bridge Library" 
        direction TB
        Compat["OtelCompat"]:::library
        Config["PyroscopeOtelConfiguration"]:::config
        SpanProc["PyroscopeOtelSpanProcessor"]:::processor
        Bridge["OtelProfilerSdkBridge"]:::bridge
    end

    %% Profiling & Tracing Agents and Exporters
    subgraph "Runtime Agents & Exporters"
        direction TB
        Profiler["Pyroscope Profiler Agent\n(JVM sampling ~100Hz)"]:::agent
        OTelExp["OTel Trace Exporter\n(e.g., OTLP)"]:::exporter
        PyroExp["Pyroscope Exporter\n(HTTP/gRPC)"]:::exporter
    end

    %% Backends
    subgraph "Backends"
        direction TB
        TracingBackend["Tracing Backend\n(Jaeger/Tempo)"]:::external
        PyroscopeServer["Pyroscope Server"]:::external
    end

    %% Connections
    App -->|uses| SDK
    SDK -->|scans SPI| MetaInf
    MetaInf -->|registers| AutoConfig
    AutoConfig -->|installs| SpanProc
    SDK -->|span start/end| SpanProc
    SpanProc -->|tags samples| Bridge
    Compat --> Bridge
    Config --> Bridge

    Profiler -->|samples CPU stacks| Bridge
    Bridge -->|ProfileSample + spanID| PyroExp
    PyroExp -->|sends profiles| PyroscopeServer

    SDK -->|SpanContext| OTelExp
    OTelExp -->|sends traces| TracingBackend

    %% Unit Tests
    Test["SpanProcessor Unit Tests"]:::test --> SpanProc

    %% Click events
    click Bridge "https://github.com/grafana/otel-profiling-java/blob/main/src/main/java/io/otel/pyroscope/OtelProfilerSdkBridge.java"
    click SpanProc "https://github.com/grafana/otel-profiling-java/blob/main/src/main/java/io/otel/pyroscope/PyroscopeOtelSpanProcessor.java"
    click Config "https://github.com/grafana/otel-profiling-java/blob/main/src/main/java/io/otel/pyroscope/PyroscopeOtelConfiguration.java"
    click AutoConfig "https://github.com/grafana/otel-profiling-java/blob/main/src/main/java/io/otel/pyroscope/PyroscopeOtelAutoConfigurationCustomizerProvider.java"
    click Compat "https://github.com/grafana/otel-profiling-java/blob/main/src/main/java/io/otel/pyroscope/OtelCompat.java"
    click MetaInf "https://github.com/grafana/otel-profiling-java/blob/main/src/main/resources/META-INF/services/io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider"
    click Test "https://github.com/grafana/otel-profiling-java/blob/main/src/test/java/io/otel/pyroscope/PyroscopeOtelSpanProcessorTest.java"

    %% Styles
    classDef app fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef library fill:#F3E5F5,stroke:#9C27B0,color:#4A148C
    classDef config fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef processor fill:#E8F5E9,stroke:#43A047,color:#1B5E20
    classDef bridge fill:#E1F5FE,stroke:#0288D1,color:#01579B
    classDef agent fill:#FFFDE7,stroke:#FDD835,color:#F57F17
    classDef exporter fill:#FCE4EC,stroke:#D81B60,color:#880E4F
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#263238
    classDef test fill:#FFEBEE,stroke:#E53935,color:#B71C1C
```
