LogPulse ⚡️

Real-time AWS CloudWatch Log Analysis & Slack Alerts

LogPulse is a lightweight, serverless utility that monitors your AWS CloudWatch Logs in real-time. It automatically detects critical error patterns and streams formatted alerts directly to your Slack workspace. Perfect for keeping an eye on Docker containers, Lambda functions, or EC2 applications without complex observability stacks.

Architecture

graph LR
    App[Application/Docker] -->|Logs| CW[CloudWatch Log Group]
    CW -->|Subscription Filter| Lambda[AWS Lambda Function]
    Lambda -->|Process & Format| Slack[Slack Channel]

Loading

Prerequisites

• Node.js 20.x installed.
• AWS CLI configured with appropriate permissions.
• AWS SAM CLI installed.

Installing AWS SAM CLI

MacOS (using Homebrew):

brew tap aws/tap
brew install aws-sam-cli

Windows / Linux / Other: Please refer to the official AWS SAM Installation Guide.

• A Slack Incoming Webhook URL. Create one here.
• Application Logs: Your app must send logs to CloudWatch. See DOCKER_CLOUDWATCH_SETUP.md for Docker configuration.

Project Structure

.
├── src/
│   └── handlers/
│       └── logAnalyzer.js  # Main Lambda logic
├── test/
│   └── local-test.js       # Local testing script
├── template.yaml           # SAM Infrastructure definition
└── README.md

Configuration

The application uses the following parameters (defined in template.yaml):

Parameter	Description	Default
SlackWebhookUrl	Required. The Slack Webhook URL.	None
LogGroupName	Required. The existing Log Group to monitor.	None
FilterPattern	The pattern to match in logs.	CRITICAL-ERROR

Deployment

1. Build the project

   sam build

2. Deploy to AWS Run the guided deployment to set your parameters:

   sam deploy --guided

   Follow the prompts:

   • Stack Name: e.g., log-analyzer-stack
   • AWS Region: e.g., us-east-1
   • SlackWebhookUrl: Paste your Slack Webhook URL.
   • LogGroupName: Enter the name of the log group you want to watch (e.g., /aws/lambda/my-app).
   • FilterPattern: Press Enter to keep CRITICAL-ERROR or type your own.

Monitoring Multiple Log Groups

To monitor more than one Log Group with the same Lambda function, you need to add additional SubscriptionFilter resources to your template.yaml.

Currently, the template has one:

LogSubscriptionFilter:
  Type: AWS::Logs::SubscriptionFilter
  Properties:
    LogGroupName: !Ref LogGroupName
    ...

To add a second group:

1. Copy the LogSubscriptionFilter block.
2. Rename it (e.g., LogSubscriptionFilterTwo).
3. Hardcode the LogGroupName or add a new Parameter for it.

Example:

  LogSubscriptionFilterTwo:
    Type: AWS::Logs::SubscriptionFilter
    Properties:
      LogGroupName: "/aws/lambda/another-app"
      FilterPattern: !Ref FilterPattern
      DestinationArn: !GetAtt LogAnalyzerFunction.Arn
    DependsOn: LambdaInvokePermission

Note: You also need to ensure the Lambda permission (LambdaInvokePermission) covers this new group, or simply allow the Lambda to be invoked by logs.amazonaws.com generally.

Sample Notification

When an error is detected, you will see a formatted message in Slack like this:

🚨 Critical Error Detected

Log Group: /aws/lambda/my-app-production Log Stream: 2024/01/08/[$LATEST]a1b2c3d4e5f6...

Errors Found: 1 • 2024-01-08T10:00:00.000Z: CRITICAL-ERROR: Database connection failed at /src/db.js:42

Redeployment / Updates

If you make changes to the code (src/handlers/logAnalyzer.js) or the template (template.yaml):

1. Rebuild:

   sam build

2. Redeploy:

   sam deploy

   Note: You don't need --guided this time; SAM will use the configuration saved in samconfig.toml.

Testing

Local Testing

You can test the function logic locally without deploying to AWS.

1. Export your Slack Webhook URL (optional, if you want to actually send a message):

   export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

2. Run the test script:

   node test/local-test.js

   Note: If you don't set the env var, the script will print a "Missing SLACK_WEBHOOK_URL" error, which confirms the handler is running.

Integration Testing (AWS)

1. Ensure the stack is deployed.

2. Generate a log entry in the monitored Log Group that matches your pattern:

   aws logs put-log-events \
     --log-group-name "/aws/lambda/my-app" \
     --log-stream-name "test-stream" \
     --log-events timestamp=$(date +%s000),message="CRITICAL-ERROR: This is a test alert from CLI"

   (Note: You must have a log stream created first. If not, use aws logs create-log-stream ...)

3. Check your Slack channel for the notification.

Cleanup

To delete the stack:

sam delete

Community

• Contributing: see CONTRIBUTING.md.
• License: MIT. See LICENSE.