Beacon sends events from EC2 user data scripts to AWS CloudWatch Events, enabling real-time monitoring of startup processes.
During EC2 instance startup, cloud-init executes user data scripts to configure the machine and deploy applications. If these scripts fail, instances may terminate without alerting administrators, especially in autoscaling groups.
Beacon solves this by emitting custom events to CloudWatch at critical points in your user data execution, allowing:
- Real-time monitoring of user data script execution
- Alerting on failures
- Tracking of deployment steps
- Auditing of instance initialization
- Download the appropriate binary for your architecture from the Releases page
- Copy to your instance:
sudo cp beacon /usr/local/bin/ - Make executable:
sudo chmod +x /usr/local/bin/beacon
EC2 instances using Beacon require the events:PutEvents permission:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "*"
}
]
}Add this to your instance profile or role.
Beacon can send three types of events: success (pass), failure (fail), or informational (info).
# Send success event
beacon --pass "User data processed successfully"
# Send failure event
beacon --fail "Failed to download application artifact"
# Send informational event
beacon --info "Starting application deployment"
# Custom status
beacon --status "warning" "Disk space below threshold"BEACON_PROJECT: Set project name (default: "unknown")
Usage:
beacon [message] [flags]
Flags:
-c, --config string Specifies a path to load a config file
-f, --fail Emits a failure event
--generate-config Displays a template for the config file
-h, --help Help for beacon
--info Emits an informational event
-p, --pass Emits a successful event
--permissions Displays IAM permissions required by the application
--project string Names the PROJECT as a source for the event (default "unknown")
--status string Emits an event with a custom STATUS
-v, --version Version for beacon
- Open the CloudWatch console
- Navigate to Events → Rules
- Create a new rule
- For the event pattern:
{
"detailType": [
"User Data"
]
}- Additional filtering options:
- By project:
"source": ["your-project-name"] - By status:
"detail": {"Status": ["fail"]}
- By project:
Connect your rule to targets like:
- SNS topics for email/SMS notifications
- Lambda functions for custom processing
- SQS queues for event processing
- CloudWatch Alarm actions
#!/bin/bash
# Start user data execution
beacon --info "Starting user data execution"
# Install dependencies
apt-get update
if [ $? -eq 0 ]; then
beacon --info "System packages updated"
else
beacon --fail "Failed to update system packages"
exit 1
fi
# Deploy application
./deploy_app.sh
if [ $? -eq 0 ]; then
beacon --pass "Application deployed successfully"
else
beacon --fail "Application deployment failed"
exit 1
fi#!/bin/bash
export BEACON_PROJECT="webapp-fleet"
beacon --info "Starting webapp deployment"
# Deployment steps...
beacon --pass "Webapp successfully deployed"Prerequisites:
- Go 1.24+
- Task (v3.x)
# Clone the repository
git clone https://github.com/scottbrown/beacon.git
cd beacon
# Build
task build
# Run tests
task test
# Build for all platforms
task dist
# Create release artifacts (requires VERSION env var)
task release VERSION=1.1.0You can list all available tasks with:
taskCloudWatch Events has associated costs:
- $1.00 per million custom events
- Additional costs for targets (SNS, Lambda, etc.)
While costs are minimal for most use cases, be mindful when implementing at scale.
MIT License - See LICENSE for details.
Copyright © Scott Brown