# open-telemetry/opentelemetry-go-compile-instrumentation architecture

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

- Interactive diagram: https://gitdiagram.com/open-telemetry/opentelemetry-go-compile-instrumentation
- Repository: https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation

## Overview

otelc is a Go compile-time OpenTelemetry instrumentation tool: a developer prefixes a Go build with otelc, which configures and transforms the build so instrumentation is injected without application-source edits. Its runtime product includes the transformation engine, shared runtime setup, and hooks for supported libraries and protocols. The README documents the user workflow and broad capabilities; source-index references support the internal links shown here. Several integration directories are represented as subsystems because their individual source was not sampled.

Main entry points: [`pkg/runtime/setup.go`](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/pkg/runtime/setup.go) (Runtime setup), [`pkg/hook/context.go`](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/pkg/hook/context.go) (Hook context), [`tool/internal/setup/setup.go`](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/setup/setup.go) (Build setup), [`tool/internal/instrument/trampoline.go`](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/instrument/trampoline.go) (Code transformer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Build entry"]
  node_otelc["otelc CLI<br/>[main.go]"]
end

subgraph group_engine["Instrumentation engine"]
  node_setup["Build setup<br/>[setup.go]"]
  node_rules["Instrumentation rules"]
  node_ast["Go AST parser<br/>[parser.go]"]
  node_transform["Code transformer<br/>[trampoline.go]"]
  node_go_util["Go build utilities<br/>[go.go]"]
end

subgraph group_runtime["Shared runtime"]
  node_runtime_setup["Runtime setup<br/>[setup.go]"]
  node_hook_context["Hook context<br/>[context.go]"]
end

subgraph group_integrations["Library instrumentation"]
  node_db_sql["SQL database hooks<br/>[client.go]"]
  node_linode["Linode API hooks<br/>[v2]"]
  node_redis["Redis hooks<br/>[client_hook.go]"]
  node_mongodb["MongoDB hooks<br/>[client_hook.go]"]
  node_other_integrations["Other library hooks"]
  node_kubernetes["Kubernetes hooks<br/>[client-go]"]
end

subgraph group_protocols["Protocol instrumentation"]
  node_grpc_client["gRPC client hooks<br/>[client_hook.go]"]
  node_grpc_server["gRPC server hooks<br/>[server_hook.go]"]
  node_http_client["HTTP client hooks<br/>[client_hook.go]"]
  node_http_server["HTTP server hooks"]
end

node_developer(("Go developer"))

node_developer -->|"runs before build"| node_otelc
node_otelc -.->|"configures build"| node_setup
node_setup -->|"invokes transformation"| node_transform
node_setup -->|"uses rules"| node_rules
node_setup -->|"uses build utilities"| node_go_util
node_transform -->|"parses source"| node_ast
node_transform -->|"applies rules"| node_rules
node_transform -->|"uses utilities"| node_go_util
node_runtime_setup -.->|"initializes instrumentation"| node_otelc
node_db_sql -->|"uses hook context"| node_hook_context
node_db_sql -->|"checks runtime state"| node_runtime_setup
node_linode -->|"uses hook context"| node_hook_context
node_redis -->|"uses hook context"| node_hook_context
node_redis -->|"checks runtime state"| node_runtime_setup
node_mongodb -->|"uses hook context"| node_hook_context
node_mongodb -->|"checks runtime state"| node_runtime_setup
node_grpc_client -->|"uses hook context"| node_hook_context
node_grpc_client -->|"checks runtime state"| node_runtime_setup
node_grpc_server -->|"uses hook context"| node_hook_context
node_grpc_server -->|"checks runtime state"| node_runtime_setup
node_http_client -->|"uses hook context"| node_hook_context
node_http_client -->|"checks runtime state"| node_runtime_setup
node_kubernetes -->|"checks runtime state"| node_runtime_setup

click node_otelc "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/cmd/otelc/main.go"
click node_setup "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/setup/setup.go"
click node_rules "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/tool/internal/rule"
click node_ast "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/ast/parser.go"
click node_transform "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/instrument/trampoline.go"
click node_go_util "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/util/go.go"
click node_runtime_setup "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/pkg/runtime/setup.go"
click node_hook_context "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/pkg/hook/context.go"
click node_db_sql "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/database/sql/client.go"
click node_linode "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation/github.com/linode/linodego/v2"
click node_redis "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/github.com/redis/go-redis/v9/client_hook.go"
click node_mongodb "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/go.mongodb.org/mongo-driver/mongo/client_hook.go"
click node_other_integrations "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation"
click node_grpc_client "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/google.golang.org/grpc/client/client_hook.go"
click node_grpc_server "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/google.golang.org/grpc/server/server_hook.go"
click node_http_client "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/net/http/client/client_hook.go"
click node_http_server "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation/net/http/server"
click node_kubernetes "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation/k8s.io/client-go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_otelc toneBlue
class node_setup,node_rules,node_ast,node_transform,node_go_util toneAmber
class node_runtime_setup,node_hook_context toneMint
class node_db_sql,node_linode,node_redis,node_mongodb,node_other_integrations,node_kubernetes toneRose
class node_grpc_client,node_grpc_server,node_http_client,node_http_server,node_developer toneIndigo
```

## Components

### Build entry

- [otelc CLI](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/cmd/otelc/main.go): `tool/cmd/otelc/main.go`

### Instrumentation engine

- [Build setup](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/setup/setup.go): `tool/internal/setup/setup.go`
- [Instrumentation rules](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/tool/internal/rule): `tool/internal/rule`
- [Go AST parser](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/ast/parser.go): `tool/internal/ast/parser.go`
- [Code transformer](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/internal/instrument/trampoline.go): `tool/internal/instrument/trampoline.go`
- [Go build utilities](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/tool/util/go.go): `tool/util/go.go`

### Shared runtime

- [Runtime setup](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/pkg/runtime/setup.go): `pkg/runtime/setup.go`
- [Hook context](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/pkg/hook/context.go): `pkg/hook/context.go`

### Library instrumentation

- [SQL database hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/database/sql/client.go): `instrumentation/database/sql/client.go`
- [Linode API hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation/github.com/linode/linodego/v2): `instrumentation/github.com/linode/linodego/v2`
- [Redis hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/github.com/redis/go-redis/v9/client_hook.go): `instrumentation/github.com/redis/go-redis/v9/client_hook.go`
- [MongoDB hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/go.mongodb.org/mongo-driver/mongo/client_hook.go): `instrumentation/go.mongodb.org/mongo-driver/mongo/client_hook.go`
- [Other library hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation): `instrumentation`
- [Kubernetes hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation/k8s.io/client-go): `instrumentation/k8s.io/client-go`

### Protocol instrumentation

- [gRPC client hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/google.golang.org/grpc/client/client_hook.go): `instrumentation/google.golang.org/grpc/client/client_hook.go`
- [gRPC server hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/google.golang.org/grpc/server/server_hook.go): `instrumentation/google.golang.org/grpc/server/server_hook.go`
- [HTTP client hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/blob/main/instrumentation/net/http/client/client_hook.go): `instrumentation/net/http/client/client_hook.go`
- [HTTP server hooks](https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/tree/main/instrumentation/net/http/server): `instrumentation/net/http/server`

### Other components

- **Go developer**

## Connections

- Go developer → otelc CLI: runs before build (evidence: `README.md`)
- otelc CLI → Build setup: configures build
- Build setup → Code transformer: invokes transformation (evidence: `tool/internal/setup/setup.go`)
- Build setup → Instrumentation rules: uses rules (evidence: `tool/internal/setup/setup.go`)
- Build setup → Go build utilities: uses build utilities (evidence: `tool/internal/setup/setup.go`)
- Code transformer → Go AST parser: parses source (evidence: `tool/internal/instrument/trampoline.go`)
- Code transformer → Instrumentation rules: applies rules (evidence: `tool/internal/instrument/trampoline.go`)
- Code transformer → Go build utilities: uses utilities (evidence: `tool/internal/instrument/trampoline.go`)
- Runtime setup → otelc CLI: initializes instrumentation
- SQL database hooks → Hook context: uses hook context (evidence: `instrumentation/database/sql/client.go`)
- SQL database hooks → Runtime setup: checks runtime state (evidence: `instrumentation/database/sql/client.go`)
- Linode API hooks → Hook context: uses hook context (evidence: `instrumentation/github.com/linode/linodego/v2/gen/main.go`)
- Redis hooks → Hook context: uses hook context (evidence: `instrumentation/github.com/redis/go-redis/v9/client_hook.go`)
- Redis hooks → Runtime setup: checks runtime state (evidence: `instrumentation/github.com/redis/go-redis/v9/client_hook.go`)
- MongoDB hooks → Hook context: uses hook context (evidence: `instrumentation/go.mongodb.org/mongo-driver/mongo/client_hook.go`)
- MongoDB hooks → Runtime setup: checks runtime state (evidence: `instrumentation/go.mongodb.org/mongo-driver/mongo/client_hook.go`)
- gRPC client hooks → Hook context: uses hook context (evidence: `instrumentation/google.golang.org/grpc/client/client_hook.go`)
- gRPC client hooks → Runtime setup: checks runtime state (evidence: `instrumentation/google.golang.org/grpc/client/client_hook.go`)
- gRPC server hooks → Hook context: uses hook context (evidence: `instrumentation/google.golang.org/grpc/server/server_hook.go`)
- gRPC server hooks → Runtime setup: checks runtime state (evidence: `instrumentation/google.golang.org/grpc/server/server_hook.go`)
- HTTP client hooks → Hook context: uses hook context (evidence: `instrumentation/net/http/client/client_hook.go`)
- HTTP client hooks → Runtime setup: checks runtime state (evidence: `instrumentation/net/http/client/client_hook.go`)
- Kubernetes hooks → Runtime setup: checks runtime state (evidence: `instrumentation/k8s.io/client-go/k8s_otel_handler.go`)
