AWS X-Ray ExecModule

Overview

AwsXRayModule brings bounded AWS X-Ray investigation and group-management operations into ValkyrAI workflows. It can find trace summaries, retrieve safe metadata for exact traces, inspect service maps and Insights, inventory X-Ray groups and sampling policy, and govern confirmed group creation, update, and deletion.

The module uses ValkyrAI's native map ABI, annotation-backed Workflow Studio discovery, and a verified IntegrationAccount. Workflow input never accepts AWS keys, session tokens, authorization headers, endpoint overrides, raw segment documents, telemetry documents, arbitrary SDK requests, sampling-rule writes, or encryption changes.

This first release is designed for release gates, SRE investigation, incident triage, service-dependency analysis, and reviewed trace-group governance. Trace reads return operational metadata rather than raw segment documents, which bounds output and reduces the chance of moving application payloads or sensitive annotations into downstream workflows. Reads may retry transient failures with bounded backoff. Every group mutation requires explicit confirmation and is sent once.

Usage

1. Create or select a least-privilege AWS identity for the exact X-Ray actions the workflow needs.
2. Store the access-key pair in an AWS IntegrationAccount.
3. Verify the account and ensure its status is READY.
4. Add AwsXRayModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose an operation, AWS region, and bounded investigation or group scope.
6. For group changes, read the current group first, review the exact filter and Insights settings, then set the matching confirmation field to true.

Never place credentials in module input. Credential-shaped fields and endpoint overrides are rejected before any AWS request.

Inputs

Common inputs

Input	Type	Required	Default	Purpose
operation	string	Yes	—	One supported X-Ray operation.
region	string	Yes	—	AWS region such as us-west-2.
nextToken	string	No	—	Opaque provider continuation token.
limit	integer	For list operations	100	Total result bound from 1 to 1,000.
returnAll	boolean	For list operations	false	Follow provider pages until limit or a provider boundary.

Trace and service-map inputs

Input	Operations	Rules
startTime / endTime	list_trace_summaries, get_service_graph	Required ISO-8601 instants. End must be after start; each window is capped at six hours.
filterExpression	list_trace_summaries	Optional X-Ray filter expression up to 2,000 characters.
traceIds	batch_get_traces	One to five unique IDs in X-Ray trace-ID form, such as 1-68fa0000-0123456789abcdef01234567.
groupName / groupArn	get_service_graph	Optional, mutually exclusive exact group selector.

batch_get_traces intentionally returns trace ID, duration, truncation state, and segment count only. Raw segment documents are not emitted because they can contain URLs, annotations, metadata, SQL statements, exceptions, and application data.

Insight inputs

Input	Operations	Rules
startTime / endTime	list_insight_summaries	Required ISO-8601 range capped at 90 days.
insightStates	list_insight_summaries	Optional unique values ACTIVE and/or CLOSED.
groupName / groupArn	list_insight_summaries	Optional, mutually exclusive exact group selector.
insightId	get_insight, list_insight_events	Exact bounded Insight identifier.

Insight results include safe summary, state, time range, category, root-cause service identity, and bounded request-impact counts. They do not include raw trace segment documents.

Group write inputs

Input	Create	Update	Delete	Rules
groupName	Required	Name or ARN	Name or ARN	Exact bounded group name.
groupArn	No	Name or ARN	Name or ARN	Mutually exclusive with groupName.
filterExpression	Required	Required	No	Complete reviewed X-Ray group filter.
insightsEnabled	Optional	Optional	No	Defaults to false.
notificationsEnabled	Optional	Optional	No	Requires insightsEnabled: true.
confirmGroupWrite	true	true	No	Confirms one exact create or update.
confirmDelete	No	No	true	Confirms exact group deletion.

update_group replaces the group filter and Insights configuration sent to AWS. Read and review the current group before constructing the full update.

Outputs

Successful execution uses a stable envelope:

Output	Meaning
status	success or error.
operation	Normalized operation name.
attempts	Provider calls, including pages and safe read retries.
resultType	Trace, service, insight, group, sampling rule, sampling statistic, or control family.
items / count	Bounded normalized results.
pages	Provider pages consumed.
hasMore / nextToken	Whether and where provider pagination may continue.
data	Bounded metadata or a group mutation receipt.
requestId	Safe AWS request reference when available.
error	Safe code, message, HTTP status, and retryability.

Normalized output excludes credentials, authorization material, raw provider exception text, segment documents, annotations, telemetry documents, and unbounded provider objects.

IntegrationAccount Requirements

The bound account must be verified, have status READY, and supply its AWS access-key ID through apiKey plus its secret access key through password. The module never serializes those values into output or logs.

Grant only the operations used by the workflow:

xray:GetTraceSummaries
xray:BatchGetTraces
xray:GetServiceGraph
xray:GetInsightSummaries
xray:GetInsight
xray:GetInsightEvents
xray:GetGroups
xray:GetSamplingRules
xray:GetSamplingStatisticSummaries
xray:CreateGroup
xray:UpdateGroup
xray:DeleteGroup

Separate read-only investigation identities from group-management identities when practical. Use IAM resource constraints for group actions where AWS supports them, and do not add segment ingestion, telemetry ingestion, resource-policy, encryption, or sampling-rule write permissions for this module release.

Configuration

The module uses ExecModuleConfig for IntegrationAccount binding, retry ceiling, and workflow policy. It does not accept endpoint overrides, custom signing hosts, inline IAM policies, cross-account role material, raw SDK requests, raw trace documents, sampling-rule write documents, or KMS configuration.

