Migre para Go OpenTelemetry - AWS X-Ray
Instrumentação manual com o SDKRastreando solicitações recebidas (instrumentação do manipulador HTTP)AWS SDK para instrumentação do SDK for Go v2Instrumentar chamadas HTTP de saídaSuporte de instrumentação para outras bibliotecasCriação manual de dados de rastreamentoInstrumentação manual Lambda

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Migre para Go OpenTelemetry

Use os exemplos de código a seguir para instrumentar manualmente seus aplicativos Go com o OpenTelemetry SDK ao migrar do X-Ray.

Instrumentação manual com o SDK

Tracing setup with X-Ray SDK

Ao usar o X-Ray SDK for Go, era necessário configurar plug-ins de serviço ou regras de amostragem locais antes de instrumentar seu código.


func init() {
    if os.Getenv("ENVIRONMENT") == "production" {
        ec2.Init()
    }

    xray.Configure(xray.Config{
        DaemonAddr:       "127.0.0.1:2000", 
        ServiceVersion:   "1.2.3",
    })
}
Set up tracing with OpenTelemetry SDK

Configure o OpenTelemetry SDK instanciando um TracerProvider e registrando-o como provedor global de rastreadores. Recomendamos configurar os seguintes componentes:

  • Exportador de rastreamento OTLP — Necessário para exportar traços para o agente ou coletor CloudWatch OpenTelemetry

  • X-Ray Propagator — necessário para propagar o contexto de rastreamento para AWS serviços integrados ao X-Ray

  • X-Ray Remote Sampler — Necessário para solicitações de amostragem usando regras de amostragem de X-Ray

  • Detectores de recursos — Para detectar metadados do host que está executando seu aplicativo


import (
    "go.opentelemetry.io/contrib/detectors/aws/ec2"
    "go.opentelemetry.io/contrib/propagators/aws/xray"
    "go.opentelemetry.io/contrib/samplers/aws/xray"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/sdk/trace"
)

func setupTracing() error {
    ctx := context.Background()

    exporterEndpoint := os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
    if exporterEndpoint == "" {
        exporterEndpoint = "localhost:4317"
    }

    traceExporter, err := otlptracegrpc.New(ctx,
        otlptracegrpc.WithInsecure(),
        otlptracegrpc.WithEndpoint(exporterEndpoint))
    if err != nil {
        return fmt.Errorf("failed to create OTLP trace exporter: %v", err)
    }

    remoteSampler, err := xray.NewRemoteSampler(ctx, "my-service-name", "ec2")
    if err != nil {
        return fmt.Errorf("failed to create X-Ray Remote Sampler: %v", err)
    }

    ec2Resource, err := ec2.NewResourceDetector().Detect(ctx)
    if err != nil {
        return fmt.Errorf("failed to detect EC2 resource: %v", err)
    }

    tp := trace.NewTracerProvider(
        trace.WithSampler(remoteSampler),
        trace.WithBatcher(traceExporter),
        trace.WithResource(ec2Resource),
    )

    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(xray.Propagator{})

    return nil
}

Rastreando solicitações recebidas (instrumentação do manipulador HTTP)

With X-Ray SDK

Para instrumentar um manipulador HTTP com X-Ray, o método do manipulador X-Ray foi usado para gerar segmentos usando. NewFixedSegmentNamer


func main() {
    http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("myApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello!"))
    })))
    http.ListenAndServe(":8000", nil)
}
With OpenTelemetry SDK

Para instrumentar um manipulador HTTP com OpenTelemetry, use o OpenTelemetry método newHandler para encapsular o código original do manipulador.


import (
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)
    
helloHandler := func(w http.ResponseWriter, req *http.Request) {
    ctx := req.Context()
    span := trace.SpanFromContext(ctx)
    span.SetAttributes(attribute.Bool("isHelloHandlerSpan", true), attribute.String("attrKey", "attrValue"))

    _, _ = io.WriteString(w, "Hello World!\n")
}

otelHandler := otelhttp.NewHandler(http.HandlerFunc(helloHandler), "Hello")

http.Handle("/hello", otelHandler)
err = http.ListenAndServe(":8080", nil)
if err != nil {
    log.Fatal(err)
}

AWS SDK para instrumentação do SDK for Go v2

With X-Ray SDK

Para instrumentar as AWS solicitações de saída do AWS SDK, seus clientes foram instrumentados da seguinte forma:


