Tracing instrumentation

The Apitally SDK captures OpenTelemetry spans during request handling. This allows you to see exactly what happened during each request, including database queries, HTTP calls to external services, and custom operations. If your application does not have an existing OpenTelemetry setup, the SDK configures one automatically. Spans created within a captured request using the standard OpenTelemetry API or instrumentation libraries will be captured, as long as they are started with the request context.

Request context

In Go, spans are linked to the request through the request’s context.Context. Pass the request context, or a context derived from it, to instrumented libraries and to the SDK’s functions. The request context to pass depends on your framework:

Framework	Request context
Gin	`c.Request.Context()`
Echo	`c.Request().Context()`
Fiber v3	`c.Context()`
Fiber v2	`c.UserContext()`
Chi	`r.Context()`

Instrument libraries

Use OpenTelemetry instrumentation libraries to trace supported libraries. For example, to trace database queries made with database/sql, install otelsql:

go get github.com/XSAM/otelsql

Then open your database with otelsql.Open instead of sql.Open, and pass the request context to your queries:

import "github.com/XSAM/otelsql"

db, err := otelsql.Open("postgres", dsn)

// In your request handler
rows, err := db.QueryContext(ctx, "SELECT name FROM items")

Apitally sets up the OpenTelemetry tracer provider automatically, so you do not need to configure one or add an exporter.

Create custom spans

For custom operations that are not covered by library instrumentation, you can create spans using the standard OpenTelemetry API. Start each span with the request context, or a context derived from it, and pass the returned context to nested operations:

import (
    "context"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
)

var tracer = otel.Tracer("my-app")

func processOrder(ctx context.Context, orderID string) error {
    ctx, span := tracer.Start(ctx, "process_order")
    defer span.End()
    span.SetAttributes(attribute.String("order.id", orderID))

    // Process the order, passing ctx to nested operations ...
    return nil
}

Capture handled errors

Apitally includes errors in request traces to help you diagnose server errors. Panics are captured automatically, as are errors that are returned to Echo or Fiber, or added to the Gin context with c.Error(). If your application handles an error itself, for example by writing an error response directly, call apitally.CaptureError() with the request context to include it in the current request trace.

if err := processOrder(ctx); err != nil {
    apitally.CaptureError(ctx, err)
    // Write an error response without returning the error to the framework
}

SDK reference

Setup guides

Request context

Instrument libraries

Create custom spans

Capture handled errors

​Request context

​Instrument libraries

​Create custom spans

​Capture handled errors

Request context

Instrument libraries

Create custom spans

Capture handled errors