# modules/telemetry

```go
import "apistock.dev/modules/telemetry"
```

Package telemetry sets up OpenTelemetry tracing and metrics and structured logs correlated with requests and traces (ADR-0007).

Tracing is always on, so every log line written with a request context carries trace and span IDs. Spans and metrics are exported only when OTLP export is enabled; the exporters read the standard OTEL\_EXPORTER\_OTLP\_\* environment variables, as OpenTelemetry specifies.

By default [Setup](#Setup) installs its providers and the W3C trace-context propagator as OpenTelemetry globals, which instrumentation libraries use. Call it once, from the composition root.

Stability: pre-1.0 (ADR-0015).

## Constants

### const KeyRequestID, …

```go
const (
	KeyRequestID = "request_id"
	KeyTraceID   = "trace_id"
	KeySpanID    = "span_id"
	KeyOrgID     = "org_id"
)
```

Log attribute keys added from the context.

## Functions

### func NewLogHandler

```go
func NewLogHandler(h slog.Handler) slog.Handler
```

NewLogHandler wraps h so records logged with a context carry request\_id, trace\_id, span\_id and org\_id when available. Keys already present on the record are not added twice.

## Types

### type LogFormat

```go
type LogFormat string
```

LogFormat selects the log encoding.

#### const LogFormatJSON, …

```go
const (
	LogFormatJSON LogFormat = "json"
	LogFormatText LogFormat = "text"
)
```

Log formats.

### type Option

```go
type Option interface {
	// contains filtered or unexported methods
}
```

An Option configures [Setup](#Setup).

#### func WithLogFormat

```go
func WithLogFormat(f LogFormat) Option
```

WithLogFormat sets JSON (default, for production) or text (for local development) logs.

#### func WithLogLevel

```go
func WithLogLevel(l slog.Leveler) Option
```

WithLogLevel sets the minimum log level. Default: info.

#### func WithLogWriter

```go
func WithLogWriter(w io.Writer) Option
```

WithLogWriter sets where logs are written. Default: os.Stdout.

#### func WithOTLPExport

```go
func WithOTLPExport(enabled bool) Option
```

WithOTLPExport enables exporting spans and metrics over OTLP/HTTP, configured by the standard OTEL\_EXPORTER\_OTLP\_\* environment variables.

#### func WithSampleRatio

```go
func WithSampleRatio(r float64) Option
```

WithSampleRatio sets the fraction of new traces sampled, from 0 to 1. Child spans follow their parent's decision. Default: 1.

#### func WithSpanExporter

```go
func WithSpanExporter(e sdktrace.SpanExporter) Option
```

WithSpanExporter adds a synchronous span exporter, for tests and custom backends.

#### func WithoutGlobals

```go
func WithoutGlobals() Option
```

WithoutGlobals keeps Setup from installing OpenTelemetry globals.

### type Telemetry

```go
type Telemetry struct {
	// contains filtered or unexported fields
}
```

Telemetry holds the configured logger and OpenTelemetry providers.

#### func Setup

```go
func Setup(ctx context.Context, service, version string, opts ...Option) (*Telemetry, error)
```

Setup configures telemetry for service at version.

#### func (*Telemetry) HTTPMiddleware

```go
func (t *Telemetry) HTTPMiddleware() func(http.Handler) http.Handler
```

HTTPMiddleware starts a server span for each request, extracts incoming W3C trace context, records standard HTTP server metrics, and names the span after the matched http.ServeMux pattern (for example "GET /v1/projects/{id}") so traces group by route, not by raw path.

#### func (*Telemetry) Logger

```go
func (t *Telemetry) Logger() *slog.Logger
```

Logger returns the correlated structured logger.

#### func (*Telemetry) MeterProvider

```go
func (t *Telemetry) MeterProvider() metric.MeterProvider
```

MeterProvider returns the meter provider.

#### func (*Telemetry) Shutdown

```go
func (t *Telemetry) Shutdown(ctx context.Context) error
```

Shutdown flushes and stops exporters. Register it first on the cleanup stack so it runs last.

#### func (*Telemetry) TracerProvider

```go
func (t *Telemetry) TracerProvider() trace.TracerProvider
```

TracerProvider returns the tracer provider.