Reads use at most five attempts, bounded by configured maxAttempts. AWS SDK retries are disabled so the module owns the visible attempt count. Mutations always use one provider call, even when AWS returns a transient error.

Operations

Operation	Behavior	Side effect
list_trace_summaries	Finds bounded trace summaries for one six-hour-or-shorter window and optional filter.	None; provider read cost and quota apply.
batch_get_traces	Retrieves safe metadata for one to five exact traces; omits segment documents.	None.
get_service_graph	Reads a bounded service map, optionally for one exact X-Ray group.	None.
list_insight_summaries	Lists bounded active or closed Insights for a time range and optional group.	None.
get_insight	Reads one exact Insight summary and impact counts.	None.
list_insight_events	Reads a bounded event timeline for one Insight.	None.
list_groups	Lists bounded X-Ray group definitions and Insights settings.	None.
list_sampling_rules	Lists bounded sampling-rule policy summaries.	None.
list_sampling_statistics	Lists bounded recent request, borrow, and sampled counts.	None.
create_group	Creates one confirmed group with a complete filter and Insights configuration.	External configuration write.
update_group	Replaces one confirmed group's filter and Insights configuration.	External configuration write.
delete_group	Deletes one exact confirmed group.	Destructive.

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	An input, time range, trace ID, group selector, bound, or confirmation failed locally.	Correct input; no AWS call occurred.
INTEGRATION_ACCOUNT_ERROR	The account is missing, unverified, not READY, or incomplete.	Repair the account binding.
AWS_XRAY_HTTP_400	AWS rejected the trace, filter, insight, group, time range, or configuration.	Usually no; inspect the exact request scope.
AWS_XRAY_HTTP_403	IAM denied the action or resource.	Add only the missing least-privilege permission.
AWS_XRAY_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry; writes report ambiguity.
NETWORK_ERROR	AWS could not be reached.	Reads may retry; reconcile an attempted group write before replay.
EXECUTION_ERROR	An unexpected local failure was safely normalized.	Use logs and request references; secrets remain redacted.

AWS may commit a group mutation before the client observes a timeout. A retryable status is never permission to blindly create, replace, or delete the group again. Read the exact provider state first.

Example

This example finds slow traces for the checkout service during a reviewed deployment window:

{
  "operation": "list_trace_summaries",
  "region": "us-west-2",
  "startTime": "2026-10-23T13:00:00Z",
  "endTime": "2026-10-23T14:00:00Z",
  "filterExpression": "service(\"checkout\") AND responsetime > 1",
  "limit": 50,
  "returnAll": false
}

Expected normalized result:

{
  "status": "success",
  "operation": "list_trace_summaries",
  "attempts": 1,
  "resultType": "trace_summaries",
  "count": 1,
  "pages": 1,
  "hasMore": false,
  "items": [
    {
      "traceId": "1-68fa0000-0123456789abcdef01234567",
      "startTime": "2026-10-23T13:42:11Z",
      "durationSeconds": 1.83,
      "responseTimeSeconds": 1.71,
      "fault": false,
      "error": true,
      "throttle": false,
      "partial": false,
      "httpMethod": "POST",
      "httpStatus": 502,
      "entryPoint": "checkout",
      "serviceCount": 4
    }
  ],
  "requestId": "example-request-id"
}

The workflow can compare this bounded evidence with a reviewed release policy, inspect the service graph, request human approval, or open incident remediation. The response is a point-in-time provider read, not continuous monitoring and not a copy of raw trace payloads.

Notes

• Pagination: List operations expose nextToken; returnAll: true follows at most 100 provider pages and never returns more than limit items.
• Rate limits and cost: X-Ray quotas, retention, trace retrieval costs, and Insight availability vary by region and account. Bound time windows and avoid tight polling loops.
• Trace retention: X-Ray trace availability is controlled by AWS retention. An empty result does not prove that no request occurred outside the queried region, group, time range, or retained period.
• Filter expressions: Expressions use AWS X-Ray filter syntax. Review them as data-selection policy; the module bounds length but does not rewrite their meaning.
• Partial traces: partial and limitExceeded indicate incomplete provider material. Downstream automation should not treat incomplete trace evidence as a complete causal account.
• Sampling: Rule and statistic operations are read-only in this release. Sampling policy changes are intentionally deferred because they affect observability coverage and cost.
• Idempotency: Reads are repeatable within provider retention and freshness limits. Group creates, updates, and deletes are never automatically retried.
• Destructive behavior: delete_group removes an X-Ray group definition. It does not delete underlying traces, but it can remove an operational investigation boundary and its Insights configuration.
• Deferred capabilities: Raw segment and telemetry ingestion, sampling-rule writes, resource policies, encryption configuration, trace retrieval jobs, tag mutation, insight impact graphs, indexing rules, and direct raw segment output are intentionally deferred.
• Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed X-Ray resources are supplied.
• Functional reference: n8n's AWS integrations establish a familiar IAM credential, region, resource, operation, and pagination model. ValkyrAI applies that interaction model to X-Ray while adding strict IntegrationAccount binding, bounded investigation windows, normalized metadata-only output, explicit write confirmations, and mutation replay safety.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsXRayModule through /v1/modules/metadata.

Related documentation

• AWS X-Ray API Reference
• AWS X-Ray filter expressions
• AWS CloudWatch ExecModule