Skip to main content
← back to extensions

Aws/logs

@webframp/aws/logsv2026.07.30.2· 1d agoMODELS
01README

Query and analyze CloudWatch Logs for operational visibility and incident investigation.

Authentication

Uses the default AWS credential chain. Set the optional profile global argument to resolve credentials from a named AWS shared-config profile (SSO token cache / fromIni), enabling multi-account use within a single swamp repo.

Requires CloudWatch Logs permissions.

Required IAM Permissions

  • logs:DescribeLogGroups
  • logs:StartQuery
  • logs:GetQueryResults
  • logs:FilterLogEvents

Usage

# Create logs model (default credential chain)
swamp model create @webframp/aws/logs aws-logs --global-arg region=us-east-1

# Create logs model with a named profile for multi-account use
swamp model create @webframp/aws/logs aws-logs-prod \
  --global-arg region=us-east-1 --global-arg profile=prod-account

# List log groups
swamp model method run aws-logs list_log_groups --input prefix=/aws/lambda

# Run a Logs Insights query
swamp model method run aws-logs query \
  --input 'logGroupNames=["/aws/lambda/my-function"]' \
  --input 'queryString=fields @timestamp, @message | filter @message like /error/i | limit 50' \
  --input startTime=1h

# Find error patterns
swamp model method run aws-logs find_errors \
  --input 'logGroupNames=["/aws/lambda/my-function"]' \
  --input startTime=2h

# Get recent events with filter
swamp model method run aws-logs get_recent_events \
  --input logGroupName=/aws/lambda/my-function \
  --input filterPattern=ERROR

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

Methods

  • list_log_groups - Discover log groups by prefix
  • query - Run CloudWatch Logs Insights queries
  • find_errors - Analyze error patterns with keyword detection
  • get_recent_events - Filter recent log events
02Release Notes

2026.07.30.2

Fixed: The query and find_errors methods now fail when a Logs Insights query does not reach Complete status. Previously, a timed-out query (status Running) or a terminal failure (Failed/Cancelled) was stored as a successful result with zero rows, misleading downstream consumers.

Added: requireComplete argument on the query method (default true). Set to false to store partial/incomplete results without error — useful for callers that inspect the status field themselves.

Changed: When a query times out with requireComplete: true, the method cancels the in-progress query via StopQuery before throwing, preventing orphaned scans from continuing to consume resources.

03Models1
@webframp/aws/logsv2026.07.30.2aws/logs.ts
fn list_log_groups()
List CloudWatch log groups with optional prefix filter
fn query()
Run a CloudWatch Logs Insights query
fn find_errors()
Find and analyze error patterns in log groups using common error keywords
fn get_recent_events(logGroupName: string)
Get recent log events from a log group using filter
ArgumentTypeDescription
logGroupNamestringLog group name

Resources

log_groups(1h)— List of CloudWatch log groups
query_results(1d)— Results from a Logs Insights query
error_analysis(1d)— Error pattern analysis results
04Previous Versions14
2026.07.30.1

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.

Changed: Internal client construction extracted into a shared makeClient helper. No behavioral difference for instances without a profile set.

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-cloudwatch-logs 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 logs.ts for proper typeVersion tracking on existing instances. No schema or behavior changes.

2026.07.18.1

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

2026.07.13.1

Fixed: The query method wrote its query_results resource under an instance name built from Date.now() (query-<ts>-<firstLogGroup>), so every run created a new resource instead of updating the existing one — unbounded data accumulation, against the repo's "deterministic resource instance names" rule. It now keys on a collision-resistant SHA-1 hash of the sorted log group names plus the query string: query-<sha1>.

Changed: The analyze_errors method's error_analysis instance name previously used only the first log group (errors-<firstLogGroup>), which collides when different multi-group analyses share a first group. It now hashes the full sorted log group set: errors-<sha1>.

Upgrade note: After upgrading, the first run of query / analyze_errors writes to the new stable instance names; old instances remain until garbage collected. Re-runs then overwrite the latest snapshot as intended.

2026.07.18.1

2026.07.18.1

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

2026.07.13.1

Fixed: The query method wrote its query_results resource under an instance name built from Date.now() (query-<ts>-<firstLogGroup>), so every run created a new resource instead of updating the existing one — unbounded data accumulation, against the repo's "deterministic resource instance names" rule. It now keys on a collision-resistant SHA-1 hash of the sorted log group names plus the query string: query-<sha1>.

Changed: The analyze_errors method's error_analysis instance name previously used only the first log group (errors-<firstLogGroup>), which collides when different multi-group analyses share a first group. It now hashes the full sorted log group set: errors-<sha1>.

Upgrade note: After upgrading, the first run of query / analyze_errors writes to the new stable instance names; old instances remain until garbage collected. Re-runs then overwrite the latest snapshot as intended.

2026.07.13.1

2026.07.13.1

Fixed: The query method wrote its query_results resource under an instance name built from Date.now() (query-<ts>-<firstLogGroup>), so every run created a new resource instead of updating the existing one — unbounded data accumulation, against the repo's "deterministic resource instance names" rule. It now keys on a collision-resistant SHA-1 hash of the sorted log group names plus the query string: query-<sha1>.

Changed: The analyze_errors method's error_analysis instance name previously used only the first log group (errors-<firstLogGroup>), which collides when different multi-group analyses share a first group. It now hashes the full sorted log group set: errors-<sha1>.

Upgrade note: After upgrading, the first run of query / analyze_errors writes to the new stable instance names; old instances remain until garbage collected. Re-runs then 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
50
Archive size
254.2 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#cloudwatch#logs#observability#ops#incident-response