# AWS X-Ray SDK for Ruby **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 is a library for Ruby web applications that provides 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 active record client. You can also create segments manually and add debug information in annotations and metadata. You can download the SDK by adding it to your gemfile and running `bundle install`. **Example Gemfile** ``` gem 'aws-sdk' ``` If you use Rails, start by [adding the X-Ray SDK middleware](xray-sdk-ruby-middleware.md) to trace incoming requests. A request filter creates a [segment](xray-concepts.md#xray-concepts-segments). 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 non-Rails applications, you can [create segments manually](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual). Next, use the X-Ray SDK to instrument your AWS SDK for Ruby, HTTP, and SQL clients by [configuring the recorder](xray-sdk-ruby-patching.md) to patch the associated libraries. Whenever you make a call to a downstream AWS service or resource with an instrumented client, the SDK records information about the call in a subsegment. AWS services and the resources that you access within the services appear as downstream nodes on the trace map to help you identify errors and throttling issues on individual connections. Once you get going with the SDK, customize its behavior by [configuring the recorder](xray-sdk-ruby-configuration.md). You can add plugins to record data about the compute resources running your application, customize sampling behavior by defining sampling rules, and provide a logger 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-ruby-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-ruby-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. For reference documentation for the SDK's classes and methods, see the [AWS X-Ray SDK for Ruby API Reference](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference). ## Requirements The X-Ray SDK requires Ruby 2.3 or later and is compatible with the following libraries: + AWS SDK for Ruby version 3.0 or later + Rails version 5.1 or later # Configuring the X-Ray SDK for Ruby **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 Ruby has a class named `XRay.recorder` that provides the global recorder. You can configure the global recorder to customize the middleware that creates segments for incoming HTTP calls. **Topics** + [Service plugins](#xray-sdk-ruby-configuration-plugins) + [Sampling rules](#xray-sdk-ruby-configuration-sampling) + [Logging](#xray-sdk-ruby-configuration-logging) + [Recorder configuration in code](#xray-sdk-ruby-configuration-code) + [Recorder configuration with rails](#xray-sdk-ruby-middleware-configuration-rails) + [Environment variables](#xray-sdk-ruby-configuration-envvars) ## Service plugins Use `plugins` to record information about the service hosting your application. **Plugins** + Amazon EC2 – `ec2` adds the instance ID and Availability Zone. + Elastic Beanstalk – `elastic_beanstalk` adds the environment name, version label, and deployment ID. + Amazon ECS – `ecs` adds the container ID. ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) To use plugins, specify it in the configuration object that you pass to the recorder. **Example main.rb – Plugin configuration** ``` my_plugins = %I[ec2 elastic_beanstalk] config = { plugins: my_plugins, name: 'my app', } XRay.recorder.configure(config) ``` You can also use [environment variables](#xray-sdk-ruby-configuration-envvars), which take precedence over values set in code, to configure the recorder. 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. To configure backup rules, define a hash for the document in the configuration object that you pass to the recorder. **Example main.rb – Backup rule configuration** ``` require 'aws-xray-sdk' my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config) ``` To store the sampling rules independently, define the hash in a separate file and require the file to pull it into your application. **Example config/sampling-rules.rb** ``` my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } ``` **Example main.rb – Sampling rule from a file** ``` require 'aws-xray-sdk' require 'config/sampling-rules.rb' config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config) ``` To use only local rules, require the sampling rules and configure the `LocalSampler`. **Example main.rb – Local rule sampling** ``` require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config) ``` You can also configure the global recorder to disable sampling and instrument all incoming requests. **Example main.rb – Disable sampling** ``` require 'aws-xray-sdk' config = { sampling: false, name: 'my app', } XRay.recorder.configure(config) ``` ## Logging By default, the recorder outputs info-level events to `$stdout`. You can customize logging by defining a [logger](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) in the configuration object that you pass to the recorder. **Example main.rb – Logging** ``` require 'aws-xray-sdk' config = { logger: my_logger, name: 'my app', } XRay.recorder.configure(config) ``` Use debug logs to identify issues, such as unclosed subsegments, when you [generate subsegments manually](xray-sdk-ruby-subsegments.md). ## Recorder configuration in code Additional settings are available from the `configure` method on `XRay.recorder`. + `context_missing` – Set to `LOG_ERROR` to avoid throwing exceptions when your instrumented code attempts to record data when no segment is open. + `daemon_address` – Set the host and port of the X-Ray daemon listener. + `name` – Set a service name that the SDK uses for segments. + `naming_pattern` – Set a domain name pattern to use [dynamic naming](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming). + `plugins` – Record information about your application's AWS resources with [plugins](#xray-sdk-ruby-configuration-plugins). + `sampling` – Set to `false` to disable sampling. + `sampling_rules` – Set the hash containing your [sampling rules](#xray-sdk-ruby-configuration-sampling). **Example main.rb – Disable context missing exceptions** ``` require 'aws-xray-sdk' config = { context_missing: 'LOG_ERROR' } XRay.recorder.configure(config) ``` ## Recorder configuration with rails If you use the Rails framework, you can configure options on the global recorder in a Ruby file under `app_root/initializers`. The X-Ray SDK supports an additional configuration key for use with Rails. + `active_record` – Set to `true` to record subsegments for Active Record database transactions. Configure the available settings in a configuration object named `Rails.application.config.xray`. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ## Environment variables You can use environment variables to configure the X-Ray SDK for Ruby. The SDK supports the following variables: + `AWS_XRAY_TRACING_NAME` – Set a service name that the SDK uses for segments. Overrides the service name that you set on the servlet filter's [segment naming strategy](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming). + `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 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. Environment variables override values set in code. # Tracing incoming requests with the X-Ray SDK for Ruby middleware **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. If you use Rails, use the Rails middleware to instrument incoming HTTP requests. When you add the middleware to your application and configure a segment name, the X-Ray SDK for Ruby creates a segment for each sampled request. Any segments created by additional instrumentation become subsegments of the request-level segment that provides information about the HTTP request and response. This information includes timing, method, and disposition of the request. 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 middleware 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. ## Using the rails middleware To use the middleware, update your gemfile to include the required [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html). **Example Gemfile - rails** ``` gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie'] ``` To use the middleware, you must also [configure the recorder](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails) with a name that represents the application in the trace map. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app' } ``` ## Instrumenting code manually If you don't use Rails, create segments manually. You can create a segment for each incoming request, or create segments around patched HTTP or AWS SDK clients to provide context for the recorder to add subsegments. ``` # Start a segment segment = XRay.recorder.begin_segment 'my_service' # Start a subsegment subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote' # Add metadata or annotation here if necessary my_annotations = { k1: 'v1', k2: 1024 } segment.annotations.update my_annotations # Add metadata to default namespace subsegment.metadata[:k1] = 'v1' # Set user for the segment (subsegment is not supported) segment.user = 'my_name' # End segment/subsegment XRay.recorder.end_subsegment XRay.recorder.end_segment ``` ## 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 configure the recorder, as shown in the [previous sections](#xray-sdk-ruby-middleware-rails). 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, specify a naming pattern in the config hash. **Example main.rb – Dynamic naming** ``` config = { naming_pattern: '*mydomain*', name: 'my app', } XRay.recorder.configure(config) ``` You can use '\$1' in the pattern to match any string, or '?' to match any single character. **Note** You can override the default service name that you define in code with the `AWS_XRAY_TRACING_NAME` [environment variable](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars). # Patching libraries to instrument downstream calls **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 instrument downstream calls, use the X-Ray SDK for Ruby to patch the libraries that your application uses. The X-Ray SDK for Ruby can patch the following libraries. **Supported Libraries** + `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)` – Instrument HTTP clients. + `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)` – Instrument AWS SDK for Ruby clients. When you use a patched library, the X-Ray SDK for Ruby creates a subsegment for the call and records information from the request and response. A segment must be available for the SDK to create the subsegment, either from the SDK middleware or a call to `XRay.recorder.begin_segment`. To patch libraries, specify them in the configuration object that you pass to the X-Ray recorder. **Example main.rb – Patch libraries** ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http aws_sdk] } XRay.recorder.configure(config) ``` # Tracing AWS SDK calls with the X-Ray SDK for Ruby **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 Ruby tracks the calls downstream in [subsegments](xray-sdk-ruby-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. The X-Ray SDK for Ruby automatically instruments all AWS SDK clients when you [patch the `aws-sdk` library](xray-sdk-ruby-patching.md). You cannot instrument individual clients. 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 # Generating custom subsegments with the X-Ray SDK **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. To manage subsegments, use the `begin_subsegment` and `end_subsegment` methods. ``` subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote' my_annotations = { id: 12345 } subsegment.annotations.update my_annotations XRay.recorder.end_subsegment ``` To create a subsegment for a function, wrap it in a call to `XRay.recorder.capture`. ``` XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' resp end ``` When you create a subsegment within a segment or another subsegment, the X-Ray SDK generates an ID for it and records the start time and end time. **Example Subsegment with metadata** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` # Add annotations and metadata to segments with the X-Ray SDK for Ruby **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-ruby-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 Ruby](#xray-sdk-ruby-segment-annotations) + [Recording metadata with the X-Ray SDK for Ruby](#xray-sdk-ruby-segment-metadata) + [Recording user IDs with the X-Ray SDK for Ruby](#xray-sdk-ruby-segment-userid) ## Recording annotations with the X-Ray SDK for Ruby Use annotations to record information on segments or subsegments 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** 1. Get a reference to the current segment or subsegment from `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` or ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Call `update` with a hash value. ``` my_annotations = { id: 12345 } document.annotations.update my_annotations ``` The following is an example that shows how to call `update` with an annotation key that contains a dot. ``` my_annotations = { testkey.test: 12345 } document.annotations.update my_annotations ``` The SDK records annotations as key-value pairs in an `annotations` object in the segment document. Calling `add_annotations` twice with the same key overwrites previously recorded values on the same segment or subsegment. 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 Ruby Use metadata to record information on segments or subsegments that you don't need indexed for search. Metadata values can be strings, numbers, Booleans, or any object that can be serialized into a JSON object or array. **To record metadata** 1. Get a reference to the current segment or subsegment from `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` or ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Call `metadata` with a String key; a Boolean, Number, String, or Object value; and a String namespace. ``` my_metadata = { my_namespace: { key: 'value' } } subsegment.metadata my_metadata ``` Calling `metadata` twice with the same key overwrites previously recorded values on the same segment or subsegment. ## Recording user IDs with the X-Ray SDK for Ruby 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 `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. Set the user field on the segment to a String ID of the user who sent the request. ``` segment.user = 'U12345' ``` You can set the user in your controllers to record the user ID as soon as your application starts processing a request. To find traces for a user ID, use the `user` keyword in a [filter expression](xray-console-filters.md).