# open-telemetry/semantic-conventions-genai architecture

> Architecture diagram of the GitHub repository open-telemetry/semantic-conventions-genai, 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/semantic-conventions-genai
- Repository: https://github.com/open-telemetry/semantic-conventions-genai

## Overview

The repository defines GenAI OpenTelemetry conventions and includes Python reference scenarios that emit telemetry to demonstrate convention coverage. The principal workflow is scenario execution, shared telemetry setup, then conformance evaluation and support reporting. The README also identifies spans, metrics, events, MCP, and provider-specific conventions as product capabilities; their convention definitions and human-readable docs are described but are not present in the supplied tree. Edges below are limited to relationships visible in excerpts or the SOURCE INDEX.

Main entry points: [`reference/shared/reference_shared.py`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/shared/reference_shared.py) (Shared OTel setup), [`reference/src/semconv_genai/conformance.py`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/conformance.py) (Conformance engine), [`reference/src/semconv_genai/semconv_model.py`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/semconv_model.py) (Signal specifications), [`reference/src/semconv_genai/run_scenario.py`](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/run_scenario.py) (Scenario runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reference_scenarios["Reference scenarios"]
  node_anthropic["Anthropic scenario<br/>[scenario.py]"]
  node_bedrock["AWS Bedrock scenario<br/>[scenario.py]"]
  node_crewai["CrewAI scenario<br/>[scenario.py]"]
  node_google_adk["Google ADK scenario<br/>[scenario.py]"]
  node_google_genai["Google GenAI scenario<br/>[scenario.py]"]
  node_langchain["LangChain scenario<br/>[scenario.py]"]
  node_openai["OpenAI scenario<br/>[scenario.py]"]
  node_vertexai["Vertex AI scenario<br/>[scenario.py]"]
end

subgraph group_telemetry["Telemetry emission"]
  node_shared_telemetry["Shared OTel setup"]
end

subgraph group_conformance["Conformance tooling"]
  node_scenario_runner["Scenario runner<br/>[run_scenario.py]"]
  node_scenario_registry["Scenario registry<br/>[scenarios.py]"]
  node_conformance_runner["Conformance engine<br/>[conformance.py]"]
  node_weaver["Weaver management<br/>[weaver.py]"]
  node_version_pins["Version pins<br/>[versions.py]"]
end

subgraph group_coverage["Coverage and reports"]
  node_coverage_model["Signal specifications<br/>[semconv_model.py]"]
  node_attribute_spec["Attribute requirements<br/>[attribute_spec.py]"]
  node_scenario_data["Scenario data files<br/>[data_files.py]"]
  node_report_generator["Coverage reports<br/>[report.py]"]
end

node_scenario_user(("Scenario operator"))
node_otlp[("OTLP backends")]
node_documentation_readers(("Convention readers"))

node_scenario_user -->|"runs"| node_scenario_runner
node_scenario_runner -->|"selects scenario"| node_scenario_registry
node_scenario_runner -->|"runs checks"| node_conformance_runner
node_anthropic -->|"sets up telemetry"| node_shared_telemetry
node_bedrock -->|"sets up telemetry"| node_shared_telemetry
node_crewai -->|"sets up telemetry"| node_shared_telemetry
node_google_adk -->|"sets up telemetry"| node_shared_telemetry
node_google_genai -->|"sets up telemetry"| node_shared_telemetry
node_langchain -->|"sets up telemetry"| node_shared_telemetry
node_openai -->|"sets up telemetry"| node_shared_telemetry
node_vertexai -->|"sets up telemetry"| node_shared_telemetry
node_shared_telemetry -->|"exports signals"| node_otlp
node_conformance_runner -->|"resolves conventions"| node_weaver
node_conformance_runner -->|"uses pinned versions"| node_version_pins
node_weaver -->|"reads pin"| node_version_pins
node_conformance_runner -->|"produces coverage model"| node_coverage_model
node_coverage_model -->|"builds specifications"| node_attribute_spec
node_scenario_data -->|"uses specifications"| node_coverage_model
node_report_generator -->|"reads scenario data"| node_scenario_data
node_report_generator -->|"uses requirements"| node_attribute_spec
node_documentation_readers -.->|"consults conventions"| node_coverage_model
node_documentation_readers -->|"reviews support reports"| node_report_generator

click node_scenario_runner "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/run_scenario.py"
click node_scenario_registry "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/scenarios.py"
click node_anthropic "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/anthropic/scenario.py"
click node_bedrock "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/aws-bedrock/scenario.py"
click node_crewai "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/crewai/scenario.py"
click node_google_adk "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/google-adk/scenario.py"
click node_google_genai "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/google-genai/scenario.py"
click node_langchain "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/langchain/scenario.py"
click node_openai "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/openai/scenario.py"
click node_vertexai "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/vertexai/scenario.py"
click node_shared_telemetry "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/shared/reference_shared.py"
click node_conformance_runner "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/conformance.py"
click node_weaver "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/weaver.py"
click node_version_pins "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/versions.py"
click node_coverage_model "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/semconv_model.py"
click node_attribute_spec "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/attribute_spec.py"
click node_scenario_data "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/data_files.py"
click node_report_generator "https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/report.py"

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_anthropic,node_bedrock,node_crewai,node_google_adk,node_google_genai,node_langchain,node_openai,node_vertexai toneBlue
class node_shared_telemetry,node_otlp toneAmber
class node_scenario_runner,node_scenario_registry,node_conformance_runner,node_weaver,node_version_pins toneMint
class node_coverage_model,node_attribute_spec,node_scenario_data,node_report_generator toneRose
class node_scenario_user,node_documentation_readers toneIndigo
```

## Components

### Reference scenarios

- [Anthropic scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/anthropic/scenario.py): `reference/scenarios/anthropic/scenario.py`
- [AWS Bedrock scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/aws-bedrock/scenario.py): `reference/scenarios/aws-bedrock/scenario.py`
- [CrewAI scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/crewai/scenario.py): `reference/scenarios/crewai/scenario.py`
- [Google ADK scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/google-adk/scenario.py): `reference/scenarios/google-adk/scenario.py`
- [Google GenAI scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/google-genai/scenario.py): `reference/scenarios/google-genai/scenario.py`
- [LangChain scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/langchain/scenario.py): `reference/scenarios/langchain/scenario.py`
- [OpenAI scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/openai/scenario.py): `reference/scenarios/openai/scenario.py`
- [Vertex AI scenario](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/scenarios/vertexai/scenario.py): `reference/scenarios/vertexai/scenario.py`

### Telemetry emission

- [Shared OTel setup](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/shared/reference_shared.py): `reference/shared/reference_shared.py`

### Conformance tooling

- [Scenario runner](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/run_scenario.py): `reference/src/semconv_genai/run_scenario.py`
- [Scenario registry](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/scenarios.py): `reference/src/semconv_genai/scenarios.py`
- [Conformance engine](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/conformance.py): `reference/src/semconv_genai/conformance.py`
- [Weaver management](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/weaver.py): `reference/src/semconv_genai/weaver.py`
- [Version pins](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/versions.py): `reference/src/semconv_genai/versions.py`

### Coverage and reports

- [Signal specifications](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/semconv_model.py): `reference/src/semconv_genai/semconv_model.py`
- [Attribute requirements](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/attribute_spec.py): `reference/src/semconv_genai/attribute_spec.py`
- [Scenario data files](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/data_files.py): `reference/src/semconv_genai/data_files.py`
- [Coverage reports](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/reference/src/semconv_genai/report.py): `reference/src/semconv_genai/report.py`

### Other components

- **Scenario operator**
- **OTLP backends**
- **Convention readers**

## Connections

- Scenario operator → Scenario runner: runs
- Scenario runner → Scenario registry: selects scenario (evidence: `reference/src/semconv_genai/run_scenario.py`)
- Scenario runner → Conformance engine: runs checks (evidence: `reference/src/semconv_genai/run_scenario.py`)
- Anthropic scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/anthropic/scenario.py`)
- AWS Bedrock scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/aws-bedrock/scenario.py`)
- CrewAI scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/crewai/scenario.py`)
- Google ADK scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/google-adk/scenario.py`)
- Google GenAI scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/google-genai/scenario.py`)
- LangChain scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/langchain/scenario.py`)
- OpenAI scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/openai/scenario.py`)
- Vertex AI scenario → Shared OTel setup: sets up telemetry (evidence: `reference/scenarios/vertexai/scenario.py`)
- Shared OTel setup → OTLP backends: exports signals (evidence: `reference/shared/reference_shared.py`)
- Conformance engine → Weaver management: resolves conventions (evidence: `reference/src/semconv_genai/conformance.py`)
- Conformance engine → Version pins: uses pinned versions (evidence: `reference/src/semconv_genai/conformance.py`)
- Weaver management → Version pins: reads pin (evidence: `reference/src/semconv_genai/weaver.py`)
- Conformance engine → Signal specifications: produces coverage model (evidence: `reference/src/semconv_genai/conformance.py`)
- Signal specifications → Attribute requirements: builds specifications (evidence: `reference/src/semconv_genai/semconv_model.py`)
- Scenario data files → Signal specifications: uses specifications (evidence: `reference/src/semconv_genai/data_files.py`)
- Coverage reports → Scenario data files: reads scenario data (evidence: `reference/src/semconv_genai/report.py`)
- Coverage reports → Attribute requirements: uses requirements (evidence: `reference/src/semconv_genai/report.py`)
- Convention readers → Signal specifications: consults conventions (evidence: `README.md`)
- Convention readers → Coverage reports: reviews support reports (evidence: `README.md`)
