Aws/traces
Query and analyze X-Ray distributed traces for incident investigation and performance analysis.
Authentication
Uses the default AWS credential chain. Requires X-Ray permissions.
Required IAM Permissions
xray:GetServiceGraphxray:GetTraceSummaries
Usage
# Create traces model
swamp model create @webframp/aws/traces aws-traces --global-arg region=us-east-1
# Get service dependency graph
swamp model method run aws-traces get_service_graph --input startTime=1h
# Get trace summaries
swamp model method run aws-traces get_traces --input startTime=1h
# Get traces with filter expression
swamp model method run aws-traces get_traces \
--input startTime=1h \
--input 'filterExpression=service("api") AND http.status = 500'
# Get error traces (convenience method)
swamp model method run aws-traces get_errors --input errorType=fault
# Analyze error patterns
swamp model method run aws-traces analyze_errors --input startTime=6hTime Formats
The startTime and endTime parameters accept:
- Relative times:
30m,1h,2d(minutes, hours, days ago) - ISO 8601 dates:
2026-03-30T12:00:00Z
Filter Expressions
X-Ray filter expressions support:
service("name")- Filter by service namehttp.url- HTTP URLhttp.method- HTTP method (GET, POST, etc.)http.status- HTTP status coderesponsetime > 5- Response time in secondsfault = true- Traces with faults (5xx)error = true- Traces with errors (4xx)throttle = true- Throttled requests
Methods
- get_service_graph - Get service dependency graph with health statistics
- get_traces - Get trace summaries with optional filter expression
- get_errors - Get error/fault traces (convenience method)
- analyze_errors - Analyze error patterns across traces
2026.09.15.1
Changed: Bump zod 4.4.3 → 4.6.5
2026.09.14.1
Changed: Bump @aws-sdk/* 3.1126.0 → 3.1131.0 (2 packages)
2026.09.04.1
Changed: Bump @aws-sdk/* 3.1121.0 → 3.1126.0 (2 packages)
2026.08.29.1
Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.
2026.08.28.2
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.28.1
Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (2 packages)
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
Resources
2026.09.04.1
Changed: Bump @aws-sdk/* 3.1121.0 → 3.1126.0 (2 packages)
2026.08.29.1
Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.
2026.08.28.2
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.28.1
Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (2 packages)
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.29.1
Changed: Bump @aws-sdk/* 3.1120.0 → 3.1121.0. Dependency-only update; no schema, API, or behavioral changes.
2026.08.28.2
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.28.1
Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (2 packages)
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.28.2
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.28.1
Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (2 packages)
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.28.1
Changed: Bump @aws-sdk/* 3.1114.0 → 3.1120.0 (2 packages)
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.26.3
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.26.1
Fixed: Added missing description field to upgrade entry for version
2026.08.24.2. The omission caused swamp extension pull to fail with a catalog
validation error ("upgrades.N.description: Invalid input: expected string,
received undefined").
2026.08.25.1
Changed: Updated labels for improved extension discoverability. Added cross-cutting category labels (security, observability, finops, infrastructure, networking, compliance, devops, ai, incident-response) where applicable.
updated labels
2026.08.24.4
Added: list_services method — lightweight service enumeration from X-Ray
service graph data. Returns service name, type, account ID, request count,
fault/error/throttle counts, and average response time in milliseconds. A
faster alternative to get_service_graph when you only need to know which
services are active and their high-level health.
Added: service_list resource spec to store the lightweight service listing.
Modified 1 models
2026.08.24.3
Added: Output metadata attributes for observability.
durationMs: Method execution duration in milliseconds.collectedBy: Extension name that produced the data.fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).
2026.08.24.2
Fixed: Corrected installation command (swamp extension install →
swamp extension pull).
Added: Troubleshooting section documenting the parseRelativeTime silent
fallback, MAX_PAGES = 20 truncation behavior, authentication flow, and
region-default guidance.
2026.08.21.1
Changed: X-Ray API failures now surface with the operation and query
context instead of a bare SDK error. GetServiceGraph and GetTraceSummaries
calls in get_service_graph, get_traces, get_errors, and analyze_errors
now catch failures and rethrow with the group name, filter expression, or
error type that was in flight, plus the original error preserved as cause.
get_service_graph, get_traces, and get_errors previously paginated with
no page cap — a query that kept returning a NextToken could loop
indefinitely. All three now stop after 20 pages and set a new truncated
field so callers know when results are incomplete instead of silently getting
a partial page with no signal.
get_traces and get_errors also previously accepted any limit value,
including 0 or unbounded numbers; limit is now constrained to 1-1000.
2026.08.20.1
Changed: Bump @aws-sdk/* 3.1111.0 → 3.1114.0 (2 packages)
2026.08.15.1
Changed: Bump @aws-sdk/* 3.1104.0 → 3.1111.0 (2 packages)
2026.08.05.1
Changed: Bump @aws-sdk/* 3.1101.0 → 3.1104.0 (2 packages)
2026.08.02.1
Changed: Bump @aws-sdk/* 3.1100.0 → 3.1101.0 (2 packages)
2026.08.01.1
Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.08.20.1
Changed: Bump @aws-sdk/* 3.1111.0 → 3.1114.0 (2 packages)
2026.08.15.1
Changed: Bump @aws-sdk/* 3.1104.0 → 3.1111.0 (2 packages)
2026.08.05.1
Changed: Bump @aws-sdk/* 3.1101.0 → 3.1104.0 (2 packages)
2026.08.02.1
Changed: Bump @aws-sdk/* 3.1100.0 → 3.1101.0 (2 packages)
2026.08.01.1
Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.08.15.1
Changed: Bump @aws-sdk/* 3.1104.0 → 3.1111.0 (2 packages)
2026.08.05.1
Changed: Bump @aws-sdk/* 3.1101.0 → 3.1104.0 (2 packages)
2026.08.02.1
Changed: Bump @aws-sdk/* 3.1100.0 → 3.1101.0 (2 packages)
2026.08.01.1
Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.08.05.1
Changed: Bump @aws-sdk/* 3.1101.0 → 3.1104.0 (2 packages)
2026.08.02.1
Changed: Bump @aws-sdk/* 3.1100.0 → 3.1101.0 (2 packages)
2026.08.01.1
Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.08.02.1
Changed: Bump @aws-sdk/* 3.1100.0 → 3.1101.0 (2 packages)
2026.08.01.1
Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.08.01.1
Fixed: Broken model-upgrade chain. The prior version bump (to 2026.07.31.1) updated version but left the upgrades array terminating one step short, which blocks swamp extension push ("model upgrade chain errors"). That version never actually published — the registry was still serving 2026.07.30.1. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.1.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.07.30.1
Added: Optional profile global argument for multi-account credential resolution.
When set, credentials resolve via fromIni (supports SSO token cache and shared-config
profiles). When omitted, the default credential chain applies as before. Fully backward
compatible — no changes required for existing instances.
2026.07.29.1
Fixed: Terminate upgrade chain at current version (extension was uninstallable due to broken upgrade chain).
2026.07.27.1
Changed: Bump @aws-sdk/client-xray 3.1094.0 → 3.1096.0
2026.07.24.1
Changed: Bump AWS SDK from 3.1091.0 to 3.1094.0 (patch-level update).
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned