Use OpenTelemetry to instrument Go applications and report traces - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Pré-requisitos

Para obter um endpoint do OpenTelemetry, siga as etapas abaixo:

Faça login no console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Em seguida, clique na aba Access point information.
Na barra de navegação superior, selecione uma região. Na seção Cluster Information, ative a opção Show Token.
Na seção Client, clique em OpenTelemetry.

Obtenha um endpoint do OpenTelemetry na coluna Related Information da tabela na parte inferior.

OpenTelemetry access point information

Nota

Se sua aplicação estiver implantada em um ambiente de produção da Alibaba Cloud, use um endpoint de Virtual Private Cloud (VPC). Caso contrário, utilize um endpoint público.

gRPC vs. HTTP: escolha um transporte

Tanto o gRPC quanto o HTTP usam OTLP para entregar dados de rastreamento. A inicialização do SDK e a lógica de instrumentação são quase idênticas — apenas o pacote do exportador e a configuração do cliente diferem.

Aspecto	gRPC	HTTP
Pacote de importação	`otlptracegrpc`	`otlptracehttp`
Formato do endpoint	`host:port` (valor único)	`Endpoint` (host:port) e `URLPath` separados
Autenticação	Mapa `WithHeaders` contendo o token de `Authentication`	Incorporado no caminho da URL
Caso de uso típico	Ambientes de baixa latência e alto throughput	Ambientes onde o gRPC está bloqueado ou indisponível

Dois caminhos de envio estão disponíveis para qualquer transporte:

Caminho	Quando usar
Envio direto via SDK	Envie dados de rastreamento diretamente da aplicação para o Managed Service for OpenTelemetry. Requer o endpoint e o token de autenticação obtidos na seção Pré-requisitos.
Encaminhamento via OpenTelemetry Collector	Roteie os dados de rastreamento por meio de um OpenTelemetry Collector autogerenciado. Substitua o endpoint pelo endereço IP do service local e remova os cabeçalhos de autenticação.

Código de exemplo

Para exemplos completos e funcionais, consulte oltp-exporter.

Envie dados via gRPC

Etapa 1: Instale as dependências

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/trace \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc

Etapa 2: Inicialize o OpenTelemetry SDK

A função initProvider configura o exportador OTLP gRPC, define os atributos de recurso e registra um TracerProvider global.

Substitua otelAgentAddr e xtraceToken pelo endpoint e token de autenticação obtidos na seção Pré-requisitos.

Nota

Se você encaminhar dados por meio de um OpenTelemetry Collector, substitua otelAgentAddr pelo endereço IP do service local e remova o mapa headers.

func initProvider() func() {
    ctx := context.Background()

    otelAgentAddr, xtraceToken, ok := common.ObtainXTraceInfo()

    if !ok {
        log.Fatalf("Cannot init OpenTelemetry, exit")
        os.Exit(-1)
    }

    // Set the authentication header for Managed Service for OpenTelemetry.
    headers := map[string]string{"Authentication": xtraceToken}
    traceClient := otlptracegrpc.NewClient(
        otlptracegrpc.WithInsecure(),
        otlptracegrpc.WithEndpoint(otelAgentAddr),
        otlptracegrpc.WithHeaders(headers),
        otlptracegrpc.WithDialOption(grpc.WithBlock()))
    log.Println("start to connect to server")
    traceExp, err := otlptrace.New(ctx, traceClient)
    handleErr(err, "Failed to create the collector trace exporter")

    res, err := resource.New(ctx,
        resource.WithFromEnv(),
        resource.WithProcess(),
        resource.WithTelemetrySDK(),
        resource.WithHost(),
        resource.WithAttributes(
            // Set the service name displayed in the Managed Service for OpenTelemetry console.
            semconv.ServiceNameKey.String(common.ServerServiceName),
            semconv.HostNameKey.String(common.ServerServiceHostName),
        ),
    )
    handleErr(err, "failed to create resource")

    bsp := sdktrace.NewBatchSpanProcessor(traceExp)
    tracerProvider := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
        sdktrace.WithResource(res),
        sdktrace.WithSpanProcessor(bsp),
    )

    // Set the global propagator to tracecontext. The global propagator is not specified by default.
    otel.SetTextMapPropagator(propagation.TraceContext{})
    otel.SetTracerProvider(tracerProvider)

    return func() {
        cxt, cancel := context.WithTimeout(ctx, time.Second)
        defer cancel()
        if err := traceExp.Shutdown(cxt); err != nil {
            otel.Handle(err)
        }
    }
}

Principais parâmetros de configuração:

Parâmetro	Descrição
`otelAgentAddr`	Endpoint gRPC obtido no console
`xtraceToken`	Token de autenticação obtido no console
`Authentication`	Chave de cabeçalho necessária para autenticação no Managed Service for OpenTelemetry
`semconv.ServiceNameKey`	Nome do service exibido no console

Etapa 3: Instrumente a aplicação

Crie um handler HTTP envolvido com a instrumentação do OpenTelemetry. O wrapper otelhttp.NewHandler cria automaticamente spans para requisições HTTP recebidas.

