Application Real-Time Monitoring Service:Reportar dados de rastreamento de uma aplicação Go usando Zipkin

Obter o endpoint do Zipkin

1. Faça login no console do Managed Service for OpenTelemetry.

2. No painel de navegação à esquerda, clique em Cluster Configurations. Na página exibida, clique em Access point information.

3. Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.

4. Defina Client como Jaeger ou Zipkin. Neste exemplo, o Jaeger está selecionado.

5. Copie o endpoint da coluna Related Information.

Adicionar dependências

Adicione a biblioteca Zipkin Go e um roteador ao seu projeto:

[[constraint]]
  name = "github.com/openzipkin/zipkin-go"
  version = "0.1.1"

[[constraint]]
  name = "github.com/gorilla/mux"
  version = "1.6.2"

Criar um tracer

O tracer gera spans que registram o tempo e os metadados das operações distribuídas. Configure-o com o endpoint de reporte, a identidade do serviço local e uma estratégia de amostragem.

func getTracer(serviceName string, ip string) *zipkin.Tracer {
    // Create a reporter that sends spans to the Zipkin endpoint.
    // Replace the URL with your actual endpoint from the console.
    reporter := httpreporter.NewReporter("http://tracing-analysis-dc-hz.aliyuncs.com/adapt_aokcdqnxyz@123456ff_abcdef123@abcdef123/api/v2/spans")

    // Set the local endpoint so spans are tagged with this service's identity.
    endpoint, _ := zipkin.NewEndpoint(serviceName, ip)

    // Sample every request. Increase the modulo value to reduce sampling
    // and lower reporting costs (e.g., NewModuloSampler(10) samples 1 in 10).
    sampler := zipkin.NewModuloSampler(1)

    // Initialize the tracer with the reporter, endpoint, and sampler.
    tracer, _ := zipkin.NewTracer(
        reporter,
        zipkin.WithLocalEndpoint(endpoint),
        zipkin.WithSampler(sampler),
    )
    return tracer
}

Criar spans

Um span raiz registra a operação principal de uma requisição:

span := tracer.StartSpan("some_operation")
// ... perform the operation ...
span.Finish()

Para rastrear suboperações dentro de uma requisição, crie spans filhos passando o contexto pai:

childSpan := tracer.StartSpan("some_operation2", zipkin.Parent(span.Context()))
// ... perform the sub-operation ...
childSpan.Finish()

Adicionar tags e anotações personalizadas (opcional)

Tags associam metadados chave-valor a um span para facilitar filtragens e depurações. Por exemplo, registre o código de status HTTP:

childSpan.Tag("http.status_code", statusCode)

Anotações marcam eventos com carimbo de data/hora dentro de um span. Use-as para registrar erros com stack traces:

childSpan := tracer.StartSpan("some_operation2", zipkin.Parent(span.Context()))
// ... perform the operation ...

var events = make(map[string]string)
events["event"] = "error"
events["stack"] = "Runtime Exception: unable to find userid"
jsonStr, err := json.Marshal(events)
if err == nil {
    childSpan.Annotate(time.Now(), string(jsonStr))
}
childSpan.Finish()

Propagar contexto entre serviços

O contexto de rastreamento — TraceId, ParentSpanId, SpanId e Sampled — deve acompanhar cada chamada de procedimento remoto (RPC) para que spans de diferentes serviços se vinculem em um único rastreamento. O Zipkin usa cabeçalhos B3 para propagar esse contexto via HTTP e gRPC.

Lado do cliente: injetar contexto na requisição de saída

req, _ := http.NewRequest("GET", "/", nil)

// Inject trace context as B3 headers into the HTTP request.
injector := b3.InjectHTTP(req)
injector(sp.Context())

Lado do servidor: extrair contexto da requisição recebida

req, _ := http.NewRequest("GET", "/", nil)
b3.InjectHTTP(req)(sp.Context())

b.ResetTimer()
_ = b3.ExtractHTTP(copyRequest(req))

Ausência de dados após a instrumentação

Verifique as mensagens de erro da sua aplicação:

• **failed the request with status code 403**: Usuário ou senha inválidos. Copie o endpoint completo — incluindo o segmento de autenticação — na aba Access point information.

• Sem erros, mas sem dados: Verifique se a URL do endpoint inclui o protocolo (http:// ou https://) e o caminho completo terminando em /api/v2/spans. Confirme também se a rede permite conexões de saída para esse endpoint.

• Configuração de amostragem: O uso de NewModuloSampler com valor superior a 1 captura apenas uma fração das requisições. Durante testes, defina esse parâmetro como 1 para capturar todas as requisições.