or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

embedded.mdindex.mdnoop.mdspan-context.mdspan-options.mdspan.mdtracer-provider-tracer.md
tile.json

tessl/golang-go-opentelemetry-io--otel--trace

OpenTelemetry Trace API for Go provides distributed tracing capabilities with TracerProvider, Tracer, and Span interfaces for instrumentation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
golangpkg:golang/go.opentelemetry.io/otel/trace@v1.38.0

To install, run

npx @tessl/cli install tessl/golang-go-opentelemetry-io--otel--trace@1.38.0

index.mddocs/

OpenTelemetry Trace API for Go

The OpenTelemetry Trace API provides a complete distributed tracing implementation for Go applications. It offers TracerProvider, Tracer, and Span interfaces for creating and managing trace data, with support for W3C Trace Context propagation, span hierarchies, and flexible instrumentation patterns.

Package Information

  • Package Name: go.opentelemetry.io/otel/trace
  • Package Type: Go module
  • Language: Go
  • Version: 1.38.0
  • Installation: go get go.opentelemetry.io/otel/trace@v1.38.0
  • Import Path: go.opentelemetry.io/otel/trace

Core Imports

import (
    "go.opentelemetry.io/otel/trace"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/codes"
)

For implementation helpers:

import "go.opentelemetry.io/otel/trace/embedded"

For no-op implementations:

import "go.opentelemetry.io/otel/trace/noop"

Basic Usage

package main

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/trace"
)

var tracer trace.Tracer

func init() {
    // Get a tracer from the global TracerProvider
    tracer = otel.Tracer("my-service/instrumentation")
}

func doWork(ctx context.Context) error {
    // Create a span
    ctx, span := tracer.Start(ctx, "doWork")
    defer span.End()

    // Add attributes
    span.SetAttributes(
        attribute.String("operation", "process"),
        attribute.Int("items", 42),
    )

    // Do work...
    if err := performOperation(ctx); err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, "operation failed")
        return err
    }

    span.SetStatus(codes.Ok, "")
    return nil
}

func performOperation(ctx context.Context) error {
    // Child span automatically inherits parent context
    _, childSpan := tracer.Start(ctx, "performOperation")
    defer childSpan.End()

    // Work happens here
    return nil
}

Architecture

The OpenTelemetry Trace API follows a layered architecture:

  • TracerProvider: Factory for creating Tracers, represents the telemetry collection pipeline
  • Tracer: Creates Spans for a specific instrumentation scope
  • Span: Represents a single operation in a distributed trace
  • SpanContext: Immutable span identification (TraceID, SpanID, flags, state)
  • Context Propagation: Uses Go's context.Context for parent-child relationships

API Evolution Pattern

This API uses a non-standard versioning approach where interfaces may have methods added in minor releases. Implementation authors must embed types from the embedded package to handle API evolution safely.

Capabilities

TracerProvider and Tracer

Factory interfaces for creating and managing Tracers that instrument code.

type TracerProvider interface {
    embedded.TracerProvider
    Tracer(name string, options ...TracerOption) Tracer
}

type Tracer interface {
    embedded.Tracer
    Start(ctx context.Context, spanName string, opts ...SpanStartOption) (context.Context, Span)
}

TracerProvider and Tracer Details

Span Operations

Core span interface for creating and managing individual trace operations.

type Span interface {
    embedded.Span
    End(options ...SpanEndOption)
    AddEvent(name string, options ...EventOption)
    AddLink(link Link)
    IsRecording() bool
    RecordError(err error, options ...EventOption)
    SpanContext() SpanContext
    SetStatus(code codes.Code, description string)
    SetName(name string)
    SetAttributes(kv ...attribute.KeyValue)
    TracerProvider() TracerProvider
}

Span Operations Details

Span Context and Identifiers

Immutable span identification and trace propagation.

type SpanContext struct { /* unexported fields */ }

type TraceID [16]byte
type SpanID [8]byte
type TraceFlags byte
type TraceState struct { /* unexported fields */ }

SpanContext and Identifiers Details

Span Configuration and Options

Configuration types and options for customizing span behavior at creation and end.

type SpanConfig struct { /* unexported fields */ }

type SpanStartOption interface { /* ... */ }
type SpanEndOption interface { /* ... */ }
type EventOption interface { /* ... */ }

// Composite option interfaces
type SpanOption interface {
    SpanStartOption
    SpanEndOption
}
type SpanEventOption interface {
    SpanOption
    EventOption
}
type SpanStartEventOption interface {
    SpanStartOption
    EventOption
}
type SpanEndEventOption interface {
    SpanEndOption
    EventOption
}

Span Configuration Details

No-Op Implementations

Production-ready implementations that produce no telemetry, useful for testing and default behavior.

type TracerProvider struct {
    embedded.TracerProvider
}

type Tracer struct {
    embedded.Tracer
}

type Span struct {
    embedded.Span
}

No-Op Implementations Details

API Implementation Patterns

Embedded types and patterns for safely implementing the OpenTelemetry Trace API.

package embedded

type TracerProvider interface { /* unexported methods */ }
type Tracer interface { /* unexported methods */ }
type Span interface { /* unexported methods */ }

API Implementation Patterns Details

Context Functions

Context manipulation functions for span propagation:

// ContextWithSpan returns a copy of parent with span set as the current Span.
func ContextWithSpan(parent context.Context, span Span) context.Context

// ContextWithSpanContext returns a copy of parent with sc as the current Span.
// The Span implementation that wraps sc is non-recording.
func ContextWithSpanContext(parent context.Context, sc SpanContext) context.Context

// ContextWithRemoteSpanContext returns a copy of parent with rsc set explicitly
// as a remote SpanContext and as the current Span.
func ContextWithRemoteSpanContext(parent context.Context, rsc SpanContext) context.Context

// SpanFromContext returns the current Span from ctx.
// If no Span is currently set, returns a non-recording span.
func SpanFromContext(ctx context.Context) Span

// SpanContextFromContext returns the current Span's SpanContext.
func SpanContextFromContext(ctx context.Context) SpanContext

Error Handling

The API does not define specific error types. Errors are recorded on spans:

if err := operation(); err != nil {
    span.RecordError(err)
    span.SetStatus(codes.Error, "operation failed")
    return err
}

Common status codes from go.opentelemetry.io/otel/codes:

  • codes.Unset - Default status
  • codes.Ok - Operation completed successfully
  • codes.Error - Operation failed

Best Practices

  1. Always call span.End(): Use defer span.End() immediately after creating a span
  2. Use TracerProvider injection: Accept TracerProvider as a parameter rather than using globals
  3. Instrument at boundaries: Create spans for external calls, database queries, and significant operations
  4. Add meaningful attributes: Include operation-specific context in span attributes
  5. Record errors properly: Use RecordError() and SetStatus() for error scenarios
  6. Propagate context: Always pass context through your call stack
  7. Name spans descriptively: Use operation names that clearly identify what the span represents