OpenTelemetry Go: Guia completo de rastreamento distribuído

1. O que é e para que serve?

OpenTelemetry é um conjunto de APIs, SDKs e ferramentas projetadas para criar e gerenciar dados de telemetria, como traces, metrics e logs. A biblioteca opentelemetry-go é a implementação oficial do padrão OpenTelemetry para a linguagem Go. Ela oferece aos desenvolvedores uma forma unificada e independente de fornecedor para instrumentar suas aplicações, coletar telemetria e enviá-la para diversos backends, como Jaeger, Zipkin, Prometheus, Grafana Tempo, Datadog e muitos outros.

Para que serve? Em arquiteturas modernas de microsserviços, uma requisição de usuário frequentemente passa por dezenas de serviços diferentes. Quando surge um problema (como uma requisição muito lenta ou um erro), sem o rastreamento distribuído (distributed tracing) é extremamente difícil identificar qual serviço é o gargalo ou a causa da falha. O OpenTelemetry permite rastrear o caminho da requisição por todo o sistema, visualizar o tempo de execução de cada etapa e conectá-las em um único trace, composto por spans. Isso dá a desenvolvedores e engenheiros de confiabilidade (SRE) uma ferramenta poderosa para depuração, monitoramento e otimização de desempenho.

A principal vantagem do OpenTelemetry sobre outras soluções (como as antigas bibliotecas OpenTracing ou OpenCensus) é sua universalidade e padronização. Você escreve o código uma vez, usando uma API única, e pode trocar o backend de armazenamento e visualização dos dados sem alterar o código da aplicação. Isso torna o opentelemetry-go não apenas uma biblioteca, mas a base para construir sistemas observáveis (observable) em Go.

2. Instalação

Para instalar a biblioteca opentelemetry-go e seus componentes principais, use o gerenciador de pacotes padrão do Go. Você precisará instalar o pacote principal da API, o SDK de tracing e um exportador (por exemplo, para console ou Jaeger).

# Instala a API principal
go get go.opentelemetry.io/otel

# Instala o SDK de tracing
go get go.opentelemetry.io/otel/sdk

# Instala o exportador para saída no console (para depuração)
go get go.opentelemetry.io/otel/exporters/stdout/stdouttrace

# Instala o propagador de contexto HTTP (para integração com HTTP)
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

# Instala o exportador para Jaeger (para produção)
go get go.opentelemetry.io/otel/exporters/jaeger

Após executar esses comandos, todas as dependências necessárias serão adicionadas ao seu arquivo go.mod.

3. Início rápido — exemplo mínimo funcional

Este exemplo mostra como criar um trace simples com um único span e exibi-lo no console. É um ótimo ponto de partida para entender os conceitos básicos.

package main

import (
	"context"
	"fmt"
	"log"

	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/attribute"
	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.17.0"
	"go.opentelemetry.io/otel/trace"
)

func main() {
	// 1. Cria o exportador para saída no console
	exporter, err := stdouttrace.New(
		stdouttrace.WithPrettyPrint(),
	)
	if err != nil {
		log.Fatal(err)
	}

	// 2. Cria o TracerProvider com o exportador e o resource
	tp := sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(exporter),
		sdktrace.WithResource(resource.NewWithAttributes(
			semconv.SchemaURL,
			semconv.ServiceNameKey.String("meu-servico"),
		)),
	)
	defer func() {
		if err := tp.Shutdown(context.Background()); err != nil {
			log.Fatal(err)
		}
	}()

	// 3. Define o TracerProvider global
	otel.SetTracerProvider(tp)

	// 4. Obtém o Tracer
	tracer := otel.Tracer("meu-tracer")

	// 5. Cria um span
	ctx, span :=