Serverless Logs Insights

Plugin for the Serverless Framework that simplifies advanced queries in AWS CloudWatch Logs Insights directly through the CLI, allowing you to filter, analyze, and visualize Lambda function logs in a practical and efficient way.

Installation

Add the plugin to your Serverless project:

npm install --save-dev serverless-logs-insights

Configuration

In your serverless.yml file, add the plugin and configure custom queries under custom.logsInsights.queries:

plugins:
  - serverless-logs-insights

custom:
  logsInsights:
    queries:
      errors: "fields @timestamp, @message | filter @message like /error/ | sort @timestamp desc | limit 20"
      warnings: "fields @timestamp, @message | filter @message like /warn/ | sort @timestamp desc | limit 20"

Queries can be customized according to your needs, using the CloudWatch Logs Insights syntax.

Usage

Run queries directly through the Serverless Framework CLI:

sls logs-insights -f <function> -q <query> [-i <interval>] [-o <output>] [--relative-time]

Available Options

Option	Description
-f, --function	Name of the Lambda function (as defined in serverless.yml)
-q, --query	Name of the query defined in custom.logsInsights.queries or a free query
-i, --interval	Time interval (default: 1h). Supports s, m, h, d
-o, --output	Output format: auto (default), table, json, raw
--relative-time	Show timestamps as relative (e.g. 2m ago)

Examples

Query the latest errors of a Lambda function named hello:

sls logs-insights -f hello -q errors

Run a custom query directly via CLI:

sls logs-insights -f hello -q "fields @message | filter @message like /timeout/" -i 3h

Force table output:

sls logs-insights -f hello -q errors -o table

JSON output for piping to other tools:

sls logs-insights -f hello -q errors -o json

Output Features

• Log level colors — ERROR in red, WARN in yellow, INFO in cyan, DEBUG in gray
• Progress indicator — shows elapsed time while the query is running
• Query statistics — displays bytes scanned, records matched, and query duration
• Auto layout — log view for @timestamp + @message queries, table view for multi-field queries
• JSON detection — automatically pretty-prints JSON payloads inside log messages

How does it work?

The plugin uses the AWS SDK to execute queries in CloudWatch Logs Insights, retrieving events from the log groups associated with the Lambda functions in your Serverless project. Results are displayed directly in the terminal with color-coded log levels, structured table views, and query statistics.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Developed by Kauê Leal - github.com/kauelima21