Skip to main content
← back to extensions

Aws/traces

@webframp/aws/tracesv2026.10.21.1· Apache-2.0· 10d agoBEHAVIORS
01README

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:GetServiceGraph
  • xray: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=6h

Time 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 name
  • http.url - HTTP URL
  • http.method - HTTP method (GET, POST, etc.)
  • http.status - HTTP status code
  • responsetime > 5 - Response time in seconds
  • fault = 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
02Release Notes

2026.10.21.1

Changed: Documentation only: the README no longer lists environment variables or a static shared-credentials file as a way to supply AWS credentials. It now recommends AWS SSO or a named profile (aws sso login --profile <name>, then --global-arg profile=<name>), or an IAM role attached to where swamp runs. Credential resolution is unchanged: the model still uses the AWS SDK default credential chain when profile is unset.

Upgrade note: No code, schema, or behavioral changes. The model version moves to 2026.10.21.1 with an identity upgrade.

03Behaviors1
@webframp/aws/tracesv2026.10.21.1aws/traces.ts
fn get_service_graph()
Get the X-Ray service dependency graph showing service relationships and health
fn get_traces()
Get trace summaries with optional filter expression
fn get_errors()
Get traces with errors or faults (convenience method for incident investigation)
fn analyze_errors()
Analyze error patterns across traces for incident investigation
fn list_services()
List services observed by X-Ray with request counts and error rates — a lightweight alternative to get_service_graph

Resources

service_graph(30m)— X-Ray service dependency graph
trace_summaries(1h)— List of trace summaries
error_analysis(1h)— Analysis of errors and faults in traces
service_list(30m)— Lightweight service listing with request counts and error rates
04Previous Versions18
2026.10.14.1Apache-2.0(was none)

2026.10.14.1

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

Upgrade note: Metadata only. No code, schema, or behavioral changes.

2026.09.24.1

Changed: Bump @aws-sdk/* 3.1133.0 → 3.1139.0 (2 packages)

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.24.1

2026.09.24.1

Changed: Bump @aws-sdk/* 3.1133.0 → 3.1139.0 (2 packages)

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.18.1

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

2026.09.17.1

2026.09.17.1

Changed: Bump @aws-sdk/* 3.1131.0 → 3.1133.0 (2 packages)

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.

2026.09.15.1

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.

2026.09.04.1

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

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

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

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

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

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

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

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 behaviors

2026.08.24.3

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

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

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

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

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.

05Stats
A
100 / 100
Downloads
76
Archive size
215.4 KB
  • 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
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/webframp/swamp-extensions
06Platforms
07Labels
#aws#distributed-tracing#incident-response#infrastructure#observability#ops#traces#xray