Skip to main content
← back to extensions

Aws/traces

@webframp/aws/tracesv2026.07.30.1· 1d agoMODELS
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.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.

03Models1
@webframp/aws/tracesv2026.07.30.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

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
04Previous Versions13
2026.07.29.1

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).

2026.07.24.1

2026.07.24.1

Changed: Bump AWS SDK from 3.1091.0 to 3.1094.0 (patch-level update).

2026.07.21.1

2026.07.21.1

Changed: Bumped AWS SDK dependencies to 3.1091.0 (from 3.1090.0).

Upgrade note: No behavioral changes. Routine dependency maintenance.

2026.07.18.2

2026.07.18.2

Added: An upgrades array entry (no-op) to traces.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.

2026.07.18.1

Changed: Bumped @aws-sdk/client-xray from 3.1069.0 to 3.1090.0 for dependency freshness. No behavior change.

2026.07.13.1

Fixed: Trace resources were written under instance names containing Date.now() (traces-<ts>, traces-filtered-<ts>, errors-<type>-<ts>, analysis-<ts>), so every method run created a brand-new resource instead of updating the existing one — unbounded data accumulation. Instance names are now deterministic and keyed on the query that produced them:

  • list → traces-all, or traces-filtered-<sha1> (hash of the filter expression)
  • errors → errors-<errorType>
  • analyze → error-analysis

Upgrade note: After upgrading, the first run of each method writes to the new stable instance name; the old timestamped instances remain until garbage collected. Re-runs now overwrite the latest snapshot as intended.

2026.07.18.1

2026.07.18.1

Changed: Bumped @aws-sdk/client-xray from 3.1069.0 to 3.1090.0 for dependency freshness. No behavior change.

2026.07.13.1

Fixed: Trace resources were written under instance names containing Date.now() (traces-<ts>, traces-filtered-<ts>, errors-<type>-<ts>, analysis-<ts>), so every method run created a brand-new resource instead of updating the existing one — unbounded data accumulation. Instance names are now deterministic and keyed on the query that produced them:

  • list → traces-all, or traces-filtered-<sha1> (hash of the filter expression)
  • errors → errors-<errorType>
  • analyze → error-analysis

Upgrade note: After upgrading, the first run of each method writes to the new stable instance name; the old timestamped instances remain until garbage collected. Re-runs now overwrite the latest snapshot as intended.

2026.07.13.1

2026.07.13.1

Fixed: Trace resources were written under instance names containing Date.now() (traces-<ts>, traces-filtered-<ts>, errors-<type>-<ts>, analysis-<ts>), so every method run created a brand-new resource instead of updating the existing one — unbounded data accumulation. Instance names are now deterministic and keyed on the query that produced them:

  • list → traces-all, or traces-filtered-<sha1> (hash of the filter expression)
  • errors → errors-<errorType>
  • analyze → error-analysis

Upgrade note: After upgrading, the first run of each method writes to the new stable instance name; the old timestamped instances remain until garbage collected. Re-runs now overwrite the latest snapshot as intended.

2026.06.21.1
2026.06.15.1
2026.05.20.1
2026.04.22.1

updated platforms

2026.04.13.1
2026.03.31.1
2026.03.30.1
05Stats
A
100 / 100
Downloads
27
Archive size
241.5 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
  • License declared1/1earned
  • Verified public repository2/2earned
Repository
https://github.com/webframp/swamp-extensions
06Platforms
07Labels
#aws#xray#traces#distributed-tracing#observability#ops#incident-response