使用 SDK 进行手动检测跟踪传入的请求（HTTP 处理程序检测）AWS 适用于 Go v2 插桩的 SDK 检测传出 HTTP 调用对其他库的仪器支持手动创建跟踪数据 Lambda 手动检测

迁移到 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-Remote Sampler — 使用 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 处理程序检测）

AWS 适用于 Go v2 插桩的 SDK

检测传出 HTTP 调用

对其他库的仪器支持

你可以在 Instrumentation 包下找 OpenTelemetry 到 Go 支持的库工具的完整列表。

或者，您可以在 OpenTelemetry 注册表中搜索注册表，以了解是否 OpenTelemetry 支持在注册表下为您的库提供工具。

手动创建跟踪数据

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 子分段。

首先，你需要创建一个 Tracer 来生成跨度，你可以通过该otel.Tracer方法获得跨度。这将提供在跟踪设置示例中全局注册 TracerProvider 的 Tracer 实例。您可以根据需要创建任意数量的 Tracer 实例，但通常为整个应用程序使用一个 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方法用于向每个跨度添加属性。请注意，默认情况下，所有 span 属性都将转换为 X-Ray 原始数据中的元数据。为确保将属性转换为注释而不是元数据，请将该属性的键添加到aws.xray.annotations属性列表中。有关更多信息，请参见启用自定义 X-Ray 注释。

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 客户端，请执行以下操作：

在 main () 中，实例化 a TracerProvider (tp) 并将其注册为全局示踪器提供者。建议配置为： TracerProvider
1. 带有 X-Ray UDP 跨度导出器的简单跨度处理器，可向 Lambda 的 UDP X-Ray 端点发送跟踪
2. 将 service.name 设置为 Lambda 函数名称的资源
将的用法更改lambda.Start(lambdaHandler)为lambda.Start(otellambda.InstrumentHandler(lambdaHandler, xrayconfig.WithRecommendedOptions(tp)...))。
通过将 OpenTelemetry 中间件附加到 Amazon S3 客户端配置aws-sdk-go-v2中，使用 OpenTemetry AWS SDK 工具包检测 Amazon S3 客户端。
使用 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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

迁移到 OpenTelemetry Java

迁移到 OpenTelemetry Node.js