# mizcausevic-dev/miz-otel-pack architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/miz-otel-pack
- Repository: https://github.com/mizcausevic-dev/miz-otel-pack

## Overview

#### Purpose and principal workflow
otel-pack is a Go library that wraps an OpenTelemetry SDK span processor and converts completed GenAI operation spans into sibling business-metric spans. The external caller is a Go service integrating the library into its OTel `TracerProvider`; that service’s instrumented code emits spans, and the processor derives cost, token, latency, tenant, provider, and model attributes before forwarding the original span to the wrapped processor.

#### Components

##### Provider wiring and processor lifecycle
- **Business Span Processor** — `processor.go`: Implements the SDK `SpanProcessor` interface, wraps another processor, forwards lifecycle calls, and invokes derivation on completed spans.

##### GenAI-to-business translation
- **Span Attribute Translator** — `processor.go`: Reads GenAI attributes from ended spans, requires a model attribute, calculates token totals and elapsed time, and creates a `business.` sibling span with a source-span ID.

##### Pricing
- **Model Pricing Registry** — `pricing.go`: Provides built-in per-million-token rates, lookup and cost calculation, and `RegisterPricing` for consumer overrides.

##### External participants
- **Integrating Go Service** — `null`: The consumer configures the tracer provider and processor, and its instrumented code creates GenAI spans.
- **OpenTelemetry SDK and Global Tracer Provider** — `null`: The external SDK invokes processor lifecycle methods; the global provider supplies the tracer used for derived spans.
- **Wrapped Span Processor / Exporter Pipeline** — `null`: The consumer supplies a processor, such as a batch processor connected to an exporter, to receive original spans.

#### Relationships
- **Integrating Go Service -> Business Span Processor**: Installs it in the tracer provider; documented quickstart constructs the wrapper and passes it to `trace.NewTracerProvider`.
- **Integrating Go Service -> OpenTelemetry SDK and Global Tracer Provider**: Configures the global provider and emits instrumented spans; documented quickstart and GenAI example.
- **OpenTelemetry SDK and Global Tracer Provider -> Business Span Processor**: Calls `OnStart` and `OnEnd` through the SDK processor interface; `OnEnd` is implemented in `processor.go`.
- **Business Span Processor -> Span Attribute Translator**: Invokes translation when an original span ends; `OnEnd` calls `emitBusinessSpan`.
- **Span Attribute Translator -> Model Pricing Registry**: Looks up provider when the span lacks a provider attribute and calculates cost from model and token counts; `processor.go` calls `LookupPricing` and `CostUSD`.
- **Span Attribute Translator -> OpenTelemetry SDK and Global Tracer Provider**: Requests a tracer from the global provider and starts and ends the derived sibling span; `processor.go` calls `otel.Tracer` and `Start`/`End`.
- **Business Span Processor -> Wrapped Span Processor / Exporter Pipeline**: Forwards original-span start/end and flush/shutdown calls; `processor.go` delegates to `next`.
- **Integrating Go Service -> Model Pricing Registry**: Registers or overrides model prices through `RegisterPricing`; documented pricing example.

#### Coverage limits
The source sample does not show exporter implementations or consumer-specific provider setup beyond the README quickstart. Pricing registry synchronization and behavior under concurrent registration are not established by the sampled code.

Main entry points: [`processor.go`](https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/processor.go) (Business Span Processor), [`pricing.go`](https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/pricing.go) (Model Pricing Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Service Integration"]
  node_service["Integrating Go Service<br/>external"]
  node_otel["OTel SDK and Provider<br/>external"]
  node_wrapped["Wrapped Processor<br/>external"]
end

subgraph group_processing["Span Processing"]
  node_processor["Business Span Processor<br/>[processor.go]"]
  node_translator["Span Attribute Translator<br/>[processor.go]"]
end

subgraph group_pricing["Pricing"]
  node_pricing_registry["Model Pricing Registry<br/>[pricing.go]"]
end

node_service -->|"installs"| node_processor
node_service -->|"configures and emits"| node_otel
node_otel -->|"invokes lifecycle"| node_processor
node_processor -->|"translates ended spans"| node_translator
node_translator -->|"looks up and calculates"| node_pricing_registry
node_translator -->|"starts derived span"| node_otel
node_processor -->|"forwards lifecycle"| node_wrapped
node_service -->|"registers pricing"| node_pricing_registry

click node_processor "https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/processor.go"
click node_translator "https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/processor.go"
click node_pricing_registry "https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/pricing.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_service,node_otel,node_wrapped toneBlue
class node_processor,node_translator toneAmber
class node_pricing_registry toneMint
```

## Components

### Service Integration

- **Integrating Go Service**: external
- **OTel SDK and Provider**: external
- **Wrapped Processor**: external

### Span Processing

- [Business Span Processor](https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/processor.go): span processor · `processor.go`
- [Span Attribute Translator](https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/processor.go): translator · `processor.go`

### Pricing

- [Model Pricing Registry](https://github.com/mizcausevic-dev/miz-otel-pack/blob/main/pricing.go): pricing registry · `pricing.go`

## Connections

- Integrating Go Service → Business Span Processor: installs
- Integrating Go Service → OTel SDK and Provider: configures and emits
- OTel SDK and Provider → Business Span Processor: invokes lifecycle
- Business Span Processor → Span Attribute Translator: translates ended spans
- Span Attribute Translator → Model Pricing Registry: looks up and calculates
- Span Attribute Translator → OTel SDK and Provider: starts derived span
- Business Span Processor → Wrapped Processor: forwards lifecycle
- Integrating Go Service → Model Pricing Registry: registers pricing