https://github.com/scottbrown/beacon
Emits user data events to AWS EventBridge
https://github.com/scottbrown/beacon
aws ec2 eventbus golang
Last synced: 5 months ago
JSON representation
Emits user data events to AWS EventBridge
- Host: GitHub
- URL: https://github.com/scottbrown/beacon
- Owner: scottbrown
- License: mit
- Created: 2017-07-15T04:10:18.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2026-01-12T08:11:41.000Z (6 months ago)
- Last Synced: 2026-01-12T17:58:39.819Z (6 months ago)
- Topics: aws, ec2, eventbus, golang
- Language: Go
- Homepage:
- Size: 2.1 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Beacon - EC2 User Data Event Emitter
Beacon sends events from EC2 user data scripts to AWS CloudWatch Events, enabling real-time monitoring of startup processes.
## Overview
During EC2 instance startup, [cloud-init](https://cloud-init.io/) 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
## Installation
### Binary Installation
1. Download the appropriate binary for your architecture from the [Releases page](https://github.com/scottbrown/beacon/releases)
2. Copy to your instance: `sudo cp beacon /usr/local/bin/`
3. Make executable: `sudo chmod +x /usr/local/bin/beacon`
### Required IAM Permission
EC2 instances using Beacon require the `events:PutEvents` permission:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "events:PutEvents",
"Resource": "*"
}
]
}
```
Add this to your instance profile or role.
## Usage
Beacon can send three types of events: success (pass), failure (fail), or informational (info).
### Basic Usage
```bash
# 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"
```
### Environment Variables
- `BEACON_PROJECT`: Set project name (default: "unknown")
### Command Line Options
```
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
```
## CloudWatch Events Setup
### Creating the Rule
1. Open the CloudWatch console
2. Navigate to Events → Rules
3. Create a new rule
4. For the event pattern:
```json
{
"detailType": [
"User Data"
]
}
```
5. Additional filtering options:
- By project: `"source": ["your-project-name"]`
- By status: `"detail": {"Status": ["fail"]}`
### Target Configuration
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
## Integration Examples
### Basic User Data Success Tracking
```bash
#!/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
```
### Project-Based Tracking
```bash
#!/bin/bash
export BEACON_PROJECT="webapp-fleet"
beacon --info "Starting webapp deployment"
# Deployment steps...
beacon --pass "Webapp successfully deployed"
```
## Building From Source
Prerequisites:
- Go 1.24+
- [Task](https://taskfile.dev) (v3.x)
```bash
# 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.0
```
You can list all available tasks with:
```bash
task
```
## Cost Considerations
CloudWatch 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.
## License
MIT License - See [LICENSE](LICENSE) for details.
Copyright © Scott Brown