Aws/logs
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:DescribeLogGroupslogs:StartQuerylogs:GetQueryResultslogs: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=ERRORTime 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
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.
| Argument | Type | Description |
|---|---|---|
| logGroupName | string | Log group name |
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.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 query timeout behavior,
parseRelativeTime silent fallback, region-scope guidance, keyword
configuration for find_errors, unbounded pagination risk, and
requireComplete=false partial-result semantics.
2026.08.21.2
Changed: CloudWatch Logs API failures now say which operation was
attempted and with what log group(s)/query, instead of surfacing the raw SDK
error. DescribeLogGroups, StartQuery (in both query and find_errors),
GetQueryResults (during polling), and FilterLogEvents failures all raise
a clear error naming the log group(s) or prefix involved, with the original
SDK error preserved as the cause. A StartQuery call that returns no
queryId also now names the log groups involved instead of a bare "failed
to start query" message.
The query method's logGroupNames and queryString arguments now reject
empty input at the schema level — previously an empty log group list or
query string would only fail deep inside the CloudWatch Logs API with a
generic error.
No schema changes.
2026.08.21.1
Changed: Tightened find_errors's logGroupNames and get_recent_events's
logGroupName to require non-empty values — these are required identifiers the
CloudWatch Logs API already rejects when empty.
2026.08.21.1
Changed: Tightened find_errors's logGroupNames and get_recent_events's
logGroupName to require non-empty values — these are required identifiers the
CloudWatch Logs API already rejects when empty.
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.2. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.2.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
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.
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.2. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.2.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
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.
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.2. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.2.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
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.
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.2. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.2.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
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.
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.2. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.2.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
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.
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.2. This release closes the chain with a no-op upgrade entry and republishes everything that had accumulated since 2026.07.30.2.
2026.07.31.1
Changed: Bump @aws-sdk/* 3.1096.0 → 3.1100.0 (2 packages)
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.
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.
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.
- 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