# AWS X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). The X-Ray SDK for Go is a set of libraries for Go applications that provide classes and methods for generating and sending trace data to the X-Ray daemon. Trace data includes information about incoming HTTP requests served by the application, and calls that the application makes to downstream services using the AWS SDK, HTTP clients, or an SQL database connector. You can also create segments manually and add debug information in annotations and metadata. Download the SDK from its [GitHub repository](https://github.com/aws/aws-xray-sdk-go) with `go get`: ``` $ go get -u github.com/aws/aws-xray-sdk-go/... ``` For web applications, start by [using the `xray.Handler` function](xray-sdk-go-handler.md) to trace incoming requests. The message handler creates a [segment](xray-concepts.md#xray-concepts-segments) for each traced request, and completes the segment when the response is sent. While the segment is open you can use the SDK client's methods to add information to the segment and create subsegments to trace downstream calls. The SDK also automatically records exceptions that your application throws while the segment is open. For Lambda functions called by an instrumented application or service, Lambda reads the [tracing header](xray-concepts.md#xray-concepts-tracingheader) and traces sampled requests automatically. For other functions, you can [configure Lambda](xray-services-lambda.md) to sample and trace incoming requests. In either case, Lambda creates the segment and provides it to the X-Ray SDK. **Note** On Lambda, the X-Ray SDK is optional. If you don't use it in your function, your service map will still include a node for the Lambda service, and one for each Lambda function. By adding the SDK, you can instrument your function code to add subsegments to the function segment recorded by Lambda. See [AWS Lambda and AWS X-Ray](xray-services-lambda.md) for more information. Next, [wrap your client with a call to the `AWS` function](xray-sdk-go-awssdkclients.md). This step ensures that X-Ray instruments calls to any client methods. You can also [instrument calls to SQL databases](xray-sdk-go-sqlclients.md). After you start using the SDK, customize its behavior by [configuring the recorder and middleware](xray-sdk-go-configuration.md). You can add plugins to record data about the compute resources running your application, customize sampling behavior by defining sampling rules, and set the log level to see more or less information from the SDK in your application logs. Record additional information about requests and the work that your application does in [annotations and metadata](xray-sdk-go-segment.md). Annotations are simple key-value pairs that are indexed for use with [filter expressions](xray-console-filters.md), so that you can search for traces that contain specific data. Metadata entries are less restrictive and can record entire objects and arrays — anything that can be serialized into JSON. **Annotations and Metadata** Annotations and metadata are arbitrary text that you add to segments with the X-Ray SDK. Annotations are indexed for use with filter expressions. Metadata are not indexed, but can be viewed in the raw segment with the X-Ray console or API. Anyone that you grant read access to X-Ray can view this data. When you have a lot of instrumented clients in your code, a single request segment can contain a large number of subsegments, one for each call made with an instrumented client. You can organize and group subsegments by wrapping client calls in [custom subsegments](xray-sdk-go-subsegments.md). You can create a custom subsegment for an entire function or any section of code, and record metadata and annotations on the subsegment instead of writing everything on the parent segment. ## Requirements The X-Ray SDK for Go requires Go 1.9 or later. The SDK depends on the following libraries at compile and runtime: + AWS SDK for Go version 1.10.0 or newer These dependencies are declared in the SDK's `README.md` file. ## Reference documentation Once you have downloaded the SDK, build and host the documentation locally to view it in a web browser. **To view the reference documentation** 1. Navigating to the `$GOPATH/src/github.com/aws/aws-xray-sdk-go` (Linux or Mac) directory or the `%GOPATH%\src\github.com\aws\aws-xray-sdk-go` (Windows) folder 1. Run the `godoc` command. ``` $ godoc -http=:6060 ``` 1. Opening a browser at `http://localhost:6060/pkg/github.com/aws/aws-xray-sdk-go/`. # Configuring the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). You can specify the configuration for X-Ray SDK for Go through environment variables, by calling `Configure` with a `Config` object, or by assuming default values. Environment variables take precedence over `Config` values, which take precedence over any default value. **Topics** + [Service plugins](#xray-sdk-go-configuration-plugins) + [Sampling rules](#xray-sdk-go-configuration-sampling) + [Logging](#xray-sdk-go-configuration-logging) + [Environment variables](#xray-sdk-go-configuration-envvars) + [Using configure](#xray-sdk-go-configuration-configure) ## Service plugins Use `plugins` to record information about the service hosting your application. **Plugins** + Amazon EC2 – `EC2Plugin` adds the instance ID, Availability Zone, and the CloudWatch Logs Group. + Elastic Beanstalk – `ElasticBeanstalkPlugin` adds the environment name, version label, and deployment ID. + Amazon ECS – `ECSPlugin` adds the container ID. ![\[Segment - Scorekeep details showing Elastic Beanstalk, EC2, and Xray configuration information.\]](http://docs.aws.amazon.com/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-go.png) To use a plugin, import one of the following packages. ``` "github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/awsplugins/ecs" "github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk" ``` Each plugin has an explicit `Init()` function call that loads the plugin. **Example ec2.Init()** ``` import ( "os" "github.com/aws/aws-xray-sdk-go/awsplugins/ec2" "github.com/aws/aws-xray-sdk-go/xray" ) func init() { // conditionally load plugin if os.Getenv("ENVIRONMENT") == "production" { ec2.Init() } xray.Configure(xray.Config{ ServiceVersion: "1.2.3", }) } ``` The SDK also uses plugin settings to set the `origin` field on the segment. This indicates the type of AWS resource that runs your application. When you use multiple plugins, the SDK uses the following resolution order to determine the origin: ElasticBeanstalk > EKS > ECS > EC2. ## Sampling rules The SDK uses the sampling rules you define in the X-Ray console to determine which requests to record. The default rule traces the first request each second, and five percent of any additional requests across all services sending traces to X-Ray. [Create additional rules in the X-Ray console](xray-console-sampling.md) to customize the amount of data recorded for each of your applications. The SDK applies custom rules in the order in which they are defined. If a request matches multiple custom rules, the SDK applies only the first rule. **Note** If the SDK can't reach X-Ray to get sampling rules, it reverts to a default local rule of the first request each second, and five percent of any additional requests per host. This can occur if the host doesn't have permission to call sampling APIs, or can't connect to the X-Ray daemon, which acts as a TCP proxy for API calls made by the SDK. You can also configure the SDK to load sampling rules from a JSON document. The SDK can use local rules as a backup for cases where X-Ray sampling is unavailable, or use local rules exclusively. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` This example defines one custom rule and a default rule. The custom rule applies a five-percent sampling rate with no minimum number of requests to trace for paths under `/api/move/`. The default rule traces the first request each second and 10 percent of additional requests. The disadvantage of defining rules locally is that the fixed target is applied by each instance of the recorder independently, instead of being managed by the X-Ray service. As you deploy more hosts, the fixed rate is multiplied, making it harder to control the amount of data recorded. On AWS Lambda, you cannot modify the sampling rate. If your function is called by an instrumented service, calls that generated requests that were sampled by that service will be recorded by Lambda. If active tracing is enabled and no tracing header is present, Lambda makes the sampling decision. To provide backup rules, point to the local sampling JSON file by using `NewCentralizedStrategyWithFilePath`. **Example main.go – Local sampling rule** ``` s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` To use only local rules, point to the local sampling JSON file by using `NewLocalizedStrategyFromFilePath`. **Example main.go – Disable sampling** ``` s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json xray.Configure(xray.Config{SamplingStrategy: s}) ``` ## Logging **Note** The `xray.Config{}` fields `LogLevel` and `LogFormat` are deprecated starting with version 1.0.0-rc.10. X-Ray uses the following interface for logging. The default logger writes to `stdout` at `LogLevelInfo` and above. ``` type Logger interface { Log(level LogLevel, msg fmt.Stringer) } const ( LogLevelDebug LogLevel = iota + 1 LogLevelInfo LogLevelWarn LogLevelError ) ``` **Example write to `io.Writer`** ``` xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError)) ``` ## Environment variables You can use environment variables to configure the X-Ray SDK for Go. The SDK supports the following variables. + `AWS_XRAY_CONTEXT_MISSING` – Set to `RUNTIME_ERROR` to throw exceptions when your instrumented code attempts to record data when no segment is open. **Valid Values** + `RUNTIME_ERROR` – Throw a runtime exception. + `LOG_ERROR` – Log an error and continue (default). + `IGNORE_ERROR` – Ignore error and continue. Errors related to missing segments or subsegments can occur when you attempt to use an instrumented client in startup code that runs when no request is open, or in code that spawns a new thread. + `AWS_XRAY_TRACING_NAME` – Set the service name that the SDK uses for segments. + `AWS_XRAY_DAEMON_ADDRESS` – Set the host and port of the X-Ray daemon listener. By default, the SDK sends trace data to `127.0.0.1:2000`. Use this variable if you have configured the daemon to [listen on a different port](xray-daemon-configuration.md) or if it is running on a different host. + `AWS_XRAY_CONTEXT_MISSING` – Set the value to determine how the SDK handles missing context errors. Errors related to missing segments or subsegments can occur when you attempt to use an instrumented client in the startup code when no request is open, or in code that spawns a new thread. + `RUNTIME_ERROR` – By default, the SDK is set to throw a runtime exception. + `LOG_ERROR` – Set to log an error and continue. Environment variables override equivalent values set in code. ## Using configure You can also configure the X-Ray SDK for Go using the `Configure` method. `Configure` takes one argument, a `Config` object, with the following, optional fields. DaemonAddr This string specifies the host and port of the X-Ray daemon listener. If not specified, X-Ray uses the value of the `AWS_XRAY_DAEMON_ADDRESS` environment variable. If that value is not set, it uses "127.0.0.1:2000". ServiceVersion This string specifies the version of the service. If not specified, X-Ray uses the empty string (""). SamplingStrategy This `SamplingStrategy` object specifies which of your application calls are traced. If not specified, X-Ray uses a `LocalizedSamplingStrategy`, which takes the strategy as defined in `xray/resources/DefaultSamplingRules.json`. StreamingStrategy This `StreamingStrategy` object specifies whether to stream a segment when **RequiresStreaming** returns **true**. If not specified, X-Ray uses a `DefaultStreamingStrategy` that streams a sampled segment if the number of subsegments is greater than 20. ExceptionFormattingStrategy This `ExceptionFormattingStrategy` object specifies how you want to handle various exceptions. If not specified, X-Ray uses a `DefaultExceptionFormattingStrategy` with an `XrayError` of type `error`, the error message, and stack trace. # Instrumenting incoming HTTP requests with the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). You can use the X-Ray SDK to trace incoming HTTP requests that your application serves on an EC2 instance in Amazon EC2, AWS Elastic Beanstalk, or Amazon ECS. Use `xray.Handler` to instrument incoming HTTP requests. The X-Ray SDK for Go implements the standard Go library `http.Handler` interface in the `xray.Handler` class to intercept web requests. The `xray.Handler` class wraps the provided `http.Handler` with `xray.Capture` using the request's context, parsing the incoming headers, adding response headers if needed, and sets HTTP-specific trace fields. When you use this class to handle HTTP requests and responses, the X-Ray SDK for Go creates a segment for each sampled request. This segment includes timing, method, and disposition of the HTTP request. Additional instrumentation creates subsegments on this segment. **Note** For AWS Lambda functions, Lambda creates a segment for each sampled request. See [AWS Lambda and AWS X-Ray](xray-services-lambda.md) for more information. The following example intercepts requests on port 8000 and returns "Hello\$1" as a response. It creates the segment `myApp` and instruments calls through any application. **Example main.go** ``` 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) } ``` Each segment has a name that identifies your application in the service map. The segment can be named statically, or you can configure the SDK to name it dynamically based on the host header in the incoming request. Dynamic naming lets you group traces based on the domain name in the request, and apply a default name if the name doesn't match an expected pattern (for example, if the host header is forged). **Forwarded Requests** If a load balancer or other intermediary forwards a request to your application, X-Ray takes the client IP from the `X-Forwarded-For` header in the request instead of from the source IP in the IP packet. The client IP that is recorded for a forwarded request can be forged, so it should not be trusted. When a request is forwarded, the SDK sets an additional field in the segment to indicate this. If the segment contains the field `x_forwarded_for` set to `true`, the client IP was taken from the `X-Forwarded-For` header in the HTTP request. The handler creates a segment for each incoming request with an `http` block that contains the following information: + **HTTP method** – GET, POST, PUT, DELETE, etc. + **Client address** – The IP address of the client that sent the request. + **Response code** – The HTTP response code for the completed request. + **Timing** – The start time (when the request was received) and end time (when the response was sent). + **User agent** — The `user-agent` from the request. + **Content length** — The `content-length` from the response. ## Configuring a segment naming strategy AWS X-Ray uses a *service name* to identify your application and distinguish it from the other applications, databases, external APIs, and AWS resources that your application uses. When the X-Ray SDK generates segments for incoming requests, it records your application's service name in the segment's [name field](xray-api-segmentdocuments.md#api-segmentdocuments-fields). The X-Ray SDK can name segments after the hostname in the HTTP request header. However, this header can be forged, which could result in unexpected nodes in your service map. To prevent the SDK from naming segments incorrectly due to requests with forged host headers, you must specify a default name for incoming requests. If your application serves requests for multiple domains, you can configure the SDK to use a dynamic naming strategy to reflect this in segment names. A dynamic naming strategy allows the SDK to use the hostname for requests that match an expected pattern, and apply the default name to requests that don't. For example, you might have a single application serving requests to three subdomains– `www.example.com`, `api.example.com`, and `static.example.com`. You can use a dynamic naming strategy with the pattern `*.example.com` to identify segments for each subdomain with a different name, resulting in three service nodes on the service map. If your application receives requests with a hostname that doesn't match the pattern, you will see a fourth node on the service map with a fallback name that you specify. To use the same name for all request segments, specify the name of your application when you create the handler, as shown in the previous section. **Note** You can override the default service name that you define in code with the `AWS_XRAY_TRACING_NAME` [environment variable](xray-sdk-go-configuration.md#xray-sdk-go-configuration-envvars). A dynamic naming strategy defines a pattern that hostnames should match, and a default name to use if the hostname in the HTTP request doesn't match the pattern. To name segments dynamically, use `NewDynamicSegmentNamer` to configure the default name and pattern to match. **Example main.go** If the hostname in the request matches the pattern `*.example.com`, use the hostname. Otherwise, use `MyApp`. ``` func main() { http.Handle("/", xray.Handler(xray.NewDynamicSegmentNamer("MyApp", "*.example.com"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("Hello!")) }))) http.ListenAndServe(":8000", nil) } ``` # Tracing AWS SDK calls with the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). When your application makes calls to AWS services to store data, write to a queue, or send notifications, the X-Ray SDK for Go tracks the calls downstream in [subsegments](xray-sdk-go-subsegments.md). Traced AWS services and resources that you access within those services (for example, an Amazon S3 bucket or Amazon SQS queue), appear as downstream nodes on the trace map in the X-Ray console. To trace AWS SDK clients, wrap the client object with the `xray.AWS()` call as shown in the following example. **Example main.go** ``` var dynamo *dynamodb.DynamoDB func main() { dynamo = dynamodb.New(session.Must(session.NewSession())) xray.AWS(dynamo.Client) } ``` Then, when you use the AWS SDK client, use the `withContext` version of the call method, and pass it the `context` from the `http.Request` object passed to the [handler](xray-sdk-go-handler.md). **Example main.go – AWS SDK call** ``` func listTablesWithContext(ctx context.Context) { output := dynamo.ListTablesWithContext(ctx, &dynamodb.ListTablesInput{}) doSomething(output) } ``` For all services, you can see the name of the API called in the X-Ray console. For a subset of services, the X-Ray SDK adds information to the segment to provide more granularity in the service map. For example, when you make a call with an instrumented DynamoDB client, the SDK adds the table name to the segment for calls that target a table. In the console, each table appears as a separate node in the service map, with a generic DynamoDB node for calls that don't target a table. **Example Subsegment for a call to DynamoDB to save an item** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` When you access named resources, calls to the following services create additional nodes in the service map. Calls that don't target specific resources create a generic node for the service. + **Amazon DynamoDB** – Table name + **Amazon Simple Storage Service** – Bucket and key name + **Amazon Simple Queue Service** – Queue name # Tracing calls to downstream HTTP web services with the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). When your application makes calls to microservices or public HTTP APIs, you can use the `xray.Client` to instrument those calls as subsegments of your Go application, as shown in the following example, where *http-client* is an HTTP client. The client creates a shallow copy of the provided HTTP client, defaulting to `http.DefaultClient`, with roundtripper wrapped with `xray.RoundTripper`. **Example** ``` myClient := xray.Client(http-client) ``` The following example instruments the outgoing HTTP call with the ctxhttp library using `xray.Client`. `ctx` can be passed from the upstream call. This ensures that the existing segment context is used. For example, X-Ray does not allow a new segment to be created within a Lambda function, so the existing Lambda segment context should be used. ``` resp, err := ctxhttp.Get(ctx, xray.Client(nil), url) ``` # Tracing SQL queries with the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). To trace SQL calls to PostgreSQL or MySQL, replacing `sql.Open` calls to `xray.SQLContext`, as shown in the following example. Use URLs instead of configuration strings if possible. **Example main.go** ``` func main() { db, err := xray.SQLContext("postgres", "postgres://user:password@host:port/db") row, err := db.QueryRowContext(ctx, "SELECT 1") // Use as normal } ``` # Generating custom subsegments with the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). Subsegments extend a trace's [segment](xray-concepts.md#xray-concepts-segments) with details about work done in order to serve a request. Each time you make a call with an instrumented client, the X-Ray SDK records the information generated in a subsegment. You can create additional subsegments to group other subsegments, to measure the performance of a section of code, or to record annotations and metadata. Use the `Capture` method to create a subsegment around a function. **Example main.go – Custom subsegment** ``` func criticalSection(ctx context.Context) { //this is an example of a subsegment xray.Capture(ctx, "GameModel.saveGame", func(ctx1 context.Context) error { var err error section.Lock() result := someLockedResource.Go() section.Unlock() xray.AddMetadata(ctx1, "ResourceResult", result) }) ``` The following screenshot shows an example of how the `saveGame` subsegment might appear in traces for the application `Scorekeep`. ![\[Trace timeline showing Scorekeep application segments, including DynamoDB operations and GameModel saveGame subsegment.\]](http://docs.aws.amazon.com/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png) # Add annotations and metadata to segments with the X-Ray SDK for Go **Note** X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). You can record additional information about requests, the environment, or your application with annotations and metadata. You can add annotations and metadata to the segments that the X-Ray SDK creates, or to custom subsegments that you create. **Annotations** are key-value pairs with string, number, or Boolean values. Annotations are indexed for use with [filter expressions](xray-console-filters.md). Use annotations to record data that you want to use to group traces in the console, or when calling the [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API. **Metadata** are key-value pairs that can have values of any type, including objects and lists, but are not indexed for use with filter expressions. Use metadata to record additional data that you want stored in the trace but don't need to use with search. In addition to annotations and metadata, you can also [record user ID strings](#xray-sdk-go-segment-userid) on segments. User IDs are recorded in a separate field on segments and are indexed for use with search. **Topics** + [Recording annotations with the X-Ray SDK for Go](#xray-sdk-go-segment-annotations) + [Recording metadata with the X-Ray SDK for Go](#xray-sdk-go-segment-metadata) + [Recording user IDs with the X-Ray SDK for Go](#xray-sdk-go-segment-userid) ## Recording annotations with the X-Ray SDK for Go Use annotations to record information on segments that you want indexed for search. **Annotation Requirements** + **Keys** – The key for an X-Ray annotation can have up to 500 alphanumeric characters. You cannot use spaces or symbols other than a dot or period ( . ) + **Values** – The value for an X-Ray annotation can have up to 1,000 Unicode characters. + The number of **Annotations** – You can use up to 50 annotations per trace. To record annotations, call `AddAnnotation` with a string containing the metadata you want to associate with the segment. ``` xray.AddAnnotation(key string, value interface{}) ``` The SDK records annotations as key-value pairs in an `annotations` object in the segment document. Calling `AddAnnotation` twice with the same key overwrites previously recorded values on the same segment. To find traces that have annotations with specific values, use the `annotation[key]` keyword in a [filter expression](xray-console-filters.md). ## Recording metadata with the X-Ray SDK for Go Use metadata to record information on segments that you don't need indexed for search. To record metadata, call `AddMetadata` with a string containing the metadata you want to associate with the segment. ``` xray.AddMetadata(key string, value interface{}) ``` ## Recording user IDs with the X-Ray SDK for Go Record user IDs on request segments to identify the user who sent the request. **To record user IDs** 1. Get a reference to the current segment from `AWSXRay`. ``` import ( "context" "github.com/aws/aws-xray-sdk-go/xray" ) mySegment := xray.GetSegment(context) ``` 1. Call `setUser` with a String ID of the user who sent the request. ``` mySegment.User = "U12345" ``` To find traces for a user ID, use the `user` keyword in a [filter expression](xray-console-filters.md).