Stacktape gives you two built-in surfaces for viewing application logs: the Stacktape Console and the stacktape logs CLI command. Both read from AWS CloudWatch Logs — the log data AWS captures from your compute resources such as Lambda functions, container workloads (web services, private services, worker services, multi-container workloads), and batch jobs.
How logging works
AWS services underlying Stacktape compute resources — Lambda functions, container workloads, and batch jobs — automatically capture everything your application writes to stdout and stderr in CloudWatch Logs. Each compute resource maps to a CloudWatch Logs log group. The CLI resolves the log group for a given --resource-name and optional --container flag; the Console log viewer receives a CloudWatch log group name and fetches events for that log group. Non-compute resources (databases, queues, buckets, etc.) may produce logs through separate AWS-native mechanisms outside this workflow.
Both surfaces fetch from CloudWatch Logs. The CLI takes --resource-name (and --container for multi-container workloads) and resolves the matching log group; the Console log viewer receives the log group name for the selected resource and queries events from it. Application logs are whatever your code writes to stdout and stderr — the underlying AWS service streams that into CloudWatch Logs.
For cost implications of CloudWatch Logs ingestion and storage, see Managing Costs.
Lower-cost ingestion for infrequently inspected logs
New log groups can opt into CloudWatch Logs Infrequent Access from the resource's existing logging block:
This lowers CloudWatch ingestion cost; storage and Logs Insights query pricing are unchanged. Standard remains the default because Infrequent Access does not support live tail, filter and subscription filters, embedded metrics, or Stacktape Issues and log forwarding. AWS fixes the class when a log group is created, so Stacktape blocks attempts to change an existing group and explains that the setting is for a new resource or stage.
The simple viewing workflow remains available. stacktape logs and the Console detect Infrequent Access and use a bounded Logs Insights snapshot automatically. The CLI's --filter flag uses an incompatible CloudWatch filter language, so use --query for filtered IA reads; the Console's IA viewer offers a literal Message contains filter.
Viewing logs in the Console
The Stacktape Console provides a paginated log viewer for resources that have a resolved CloudWatch log group. The viewer displays returned events with timestamps, and each log line is expandable to show its full content via the ExpandableLogLine component.
Time range filtering
The Console log viewer offers two modes for selecting the time window, accessible via tabs above the log output:
- Relative time filter — choose from 14 preset windows relative to the current time: 1 minute, 5 minutes, 15 minutes, 30 minutes (default), 1 hour, 2 hours, 4 hours, 6 hours, 12 hours, 1 day, 3 days, 7 days, 14 days, or 30 days. This is the fastest way to get recent logs and covers most debugging sessions.
- Time range filter — pick an exact start and end date/time using the date-time range picker. Use this when investigating a known incident window where you need precise time boundaries.
Filter patterns
For Standard log groups, enter a CloudWatch filter pattern in the Filter pattern input to narrow results to matching log events. The filter uses CloudWatch filter pattern syntax. For Infrequent Access groups, the field is labeled Message contains and Stacktape uses a Logs Insights snapshot. The input is debounced — results refresh automatically after you stop typing, so there is no need to press a submit button.
Filter patterns are useful for isolating error messages, matching JSON field values, or excluding noisy log lines. For example, entering ERROR shows only lines containing that keyword, while { $.level = "error" } matches structured JSON logs with a specific field value.
Pagination and display
The log viewer fetches up to 200 events per page and renders them in a virtualized, scrollable list. Each log line is expandable — click a line to see its full content. If more events are available beyond the current page, click Show more at the bottom to load the next batch.
The virtualized list keeps the viewer responsive even with hundreds of log entries loaded.
Viewing logs with the CLI
The stacktape logs command fetches logs from your terminal. It supports two modes: standard log fetching and CloudWatch Logs Insights queries via the --query flag.
Basic usage
Fetch the most recent logs for a resource:
This returns up to 100 log events from the last hour. Without --raw or agent mode, log events are passed to a formatted printer that adds timestamps and level-based coloring. Pass --raw for structured JSON output instead.
Time ranges
Control the time window with --since and --until.
Last 30 minutes:
Last 3 hours:
Last 2 days:
Specific time window (used with Logs Insights queries):
The --since flag accepts two formats:
| Format | Example | Meaning |
|---|---|---|
| Relative shorthand | 1h, 30m, 2d, 10s | Hours, minutes, days, or seconds before --until |
| Absolute date | 2025-05-14T08:00:00Z | Any value accepted by the JavaScript Date constructor |
If --since is omitted, it defaults to 1 hour before --until. If --until is omitted, it defaults to the current time.
How --until works: The --until flag serves as the anchor point when computing relative --since values — for example, --since 1h means 1 hour before --until. For Logs Insights queries (when using --query), both --since and --until define the query's time window. For standard log fetching (without --query), --until is used only to compute relative --since values; the CloudWatch fetch call receives startTime but not an end-time bound.
Limiting results
Use --limit to control how many log events are returned. For example, to fetch the last 500 events:
The default limit is 100 events. The CLI applies the limit by slicing the fetched events to the first N entries (events.slice(0, limit)). If you are looking at a high-traffic resource, increase the limit to capture more context around an incident.
Filter patterns
Use --filter to apply a CloudWatch filter pattern, returning only events that match.
Filter to only errors:
Filter JSON structured logs by field value:
Filter patterns follow CloudWatch filter pattern syntax. Common patterns:
"ERROR"— match any event containing the word ERROR"ERROR" - "DeprecationWarning"— match ERROR but exclude DeprecationWarning{ $.level = "error" }— match JSON logs where thelevelfield equals"error"{ $.statusCode >= 500 }— match JSON logs with status code 500 or above
Filter patterns are applied server-side by CloudWatch before events are returned, so they reduce both network transfer and the number of events you need to scan. For more complex analysis, use Logs Insights queries instead.
CloudWatch Logs Insights queries
For complex analysis — aggregations, top-N queries, statistical breakdowns — use --query to run a CloudWatch Logs Insights query.
Find the 20 most recent errors with timestamps:
Count errors per hour over the last 24 hours:
Find slowest Lambda invocations:
When --query is provided, the command uses the CloudWatch Logs Insights engine instead of the standard log-fetching path. Both --since and --until define the query's time window. In non-agent mode, the CLI prints the result count and each row's timestamp and message. In agent mode, results are returned as structured JSON.
CloudWatch Logs Insights is well suited for ad-hoc investigation and aggregate queries across large volumes of logs. Use it when simple filter patterns are not expressive enough — for example, when you need to count occurrences, compute averages, or group by a field.
Container-specific logs
For multi-container workloads, use --container to specify which container's logs to fetch:
The --container flag is used when resolving the log group for the resource. For single-container resources (web services, private services, worker services), the log group is resolved automatically and --container is not needed.
Raw JSON output
Use --raw to get structured JSON output instead of formatted text:
This outputs a JSON object containing the log group name and an array of events, each with timestamp, message, and logStream fields. Raw output is useful for piping into jq, storing for later analysis, or consuming in scripts.
The logGroup value is the resolved CloudWatch Logs log group name for your Stacktape resource.
When the CLI runs in agent mode (used by AI coding assistants via the MCP server), it automatically outputs structured JSON regardless of the --raw flag.
CLI vs Console comparison
Both surfaces access the same underlying CloudWatch Logs data. Choose based on your workflow:
| Feature | CLI (logs) | Console |
|---|---|---|
| Historical log search | ✓ | ✓ |
| Filter patterns | ✓ | ✓ |
| CloudWatch Logs Insights queries | ✓ | Filter patterns only |
| Structured JSON output | ✓ | ✕ |
| Time range controls | Relative shorthand + absolute | 14 presets + date-time range picker |
| Formatted output | Timestamps + level-based coloring | Expandable log lines with timestamps |
| Scriptable / CI-friendly | ✓ | ✕ |
Use the Console for quick visual inspection of stored log events with its 14 preset time windows, date-range picker, and expandable log lines. Use the CLI for Logs Insights queries, JSON export, scripted analysis, and terminal-based workflows. The logs command targets a single --resource-name per invocation; the Console log viewer operates on one log group at a time.
Structured logging
While Stacktape captures any stdout/stderr output, writing logs as structured JSON makes them far more useful for filtering and querying. Both the CLI's --filter flag and Logs Insights queries can match on individual JSON fields, which is not possible with plain-text logs.
A minimal structured log entry looks like:
With this format, you can run targeted queries.
Filter to errors for a specific user:
Aggregate error counts by status code over the last 6 hours:
Most logging libraries (Winston, Pino, Python's structlog, Go's slog) support JSON output with minimal setup. If you are starting a new project, default to structured JSON logs — the investment pays off immediately once you need to debug a production issue.
Log forwarding
For external log shipping, see log forwarding. That page covers the supported destinations and configuration.
Logs FAQ
How much does CloudWatch Logs cost?
AWS CloudWatch Logs charges for ingestion, storage, and Logs Insights queries. Pricing is billed directly to your AWS account and varies by region — check the AWS CloudWatch pricing page for current rates. For Stacktape cost management, see Managing Costs.
Can I search logs across multiple resources at once?
The CLI's logs command targets a single --resource-name per invocation, and the Console log viewer operates on one log group at a time. To search across multiple resources, run separate stacktape logs commands for each. For cross-resource log analysis, consider forwarding logs to a centralized platform using log forwarding.
What is the difference between filter patterns and Logs Insights queries?
Filter patterns are simple text or JSON-field matchers applied at fetch time — they return matching log lines. CloudWatch Logs Insights is a full query language that supports aggregation (stats count(*)), grouping (by bin(1h)), sorting, and field extraction. Use filter patterns for quick keyword searches; use Insights for analytical queries like "how many errors per hour" or "what are the slowest requests." The CLI supports both filter patterns (--filter) and Logs Insights queries (--query). The Console log viewer supports CloudWatch filter patterns.
When should I use CloudWatch Logs vs an external logging service?
CloudWatch Logs requires no additional setup for Stacktape resources and integrates with both the CLI and the Console, so it handles most debugging and monitoring needs. Reach for an external service when you need cross-service correlation, advanced alerting on log patterns, or a unified dashboard spanning AWS and non-AWS systems. Use log forwarding to ship logs to those destinations.
How do I set up alerts based on log patterns?
Stacktape alarms trigger notifications based on CloudWatch metrics but do not include a built-in log-pattern alerting workflow. For log-based alerting, you can use AWS CloudWatch metric filters — an AWS-native mechanism outside the Stacktape logs workflow — to derive custom metrics from log data, then create alarms against those metrics. For alert delivery, see alert channels and notifications.