tracex

README

tracex

Библиотека для быстрой инициализации OpenTelemetry в Go-сервисах. Объединяет трассировку, метрики и логирование в одном месте.

Установка

go get github.com/fr11nik/tracex

Быстрый старт

ctx := context.Background()

tel, err := tracex.NewTelemetryProvider(ctx, "my-service", "1.0.0",
    tracex.WithDefaultExporters(),
)
if err != nil {
    log.Fatal(err)
}
defer tel.Shutdown(ctx)

После этого глобальные провайдеры OTel (otel.GetTracerProvider(), otel.GetMeterProvider(), global.GetLoggerProvider()) зарегистрированы и готовы к использованию.

Конструкторы

NewTelemetryProvider (рекомендуется)

tel, err := tracex.NewTelemetryProvider(ctx, serviceName, version, opts...)

Требует хотя бы один экспортер или опцию WithDefaultExporters. Если ни один не задан — возвращает ErrAtLeastOneExporter.

NewTelemetry (устарел)

tel, err := tracex.NewTelemetry(ctx, serviceName, version, opts...)

Автоматически включает консольные экспортеры, если ни один не задан. Оставлен для обратной совместимости.

Опции

Экспортеры трассировки

Опция	Описание
WithSpanConsoleExporter()	Вывод спанов в stdout
WithSpanGrpcExporter(ctx, endpoint)	Отправка спанов по gRPC (OTLP)
WithSpanHTTPExporter(ctx, endpoint)	Отправка спанов по HTTP (OTLP)

Экспортеры метрик

Опция	Описание
WithMetricConsoleExporter()	Вывод метрик в stdout
WithMetricGrpcExporter(ctx, endpoint)	Отправка метрик по gRPC (OTLP)

Экспортеры логов

Опция	Описание
WithLogConsoleExporter()	Вывод логов в stdout
WithLogGrpcExporter(ctx, endpoint)	Отправка логов по gRPC (OTLP)

Прочее

Опция	Описание
WithDefaultExporters()	Включает консольные экспортеры для всех сигналов
WithSlogHandler(mh)	Добавляет OTel bridge в существующий slogx.MultiHandler

Примеры

Отправка в коллектор по gRPC

endpoint := "localhost:4317"

tel, err := tracex.NewTelemetryProvider(ctx, "my-service", "1.0.0",
    tracex.WithSpanGrpcExporter(ctx, endpoint),
    tracex.WithMetricGrpcExporter(ctx, endpoint),
    tracex.WithLogGrpcExporter(ctx, endpoint),
)
if err != nil {
    log.Fatal(err)
}
defer tel.Shutdown(ctx)

Интеграция с существующим slog-логгером

Если у вас уже есть slogx.MultiHandler, OTel bridge добавится в него — отдельный логгер создаваться не будет:

handler := slogx.NewMultiHandler(jsonHandler)

tel, err := tracex.NewTelemetryProvider(ctx, "my-service", "1.0.0",
    tracex.WithSlogHandler(handler),
    tracex.WithLogGrpcExporter(ctx, "localhost:4317"),
    tracex.WithSpanGrpcExporter(ctx, "localhost:4317"),
)

Использование трассировки и метрик

После инициализации работайте с OTel напрямую через глобальные провайдеры:

tracer := otel.Tracer("my-service")
ctx, span := tracer.Start(ctx, "operation-name")
defer span.End()

meter := otel.Meter("my-service")
counter, _ := meter.Int64Counter("requests.total")
counter.Add(ctx, 1)

Корректное завершение

tel, err := tracex.NewTelemetryProvider(...)
if err != nil {
    log.Fatal(err)
}

// Обязательно вызывайте Shutdown — это гарантирует отправку буферизованных данных
defer tel.Shutdown(ctx)

Архитектура

NewTelemetryProvider
├── setupLogging   → LoggerProvider → global.SetLoggerProvider + slog bridge
├── setupMetrics   → MeterProvider  → otel.SetMeterProvider
└── setupTracing   → TracerProvider → otel.SetTracerProvider + propagation

Resource автоматически включает имя сервиса, версию и hostname.

gRPC-экспортеры работают без TLS (WithInsecure) и без повторных попыток — настройте это на стороне коллектора или оберните собственным экспортером.

Documentation

Index

• Variables
• type Option
  • func WithDefaultExporters() Option
  • func WithLogConsoleExporter() Option
  • func WithLogGrpcExporter(ctx context.Context, otlpEndpoint string) Option
  • func WithMetricConsoleExporter() Option
  • func WithMetricGrpcExporter(ctx context.Context, otlpEndpoint string, scrapeInterval time.Duration) Option
  • func WithSlogHandler(mh *slogx.MultiHandler) Option
  • func WithSpanConsoleExporter() Option
  • func WithSpanGrpcExporter(ctx context.Context, otlpEndpoint string) Option
  • func WithSpanHTTPExporter(ctx context.Context, otlpEndpoint string) Option
• type Telemetry
  • func NewTelemetry(ctx context.Context, serviceName, version string, opts ...Option) (*Telemetry, error)
  • func NewTelemetryProvider(ctx context.Context, serviceName, version, enviroment string, opts ...Option) (*Telemetry, error)
  • func (t *Telemetry) Shutdown(ctx context.Context)

Variables

var ErrAtLeastOneExporter = errors.New("at least one exporter must be provided or use withDefaultExporters option")

Types

type Option

type Option func(t *Telemetry) error

func WithDefaultExporters

func WithDefaultExporters() Option

func WithLogConsoleExporter

func WithLogConsoleExporter() Option

func WithLogGrpcExporter

func WithLogGrpcExporter(ctx context.Context, otlpEndpoint string) Option

func WithMetricConsoleExporter

func WithMetricConsoleExporter() Option

func WithMetricGrpcExporter

func WithMetricGrpcExporter(ctx context.Context, otlpEndpoint string, scrapeInterval time.Duration) Option

func WithSlogHandler

func WithSlogHandler(mh *slogx.MultiHandler) Option

WithSlogHandler позволяет передать уже инициализированный MultiHandler. OTel log bridge будет inject'нут в него, вместо создания нового логгера.

func WithSpanConsoleExporter

func WithSpanConsoleExporter() Option

func WithSpanGrpcExporter

func WithSpanGrpcExporter(ctx context.Context, otlpEndpoint string) Option

func WithSpanHTTPExporter

func WithSpanHTTPExporter(ctx context.Context, otlpEndpoint string) Option

type Telemetry

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

func NewTelemetry

func NewTelemetry(
	ctx context.Context,
	serviceName, version string,
	opts ...Option,
) (*Telemetry, error)

Deprecated: Use NewTelemetryProvider instead

func NewTelemetryProvider

func NewTelemetryProvider(
	ctx context.Context,
	serviceName, version, enviroment string,
	opts ...Option,
) (*Telemetry, error)

NewTelemetryProvider creates a new telemetry instance. Without any exporters and without WithDefaultExporters option NewTelemetryProvider return error - ErrAtLeastOneExporter

func (*Telemetry) Shutdown

func (t *Telemetry) Shutdown(ctx context.Context)

Shutdown shuts down the logger, meter, and tracer.