ydb-go-sdk-otel

May 24, 2026 · View on GitHub

OpenTelemetry adapter for ydb-go-sdk: traces (spans), metrics and logs from YDB driver events.

The adapter does not configure OpenTelemetry exporters by itself. You set up TracerProvider, MeterProvider and LoggerProvider in your application (or rely on auto-instrumentation / OTel SDK defaults), then pass the corresponding instruments into ydb.Open.

What you get

Adapter optionYDB SDK signalOpenTelemetry signal
WithTracerdriver / table / query / … eventsspans and traces
WithMetricspool sizes, latencies, counters, …metrics via OTLP
WithLoggerSDK log events (resolver, retries, …)log records via OTLP

All three options are independent: enable only what you need.

Where to get tracer, meter and logger

OpenTelemetry instruments are obtained from global providers after you configure exporters (OTLP, stdout, etc.):

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/log/global"
)

// Call once at application startup, before ydb.Open:
//   otel.SetTracerProvider(...)
//   otel.SetMeterProvider(...)
//   global.SetLoggerProvider(...)

tracer := otel.Tracer("my-service")       // go.opentelemetry.io/otel/trace.Tracer
meter := otel.Meter("my-service")         // go.opentelemetry.io/otel/metric.Meter
logger := global.Logger("my-service")     // go.opentelemetry.io/otel/log.Logger

Use the same instrumentation scope name (for example "my-service") across tracer, meter and logger so signals correlate in the backend.

Pass nil to WithTracer, WithMetrics or WithLogger to use the global provider with the default scope "ydb-go-sdk".

See OpenTelemetry Go documentation and package docs:

For OTLP export to a collector set OTEL_EXPORTER_OTLP_ENDPOINT (for example localhost:4318 for HTTP) and use OTLP exporters from go.opentelemetry.io/otel/exporters/otlp/....

Quick start

package main

import (
    "context"
    "os"

    "github.com/ydb-platform/ydb-go-sdk/v3"
    "github.com/ydb-platform/ydb-go-sdk/v3/trace"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/log/global"

    ydbOtel "github.com/ydb-platform/ydb-go-sdk-otel"
)

func main() {
    ctx := context.Background()

    // 1. Configure OTel providers and exporters (TracerProvider, MeterProvider, LoggerProvider).
    //    See internal/cmd/native/query/main.go for a trace-only OTLP/HTTP example.

    tracer := otel.Tracer("my-service")
    meter := otel.Meter("my-service")
    logger := global.Logger("my-service")

    // 2. Open YDB driver with adapter options.
    db, err := ydb.Open(ctx, os.Getenv("YDB_CONNECTION_STRING"),
        ydbOtel.WithTracer(tracer, ydbOtel.WithDetailer(trace.DetailsAll)),
        ydbOtel.WithMetrics(meter, ydbOtel.WithDetailer(trace.DetailsAll)),
        ydbOtel.WithLogger(logger, ydbOtel.WithDetailer(trace.DetailsAll)),
    )
    if err != nil {
        panic(err)
    }
    defer func() { _ = db.Close(ctx) }()

    // work with db
}

More examples: example_test.go (also shown on pkg.go.dev).

Options

Common

WithDetailer(trace.Detailer) — controls which SDK events are reported. Works with WithTracer, WithMetrics and WithLogger:

ydbOtel.WithDetailer(trace.DetailsAll)

Traces

ydbOtel.WithTracer(tracer, opts...)

If tracer is nil, the adapter uses otel.Tracer("ydb-go-sdk").

Metrics

ydbOtel.WithMetrics(meter, opts...)

If meter is nil, the adapter uses otel.Meter("ydb-go-sdk").

Additional metrics options:

  • WithNamespace(prefix) — metric name prefix
  • WithSeparator(sep) — scope separator (default _)
  • WithTimerBuckets(buckets) — histogram buckets for timers

Logs

ydbOtel.WithLogger(logger, opts...)

If logger is nil, the adapter uses global.Logger("ydb-go-sdk").

Additional log options:

  • WithLogQuery() — log SQL/YQL query text

When trace ID is available in context, the adapter adds otel-trace-id to log fields for correlation with spans.

Local development

Start YDB and an OTLP-compatible backend (Jaeger accepts OTLP on port 4318):

docker compose -f internal/cmd/configs/docker-compose.yml up -d
export YDB_CONNECTION_STRING="grpc://localhost:2136/local"
export OTEL_EXPORTER_OTLP_ENDPOINT="localhost:4318"

Run the sample application:

go run ./internal/cmd/native/query

Open Jaeger UI at http://localhost:16686.