shutdown := initProvider()
    defer shutdown()

    serverAttribute := attribute.String("server-attribute", "foo")
    fmt.Println("start to gen chars for trace data")
    initTraceDemoData()
    fmt.Println("gen trace data done")
    tracer := otel.Tracer(common.TraceInstrumentationName)

    // Wrap the HTTP handler with OpenTelemetry instrumentation.
    handler := http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
        // Simulate a delay.
        var sleep int64
        switch modulus := time.Now().Unix() % 5; modulus {
        case 0:
            sleep = rng.Int63n(2000)
        case 1:
            sleep = rng.Int63n(15)
        case 2:
            sleep = rng.Int63n(917)
        case 3:
            sleep = rng.Int63n(87)
        case 4:
            sleep = rng.Int63n(1173)
        }
        ctx := req.Context()
        span := trace.SpanFromContext(ctx)
        span.SetAttributes(serverAttribute)

        actionChild(tracer, ctx, sleep)

        w.Write([]byte("Hello World"))
    })
    wrappedHandler := otelhttp.NewHandler(handler, "/hello")

    http.Handle("/hello", wrappedHandler)
    http.ListenAndServe(":7080", nil)

Etapa 4: Execute e verifique

Inicie a aplicação:

go run main.go

Na página Applications do console do Managed Service for OpenTelemetry, clique no nome da aplicação. Na página exibida, visualize os dados de rastreamento.

Envie dados via HTTP

Etapa 1: Instale as dependências

go get go.opentelemetry.io/otel \
  go.opentelemetry.io/otel/trace \
  go.opentelemetry.io/otel/sdk \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

Nota

A única diferença em relação às dependências gRPC é o uso de otlptracehttp em vez de otlptracegrpc.

Etapa 2: Inicialize o OpenTelemetry SDK

Substitua Endpoint e URLPath pelos valores do endpoint obtido na seção Pré-requisitos.

Nota

Se você encaminhar dados por meio de um OpenTelemetry Collector, substitua Endpoint pelo endereço IP do service local e remova os cabeçalhos de autenticação.

func initProvider() func() {
    ctx := context.Background()

    traceClientHttp := otlptracehttp.NewClient(
        otlptracehttp.WithEndpoint("127.0.XX.XX:8080"),                    // Replace with your endpoint host and port.
        otlptracehttp.WithURLPath("/adapt_xxxxx/api/otlp/traces"),         // Replace with your endpoint URL path.
        otlptracehttp.WithInsecure())
    otlptracehttp.WithCompression(1)

    traceExp, err := otlptrace.New(ctx, traceClientHttp)
    handleErr(err, "Failed to create the collector trace exporter")

    res, err := resource.New(ctx,
        resource.WithFromEnv(),
        resource.WithProcess(),
        resource.WithTelemetrySDK(),
        resource.WithHost(),
        resource.WithAttributes(
            // Set the service name displayed in the Managed Service for OpenTelemetry console.
            semconv.ServiceNameKey.String(common.ClientServiceName),
            semconv.HostNameKey.String(common.ClientServiceHostName),
        ),
    )
    handleErr(err, "failed to create resource")

    bsp := sdktrace.NewBatchSpanProcessor(traceExp)
    tracerProvider := sdktrace.NewTracerProvider(
        sdktrace.WithSampler(sdktrace.AlwaysSample()),
        sdktrace.WithResource(res),
        sdktrace.WithSpanProcessor(bsp),
    )

    // Set the global propagator to tracecontext. The global propagator is not specified by default.
    otel.SetTextMapPropagator(propagation.TraceContext{})
    otel.SetTracerProvider(tracerProvider)

    log.Println("OTEL init success")

    return func() {
        cxt, cancel := context.WithTimeout(ctx, time.Second)
        defer cancel()
        if err := traceExp.Shutdown(cxt); err != nil {
            otel.Handle(err)
        }
    }
}

Etapa 3: Instrumente a aplicação

Este exemplo cria spans manualmente em um loop, em vez de envolver um handler HTTP. Cada iteração inicia um span chamado ExecuteRequest, chama makeRequest e anexa membros de baggage que se propagam entre os limites dos services.

tracer := otel.Tracer(common.TraceInstrumentationName)

    method, _ := baggage.NewMember("method", "repl")
    client, _ := baggage.NewMember("client", "cli")
    bag, _ := baggage.New(method, client)

    defaultCtx := baggage.ContextWithBaggage(context.Background(), bag)
    for {
        ctx, span := tracer.Start(defaultCtx, "ExecuteRequest")
        makeRequest(ctx)
        span.End()
        time.Sleep(time.Duration(1) * time.Second)
    }

Etapa 4: Execute e verifique

Inicie a aplicação:

go run main.go

Na página Applications do console do Managed Service for OpenTelemetry, clique no nome da aplicação. Na página exibida, visualize os dados de rastreamento.

Auto-instrumentação para frameworks comuns

O OpenTelemetry oferece plugins de instrumentação semiautomática. Não é necessário criar spans manualmente; basta chamar as operações de API fornecidas por esses plugins no código. Spans podem ser criados automaticamente para frameworks comuns. Para mais informações sobre os frameworks suportados, consulte o OpenTelemetry Registry.

Próximos passos

Bibliotecas de instrumentação OpenTelemetry Go — instrumentação automática para frameworks populares
OpenTelemetry SDK for Go — código-fonte do SDK e exemplos
Documentação do OpenTelemetry Go — opções avançadas de configuração