// Create a segment
ctx, root := xray.BeginSegment(context.TODO(), "AWSSDKV2_Dynamodb")
defer root.Close(nil)

cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-west-2"))
if err != nil {
    log.Fatalf("unable to load SDK config, %v", err)
}
// Instrumenting AWS SDK v2
awsv2.AWSV2Instrumentor(&cfg.APIOptions)
// Using the Config value, create the DynamoDB client
svc := dynamodb.NewFromConfig(cfg)
// Build the request with its input parameters
_, err = svc.ListTables(ctx, &dynamodb.ListTablesInput{
    Limit: aws.Int32(5),
})
if err != nil {
    log.Fatalf("failed to list tables, %v", err)
}
With OpenTelemetry SDK

O suporte de rastreamento para chamadas downstream do AWS SDK é fornecido pela instrumentação OpenTelemetry do SDK AWS for Go v2. Aqui está um exemplo de rastreamento de uma chamada do cliente S3:

import (
    ...

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"

    "go.opentelemetry.io/otel"
    oteltrace "go.opentelemetry.io/otel/trace"
    awsConfig "github.com/aws/aws-sdk-go-v2/config"
    "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
)

...

    
    // init aws config
    cfg, err := awsConfig.LoadDefaultConfig(ctx)
    if err != nil {
        panic("configuration error, " + err.Error())
    }
    
    // instrument all aws clients
    otelaws.AppendMiddlewares(&.APIOptions)
    
    
    // Call to S3
    s3Client := s3.NewFromConfig(cfg)
    input := &s3.ListBucketsInput{}
    result, err := s3Client.ListBuckets(ctx, input)
    if err != nil {
        fmt.Printf("Got an error retrieving buckets, %v", err)
        return
    }

Instrumentar chamadas HTTP de saída

With X-Ray SDK

Para instrumentar as chamadas HTTP de saída com o X-Ray, o XRay.client foi usado para criar uma cópia de um cliente HTTP fornecido.


myClient := xray.Client(http-client)

resp, err := ctxhttp.Get(ctx, xray.Client(nil), url)
With OpenTelemetry SDK

Para instrumentar clientes HTTP com OpenTelemetry, use OpenTelemetry otelhttp. NewTransport método para encapsular o http. DefaultTransport.

import (
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
)

// Create an instrumented HTTP client.
httpClient := &http.Client{
    Transport: otelhttp.NewTransport(
        http.DefaultTransport,
    ),
}

req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
if err != nil {
    fmt.Printf("failed to create http request, %v\n", err)
}
res, err := httpClient.Do(req)
if err != nil {
    fmt.Printf("failed to make http request, %v\n", err)
}
// Request body must be closed
defer func(Body io.ReadCloser) {
    err := Body.Close()
    if err != nil {
        fmt.Printf("failed to close http response body, %v\n", err)
    }
}(res.Body)

Suporte de instrumentação para outras bibliotecas

Você pode encontrar a lista completa de instrumentações de biblioteca compatíveis com o OpenTelemetry Go em Pacotes de instrumentação.

Como alternativa, você pode pesquisar no OpenTelemetry registro para descobrir se OpenTelemetry suporta instrumentação para sua biblioteca em Registro.

Criação manual de dados de rastreamento

With X-Ray SDK

Com o X-Ray SDK, os BeginSubsegment métodos BeginSegment e foram necessários para criar manualmente segmentos e subsegmentos de raio-X.


// Start a segment
ctx, seg := xray.BeginSegment(context.Background(), "service-name")
// Start a subsegment
subCtx, subSeg := xray.BeginSubsegment(ctx, "subsegment-name")

// Add metadata or annotation here if necessary
xray.AddAnnotation(subCtx, "annotationKey", "annotationValue")
xray.AddMetadata(subCtx, "metadataKey", "metadataValue")

subSeg.Close(nil)
// Close the segment
seg.Close(nil)
With OpenTelemetry SDK

Use extensões personalizadas para monitorar o desempenho de atividades internas que não são capturadas pelas bibliotecas de instrumentação. Observe que somente extensões do tipo Server são convertidas em segmentos de X-Ray, todas as outras extensões são convertidas em subsegmentos de X-Ray.

Primeiro, você precisará criar um Tracer para gerar extensões, que podem ser obtidas por meio do otel.Tracer método. Isso fornecerá uma instância do Tracer TracerProvider que foi registrada globalmente no exemplo de configuração de rastreamento. Você pode criar quantas instâncias do Tracer forem necessárias, mas é comum ter um Tracer para um aplicativo inteiro.

    tracer := otel.Tracer("application-tracer")
