opentelemetry-go-extra

This repository provides a collection of OpenTelemetry instrumentations for various Go libraries and frameworks. The instrumentations support Metrics, Traces, and Logs depending on the specific package.

Key instrumentations include:

• Databases/SQL: database/sql, GORM 1, GORM 2, sqlx, and sqlboiler (all support Metrics and Traces).
• Logging: logrus (Traces) and otelzap (Logs).
• APIs/Frameworks: graphql-go (Traces).

You can find more instrumentations via the Uptrace instrument registry or the OpenTelemetry registry.

The otellogrus instrumentation records logrus log messages as events on an existing OpenTelemetry span.

Important Requirements:

• The log message is only recorded if the context.Context passed to the log call contains an active span.
• You must use logrus.WithContext(ctx) to ensure the span is propagated to the hook.

The otelgraphql package provides an implementation of the graphql-go tracer interface. It records GraphQL operations using the OpenTelemetry API by implementing the following methods (all accepting context.Context):

• TraceValidation: Traces the schema validation step that occurs before the operation.
• TraceQuery: Traces the entire operation (query or mutation) as a single span.
• TraceField: Traces specific field operations. These spans are typically intended to be sub-spans of the TraceQuery span.

Additionally, because graphql-go resolver methods receive context.Context, you can manually create field-specific sub-spans within your resolvers if the standard TraceField instrumentation does not meet your needs.

The net/http example can be executed using different OpenTelemetry exporters by setting specific environment variables. By default, it uses the Stdout exporter.

To use other backends, set the following environment variables before running the application:

• Jaeger: Set OTEL_EXPORTER_JAEGER_ENDPOINT to your Jaeger collector endpoint.
• Uptrace: Set UPTRACE_DSN with your Uptrace Data Source Name (DSN) containing your token and project ID.

# Stdout exporter (default)
go run .

# Jaeger exporter
OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces go run .

# Uptrace exporter
UPTRACE_DSN="https://<token>@uptrace.dev/<project_id>" go run .

To execute the demonstration for the otelpackage instrumentation, navigate to the example directory and use the Go CLI to run the package.

go run .

The otelzap instrumentation example can be executed using different OpenTelemetry exporters by setting specific environment variables. By default, the example uses the Stdout exporter.

To use the Jaeger exporter, set the OTEL_EXPORTER_JAEGER_ENDPOINT environment variable.

To use the Uptrace exporter, set the UPTRACE_DSN environment variable with your project credentials.

# Stdout exporter (default)
go run .

# Jaeger exporter
OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces go run .

# Uptrace exporter
UPTRACE_DSN="https://<token>@uptrace.dev/<project_id>" go run .

This example demonstrates how to send OpenTelemetry metrics to Prometheus. It uses Docker Compose to orchestrate the services required to view and scrape metrics.

To run the example, execute:

docker-compose up -d

Once running, two services are available:

• Metrics Target: https://localhost:8088/metrics (The endpoint that exports OpenTelemetry metrics).
• Prometheus UI: http://localhost:9090/graph (The Prometheus instance configured to scrape the metrics target).

You can verify the metrics by querying the counter test_my_counter in the Prometheus graph interface.

otelzap records Zap log messages as events on an existing OpenTelemetry span. To work, you must pass a context.Context containing an active span as the first argument. If the context does not contain a span, nothing is recorded.

You can use either the .Ctx(ctx) pattern or the .ErrorContext(ctx, ...) pattern. Both are designed to be fast and allocation-free.

import (
    "go.uber.org/zap"
    "github.com/uptrace/opentelemetry-go-extra/otelzap"
)

// Wrap zap logger to extend Zap with API that accepts a context.Context.
log := otelzap.New(zap.NewExample())

// Option 1: Using .Ctx(ctx)
log.Ctx(ctx).Error("hello from zap",
    zap.Error(errors.New("hello world")),
    zap.String("foo", "bar"))

// Option 2: Using .ErrorContext(ctx, ...)
log.ErrorContext(ctx, "hello from zap",
    zap.Error(errors.New("hello world")),
    zap.String("foo", "bar"))

To use OpenTelemetry instrumentation with sqlx, install the otelsqlx package using go get.

go get github.com/uptrace/opentelemetry-go-extra/otelsqlx