Usar Zipkin para instrumentar aplicações Go e reportar rastreamentos - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Se você precisa de rastreamento distribuído para uma aplicação Go e já utiliza o Zipkin em seu stack, reporte os dados de rastreamento diretamente ao Managed Service for OpenTelemetry. Após a integração, visualize a topologia da aplicação, rastreamentos, transações anômalas e lentas, além de análises de SQL no console.

Importante

Para obter recursos avançados, capacidades superiores de rastreamento e uma experiência aprimorada, conecte sua aplicação ao Managed Service for OpenTelemetry pelo protocolo OpenTelemetry. Para mais informações, consulte Preparativos.
O ARMS oferece um agente proprietário com suporte comercial para aplicações Go. Esse agente permite instrumentação não intrusiva, com um conjunto de recursos mais completo e maior estabilidade. Para mais detalhes, veja Monitorar aplicações Go.

Como funciona

O Zipkin é um sistema de rastreamento distribuído open source desenvolvido pelo Twitter. Ele agrega dados de monitoramento em tempo real de múltiplos sistemas heterogêneos.

Sua aplicação Go usa a biblioteca cliente do Zipkin para criar spans e enviá-los ao endpoint do Managed Service for OpenTelemetry via HTTP:

Pré-requisitos

Antes de começar, certifique-se de ter:

Um ambiente de desenvolvimento Go
Acesso ao console do Managed Service for OpenTelemetry
O endpoint do Zipkin para sua região (consulte Obter o endpoint do Zipkin)

Obter o endpoint do Zipkin

Faça login no console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Na página exibida, clique em Access point information.
Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative Show Token.
Defina Client como Jaeger ou Zipkin. Neste exemplo, o Jaeger está selecionado.
Copie o endpoint da coluna Related Information.

Jaeger/Zipkin access point information

Nota

Se sua aplicação for executada em um ambiente de produção da Alibaba Cloud, use o endpoint de VPC. Caso contrário, use o endpoint público. Use o endpoint v2, a menos que haja um motivo específico para usar a versão v1.

Início rápido

Execute uma demonstração pré-construída para confirmar se os dados de rastreamento chegam ao Managed Service for OpenTelemetry antes de instrumentar sua própria aplicação.

Baixe o projeto de demonstração.
Abra o arquivo utils.go e substitua <endpoint> pelo endpoint do Zipkin obtido na seção Obter o endpoint do Zipkin.
Instale as dependências:
```
dep ensure
```
Execute a aplicação:
```
go run main.go
```
Verifique os dados de rastreamento no console:
1. Faça login no console do ARMS.
2. No painel de navegação à esquerda, escolha Application Monitoring > Applications.
3. Clique em nome da aplicação para visualizar seus dados de rastreamento.

Nota

Se o ícone icon aparecer na coluna Language, a aplicação estará conectada ao Application Monitoring. Se houver um hífen (-), ela estará vinculada ao Managed Service for OpenTelemetry.

Instrumentar sua aplicação

Esta seção detalha cada etapa da instrumentação: adição de dependências, criação do tracer, registro de spans, aplicação de tags e propagação de contexto entre serviços.

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 de nível superior de uma requisição:

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

Para acompanhar 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 tempo 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 o 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))

Solução de problemas

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

Verifique a saída de erros da sua aplicação:

**failed the request with status code 403**: Nome de usuário ou senha inválidos. Copie o endpoint completo — incluindo o segmento de autenticação — da aba Access point information.
Sem erros, mas sem dados: Confirme se a URL do endpoint inclui o protocolo (http:// ou https://) e o caminho completo terminando em /api/v2/spans. Verifique também se sua rede permite conexões de saída para o endpoint.
Configuração de amostragem: O uso de NewModuloSampler com valor superior a 1 amostra apenas uma fração das requisições. Defina como 1 durante os testes para capturar todas as requisições.