import (
    ...

    oteltrace "go.opentelemetry.io/otel/trace"
)

...

    var attributes = []attribute.KeyValue{
        attribute.KeyValue{Key: "metadataKey", Value: attribute.StringValue("metadataValue")},
        attribute.KeyValue{Key: "annotationKey", Value: attribute.StringValue("annotationValue")},
        attribute.KeyValue{Key: "aws.xray.annotations", Value: attribute.StringSliceValue([]string{"annotationKey"})},
    }
    
    ctx := context.Background()
    
    parentSpanContext, parentSpan := tracer.Start(ctx, "ParentSpan", oteltrace.WithSpanKind(oteltrace.SpanKindServer), oteltrace.WithAttributes(attributes...))
    _, childSpan := tracer.Start(parentSpanContext, "ChildSpan", oteltrace.WithSpanKind(oteltrace.SpanKindInternal))
    
    // ...
    
    childSpan.End()
    parentSpan.End()

Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry

No exemplo acima, o WithAttributes método é usado para adicionar atributos a cada extensão. Observe que, por padrão, todos os atributos de amplitude são convertidos em metadados nos dados brutos do X-Ray. Para garantir que um atributo seja convertido em uma anotação e não em metadados, adicione a chave do atributo à lista do atributo. aws.xray.annotations Para obter mais informações, consulte Enable The Customized X-Ray Annotations.

Instrumentação manual Lambda

With X-Ray SDK

Com o X-Ray SDK, depois que seu Lambda ativou o Active Tracing, não foram necessárias configurações adicionais para usar o X-Ray SDK. O Lambda criou um segmento representando a invocação do manipulador Lambda, e você criou subsegmentos usando o X-Ray SDK sem nenhuma configuração adicional.

With OpenTelemetry SDK

O código de função Lambda a seguir (sem instrumentação) faz uma chamada do Amazon S3 e uma solicitação HTTP de saída ListBuckets .


package main

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"

    "github.com/aws/aws-lambda-go/events"
    "github.com/aws/aws-lambda-go/lambda"
    awsconfig "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func lambdaHandler(ctx context.Context) (interface{}, error) {
    // Initialize AWS config.
    cfg, err := awsconfig.LoadDefaultConfig(ctx)
    if err != nil {
        panic("configuration error, " + err.Error())
    }

    s3Client := s3.NewFromConfig(cfg)

    // Create an HTTP client.
    httpClient := &http.Client{
        Transport: http.DefaultTransport,
    }

    input := &s3.ListBucketsInput{}
    result, err := s3Client.ListBuckets(ctx, input)
    if err != nil {
        fmt.Printf("Got an error retrieving buckets, %v", err)
    }

    fmt.Println("Buckets:")
    for _, bucket := range result.Buckets {
        fmt.Println(*bucket.Name + ": " + bucket.CreationDate.Format("2006-01-02 15:04:05 Monday"))
    }
    fmt.Println("End Buckets.")

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
    if err != nil {
        fmt.Printf("failed to create http request, %v\n", err)
    }
    res, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("failed to make http request, %v\n", err)
    }
    defer func(Body io.ReadCloser) {
        err := Body.Close()
        if err != nil {
            fmt.Printf("failed to close http response body, %v\n", err)
        }
    }(res.Body)

    var data map[string]interface{}
    err = json.NewDecoder(res.Body).Decode(&data)
    if err != nil {
        fmt.Printf("failed to read http response body, %v\n", err)
    }
    fmt.Printf("Latest ADOT Go Release is '%s'\n", data["name"])

    return events.APIGatewayProxyResponse{
        StatusCode: http.StatusOK,
        Body:       os.Getenv("_X_AMZN_TRACE_ID"),
    }, nil
}

func main() {
    lambda.Start(lambdaHandler)
}

Para instrumentar manualmente seu manipulador Lambda e o cliente Amazon S3, faça o seguinte:

  1. Em main (), instancie um TracerProvider (tp) e registre-o como provedor global de rastreadores. TracerProvider Recomenda-se que seja configurado com:

    1. Processador de amplitude simples com um exportador de amplitude UDP de raio-X para enviar traços para o endpoint UDP X-Ray da Lambda

    2. Recurso com service.name definido como o nome da função Lambda

  2. Altere o uso de lambda.Start(lambdaHandler) paralambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...)).

  3. Instrumente o cliente Amazon S3 com a instrumentação do OpenTemetry AWS SDK anexando OpenTelemetry middleware à configuração do cliente Amazon S3. aws-sdk-go-v2

  4. Instrumente o cliente http usando o otelhttp.NewTransport método OpenTelemetry's para encapsular http.DefaultTransport o.

O código a seguir é um exemplo de como a Função Lambda ficará após as alterações. Você pode criar manualmente extensões personalizadas adicionais, além das extensões fornecidas automaticamente.

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"

    "github.com/aws-observability/aws-otel-go/exporters/xrayudp"
    "github.com/aws/aws-lambda-go/events"
    "github.com/aws/aws-lambda-go/lambda"
    awsconfig "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"

    lambdadetector "go.opentelemetry.io/contrib/detectors/aws/lambda"
    "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda"
    "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-lambda-go/otellambda/xrayconfig"
    "go.opentelemetry.io/contrib/instrumentation/github.com/aws/aws-sdk-go-v2/otelaws"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
    "go.opentelemetry.io/contrib/propagators/aws/xray"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/sdk/resource"
    "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.26.0"
)

func lambdaHandler(ctx context.Context) (interface{}, error) {
    // Initialize AWS config.
    cfg, err := awsconfig.LoadDefaultConfig(ctx)
    if err != nil {
        panic("configuration error, " + err.Error())
    }

    // Instrument all AWS clients.
    otelaws.AppendMiddlewares(&cfg.APIOptions)
    // Create an instrumented S3 client from the config.
    s3Client := s3.NewFromConfig(cfg)

    // Create an instrumented HTTP client.
    httpClient := &http.Client{
        Transport: otelhttp.NewTransport(
            http.DefaultTransport,
        ),
    }

    // return func(ctx context.Context) (interface{}, error) {
    input := &s3.ListBucketsInput{}
    result, err := s3Client.ListBuckets(ctx, input)
    if err != nil {
        fmt.Printf("Got an error retrieving buckets, %v", err)
    }

    fmt.Println("Buckets:")
    for _, bucket := range result.Buckets {
        fmt.Println(*bucket.Name + ": " + bucket.CreationDate.Format("2006-01-02 15:04:05 Monday"))
    }
    fmt.Println("End Buckets.")

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.github.com/repos/aws-observability/aws-otel-go/releases/latest", nil)
    if err != nil {
        fmt.Printf("failed to create http request, %v\n", err)
    }
    res, err := httpClient.Do(req)
    if err != nil {
        fmt.Printf("failed to make http request, %v\n", err)
    }
    defer func(Body io.ReadCloser) {
        err := Body.Close()
        if err != nil {
            fmt.Printf("failed to close http response body, %v\n", err)
        }
    }(res.Body)

    var data map[string]interface{}
    err = json.NewDecoder(res.Body).Decode(&data)
    if err != nil {
        fmt.Printf("failed to read http response body, %v\n", err)
    }
    fmt.Printf("Latest ADOT Go Release is '%s'\n", data["name"])

    return events.APIGatewayProxyResponse{
        StatusCode: http.StatusOK,
        Body:       os.Getenv("_X_AMZN_TRACE_ID"),
    }, nil
}

func main() {
    ctx := context.Background()
    detector := lambdadetector.NewResourceDetector()
    lambdaResource, err := detector.Detect(context.Background())
    if err != nil {
        fmt.Printf("failed to detect lambda resources: %v\n", err)
    }

    var attributes = []attribute.KeyValue{
        attribute.KeyValue{Key: semconv.ServiceNameKey, Value: attribute.StringValue(os.Getenv("AWS_LAMBDA_FUNCTION_NAME"))},
    }
    customResource := resource.NewWithAttributes(semconv.SchemaURL, attributes...)
    mergedResource, _ := resource.Merge(lambdaResource, customResource)

    xrayUdpExporter, _ := xrayudp.NewSpanExporter(ctx)
    tp := trace.NewTracerProvider(
        trace.WithSpanProcessor(trace.NewSimpleSpanProcessor(xrayUdpExporter)),
        trace.WithResource(mergedResource),
    )

    defer func(ctx context.Context) {
        err := tp.Shutdown(ctx)
        if err != nil {
            fmt.Printf("error shutting down tracer provider: %v", err)
        }
    }(ctx)

    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(xray.Propagator{})

    lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))
}

Ao invocar o Lambda, você verá o seguinte rastreamento Trace Map no CloudWatch console:

Mapa de rastreamento no CloudWatch console para Golang.