本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 迁移到 OpenTelemetry Go 从 X-Ray 迁移时，使用以下代码示例使用 OpenTelemetry SDK 手动检测您的 Go 应用程序。 ## 使用 SDK 进行手动检测 ------ #### [ Tracing setup with X-Ray SDK ] 使用 X-Ray SDK for Go 时，需要先配置服务插件或本地采样规则，然后才能对代码进行检测。 ``` 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 ] 通过实例化 a TracerProvider 并将其注册为全局跟踪器提供程序来配置 OpenTelemetry SDK。我们建议配置以下组件： + OTLP 跟踪导出器 — 向 CloudWatch 代理或 OpenTelemetry 收集器导出跟踪时需要此项 + X-Ray Propagator — 需要将跟踪上下文传播到与 X-Ray 集成的 AWS 服务 + X-Ray 远程采样器 – 使用 X-Ray 采样规则对请求进行采样时需要此组件 + 资源检测器 – 检测运行应用程序的主机的元数据 ``` 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 } ``` ------ ## 跟踪传入的请求（HTTP 处理程序检测） ------ #### [ With X-Ray SDK ] 为了使用 X-Ray 对 HTTP 处理程序进行检测，使用了 X-Ray 处理程序方法来生成分段 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 ] 要使用 HTTP 处理程序进行检测 OpenTelemetry，请使用 OpenTelemetry的 newHandler 方法来封装您的原始处理程序代码。 ``` 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 适用于 Go v2 插桩的 SDK ------ #### [ With X-Ray SDK ] 为了检测来自 AWS SDK 的传出 AWS 请求，我们对您的客户端进行了如下检测： ``` // 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 ] 的 AWS SDK for Go v2 Instrumen OpenTelemetry tion 提供了对下游 AWS SDK 调用的跟踪支持。跟踪 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 } ``` ------ ## 检测传出 HTTP 调用 ------ #### [ With X-Ray SDK ] 为了使用 X-Ray 检测传出的 HTTP 调用，使用 xray.Client 创建了所提供 HTTP 客户端的副本。 ``` myClient := xray.Client(http-client) resp, err := ctxhttp.Get(ctx, xray.Client(nil), url) ``` ------ #### [ With OpenTelemetry SDK ] 要使用 HTTP 客户端进行探测 OpenTelemetry，请使用 OpenTelemetry的 otelhttp。 NewTransport 封装 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) ``` ------ ## 对其他库的检测支持 [你可以在 Instrumentation 包下找 OpenTelemetry 到 Go 支持的库工具的完整列表。](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation#instrumentation-packages) 或者，您可以在 OpenTelemetry 注册表中搜索注册表，以了解是否 OpenTelemetry 支持在[注册](https://opentelemetry.io/ecosystem/registry/)表下为您的库提供工具。 ## 手动创建跟踪数据 ------ #### [ With X-Ray SDK ] 使用 X-Ray SDK，需要使用 BeginSegment 和 BeginSubsegment 方法来手动创建 X-Ray 分段和子分段。 ``` // 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 ] 使用自定义跨度来监控未被检测库捕获的内部活动的性能。请注意，只有服务器类跨度会转换为 X-Ray 分段，所有其他跨度均转换为 X-Ray 子分段。 首先，您需要创建一个跟踪器来生成跨度，您可以通过 `otel.Tracer` 方法来获得该跨度。这将提供在跟踪设置示例中全局注册 TracerProvider 的 Tracer 实例。您可以根据需要创建任意数量的跟踪器实例，但通常针对整个应用程序创建一个跟踪器。 ``` 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() ``` **使用 OpenTelemetry SDK 向跟踪添加注释和元数据** 在上面的示例中，`WithAttributes` 方法用于向每个跨度添加属性。请注意，默认情况下，所有跨度属性都将转换为 X-Ray 原始数据中的元数据。为确保将属性转换为注释而不是元数据，请将该属性的键添加到 `aws.xray.annotations` 属性列表中。有关更多信息，请参阅[启用自定义 X-Ray 注释](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)。 ------ ## Lambda 手动检测 ------ #### [ With X-Ray SDK ] 使用 X-Ray SDK，在 Lambda 启用*主动跟踪*后，无需进行任何其他配置即可使用 X-Ray SDK。Lambda 创建了一个表示 Lambda 处理程序调用的分段，您使用 X-Ray SDK 创建了子分段，而未进行任何其他配置。 ------ #### [ With OpenTelemetry SDK ] 以下 Lambda 函数代码（不带工具）发出 Amazon S3 ListBuckets 调用和传出 HTTP 请求。 ``` 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) } ``` 要手动检测 Lambda 处理程序和 Amazon S3 客户端，请执行以下操作： 1. 在 *main ()* 中，实例化 a TracerProvider (tp) 并将其注册为全局示踪器提供者。建议配置为： TracerProvider 1. 带有 X-Ray UDP 跨度导出程序的简单跨度处理器，用于向 Lambda 的 UDP X-Ray 端点发送跟踪数据 1. 将 *service.name* 设置为 Lambda 函数名称的资源 1. 将使用 `lambda.Start(lambdaHandler)` 更改为使用 `lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))`。 1. 通过将 OpenTelemetry 中间件附加到 Amazon S3 客户端配置`aws-sdk-go-v2`中，使用 OpenTemetry AWS SDK 工具包检测 Amazon S3 客户端。 1. 使用 OpenTelemetry's `otelhttp.NewTransport` 方法封装 http 客户端`http.DefaultTransport`。 以下代码示例展示了更改后的 Lambda 函数的样子。除了自动提供的跨度之外，您还可以手动创建其他自定义跨度。 ``` 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)...)) } ``` ------ 调用 Lambda 时，您将在控制台中`Trace Map`看到以下跟踪： CloudWatch ![\[Golang 在 CloudWatch 控制台中追踪地图。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/deprecation_golang.png)