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 SDK do X-Ray para 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. É recomendável 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
+ Amostrador remoto do X-Ray: necessário para solicitações de amostragem usando regras de amostragem do X-Ray
+ Detectores de recursos: para detectar metadados do host que está executando sua aplicação
```
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
}
```
------
## Rastrear solicitações de entrada (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. Veja um exemplo de rastreamento de uma chamada do cliente do 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](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation#instrumentation-packages).
[Como alternativa, você pode pesquisar no OpenTelemetry registro para descobrir se OpenTelemetry oferece suporte à instrumentação para sua biblioteca em Registro.](https://opentelemetry.io/ecosystem/registry/)
## Criar dados de rastreamento manualmente
------
#### [ 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. Somente extensões do tipo servidor são convertidas em segmentos do X-Ray. Todas as outras extensões são convertidas em subsegmentos do X-Ray.
Primeiro, você precisará criar um rastreador para gerar extensões, que podem ser obtidas por meio do método `otel.Tracer`. 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 de rastreador forem necessárias, mas é comum ter um rastreador para toda a aplicação.
```
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 método `WithAttributes` é usado para adicionar atributos a cada extensão. Por padrão, todos os atributos de extensão 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](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations).
------
## Instrumentação manual Lambda
------
#### [ With X-Ray SDK ]
Ao usar o SDK do X-Ray, depois que o Lambda tiver o *Rastreamento ativo* habilitado, não há necessidade de configurações adicionais para usar o SDK do X-Ray. O Lambda criou um segmento representando a invocação do manipulador do Lambda, e você criou subsegmentos usando o SDK do X-Ray 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 do Lambda e o cliente do Amazon S3, faça o seguinte:
1. Em *main ()*, instancie um TracerProvider (tp) e registre-o como o provedor global de rastreadores. TracerProvider Recomenda-se que seja configurado com:
1. Processador de extensão simples com um exportador de extensão UDP X-Ray para enviar rastreamentos ao endpoint UDP X-Ray do Lambda
1. Recurso com *service.name* definido como o nome da função do Lambda
1. Altere o uso de `lambda.Start(lambdaHandler)` para `lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))`.
1. 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`
1. 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 do 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:
