Type to search.

AWS X-Ray connector

Serverless Preview

Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud.

Availability

  • Preview

    This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply.

Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

Stack Planned

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Planned

    We plan to add this functionality in a future Elastic Stack update. Subject to changes.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

The AWS X-Ray connector connects directly to the AWS X-Ray API. It lets an agent react to a distributed-tracing anomaly without opening the X-Ray console: pull an open insight, read what broke, snapshot the service graph, search the traces behind it, and drill into full trace detail.

Note

This connector is currently available in Agent Builder only. Workflow support is planned for a future release.

The AWS X-Ray connector signs requests to the AWS X-Ray API using AWS Signature Version 4 (SigV4). You configure an AWS Access Key ID, Secret Access Key, and AWS Region when creating the connector; every action runs under that account and region.

You can create an AWS X-Ray connector in Stack Management > Connectors.

AWS Region
The AWS region that hosts the X-Ray data you want to query, for example us-east-1 or eu-west-1. Requests are sent to xray.<region>.amazonaws.com.
Authentication
AWS Access Key ID and Secret Access Key. Both are required for every action. The IAM identity behind them needs read access to X-Ray — see Get API credentials.
Action Description
getInsightSummaries List open and closed insights for a group in a time range, optionally filtered by state. Parameters: startTime (required), endTime (required), groupArn or groupName (one required), maxResults, nextToken, states.
getInsight Get the full summary of a single insight: categories, root-cause service, impact statistics, and top anomalous services. Parameters: insightId (required).
getServiceGraph Get the service map for a time range, with per-node error, fault, and latency statistics. Parameters: startTime (required), endTime (required), groupArn, groupName, nextToken.
getTraceSummaries Search for trace IDs and summaries in a time range using an optional filter expression. Parameters: startTime (required), endTime (required), filterExpression, nextToken, sampling, samplingStrategy, timeRangeType.
batchGetTraces Retrieve full segment detail for up to 5 trace IDs. Parameters: traceIds (required, 1-5 items), nextToken.
getInsightImpactGraph Get the service graph scoped to a single insight, showing downstream services the anomaly touched. Parameters: insightId (required), startTime (required), endTime (required, must be within 6 hours of startTime), nextToken.
getInsightEvents Get the ordered timeline of states X-Ray recorded while reevaluating an insight. Parameters: insightId (required), maxResults, nextToken.
getTimeSeriesServiceStatistics Get error, fault, and response-time statistics as a time series for a service or group. Parameters: startTime (required), endTime (required), entitySelectorExpression, forecastStatistics, groupArn, groupName, nextToken, period.
getGroups List all active X-Ray groups. Parameters: nextToken.
getTraceGraph Build a service graph for a specific set of trace IDs, for per-request topology. Parameters: traceIds (required, 1-5 items), nextToken.
startTraceRetrieval Start an asynchronous historical trace retrieval job against the Transaction Search log group. Parameters: startTime (required), endTime (required), traceIds (required, up to 100 items; pass an empty array for all traces in range).
getRetrievedTracesGraph Get the service graph produced by a completed startTraceRetrieval job. Parameters: retrievalToken (required), nextToken.
getSamplingRules List all sampling rules, to audit how much trace data X-Ray is capturing. Parameters: nextToken.

All time parameters (startTime, endTime) are Unix timestamps in seconds.

Use the Action configuration settings to customize connector networking, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use xpack.actions.customHostSettings to set per-host configurations.

  1. Sign in to the AWS Management Console and open IAM.
  2. Create (or choose) an IAM user or role that will be used only for this connector, then attach a policy granting read access to X-Ray. The AWS managed policy AWSXRayReadOnlyAccess covers most actions this connector exposes, but not the Transaction Search actions startTraceRetrieval and getRetrievedTracesGraph; to use those you must additionally grant xray:StartTraceRetrieval and xray:GetRetrievedTracesGraph. To scope permissions more tightly instead, grant exactly the xray:Get*, xray:BatchGetTraces, and xray:StartTraceRetrieval actions this connector uses instead of the full xray:* namespace.
  3. Under Security credentials, create an Access key for that user and copy the Access Key ID and Secret Access Key. Store the secret access key securely — AWS only shows it once.
  4. Note the AWS region where your X-Ray traces and groups live (for example us-east-1).
  5. When configuring the connector, enter the Access Key ID, Secret Access Key, and Region.