{"id":42552638,"url":"https://github.com/scottbrown/beacon","last_synced_at":"2026-01-28T19:21:53.707Z","repository":{"id":66784533,"uuid":"97291371","full_name":"scottbrown/beacon","owner":"scottbrown","description":"Emits user data events to AWS EventBridge","archived":false,"fork":false,"pushed_at":"2026-01-12T08:11:41.000Z","size":2202,"stargazers_count":6,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-12T17:58:39.819Z","etag":null,"topics":["aws","ec2","eventbus","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottbrown.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-07-15T04:10:18.000Z","updated_at":"2026-01-12T08:11:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"369b610d-f1dc-496e-949f-d334d2f1bca7","html_url":"https://github.com/scottbrown/beacon","commit_stats":null,"previous_names":["scottbrown/beacon"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/scottbrown/beacon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbrown%2Fbeacon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbrown%2Fbeacon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbrown%2Fbeacon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbrown%2Fbeacon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottbrown","download_url":"https://codeload.github.com/scottbrown/beacon/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbrown%2Fbeacon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28849821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","ec2","eventbus","golang"],"created_at":"2026-01-28T19:21:52.543Z","updated_at":"2026-01-28T19:21:53.700Z","avatar_url":"https://github.com/scottbrown.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Beacon](beacon.small.png)\n\n# Beacon - EC2 User Data Event Emitter\n\nBeacon sends events from EC2 user data scripts to AWS CloudWatch Events, enabling real-time monitoring of startup processes.\n\n## Overview\n\nDuring 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.\n\nBeacon solves this by emitting custom events to CloudWatch at critical points in your user data execution, allowing:\n- Real-time monitoring of user data script execution\n- Alerting on failures\n- Tracking of deployment steps\n- Auditing of instance initialization\n\n## Installation\n\n### Binary Installation\n\n1. Download the appropriate binary for your architecture from the [Releases page](https://github.com/scottbrown/beacon/releases)\n2. Copy to your instance: `sudo cp beacon /usr/local/bin/`\n3. Make executable: `sudo chmod +x /usr/local/bin/beacon`\n\n### Required IAM Permission\n\nEC2 instances using Beacon require the `events:PutEvents` permission:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": \"events:PutEvents\",\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\nAdd this to your instance profile or role.\n\n## Usage\n\nBeacon can send three types of events: success (pass), failure (fail), or informational (info).\n\n### Basic Usage\n\n```bash\n# Send success event\nbeacon --pass \"User data processed successfully\"\n\n# Send failure event\nbeacon --fail \"Failed to download application artifact\"\n\n# Send informational event\nbeacon --info \"Starting application deployment\"\n\n# Custom status\nbeacon --status \"warning\" \"Disk space below threshold\"\n```\n\n### Environment Variables\n\n- `BEACON_PROJECT`: Set project name (default: \"unknown\")\n\n### Command Line Options\n\n```\nUsage:\n  beacon [message] [flags]\n\nFlags:\n  -c, --config string     Specifies a path to load a config file\n  -f, --fail              Emits a failure event\n      --generate-config   Displays a template for the config file\n  -h, --help              Help for beacon\n      --info              Emits an informational event\n  -p, --pass              Emits a successful event\n      --permissions       Displays IAM permissions required by the application\n      --project string    Names the PROJECT as a source for the event (default \"unknown\")\n      --status string     Emits an event with a custom STATUS\n  -v, --version           Version for beacon\n```\n\n## CloudWatch Events Setup\n\n### Creating the Rule\n\n1. Open the CloudWatch console\n2. Navigate to Events → Rules\n3. Create a new rule\n4. For the event pattern:\n\n```json\n{\n  \"detailType\": [\n    \"User Data\"\n  ]\n}\n```\n\n5. Additional filtering options:\n   - By project: `\"source\": [\"your-project-name\"]`\n   - By status: `\"detail\": {\"Status\": [\"fail\"]}`\n\n### Target Configuration\n\nConnect your rule to targets like:\n- SNS topics for email/SMS notifications\n- Lambda functions for custom processing\n- SQS queues for event processing\n- CloudWatch Alarm actions\n\n## Integration Examples\n\n### Basic User Data Success Tracking\n\n```bash\n#!/bin/bash\n\n# Start user data execution\nbeacon --info \"Starting user data execution\"\n\n# Install dependencies\napt-get update\nif [ $? -eq 0 ]; then\n  beacon --info \"System packages updated\"\nelse\n  beacon --fail \"Failed to update system packages\"\n  exit 1\nfi\n\n# Deploy application\n./deploy_app.sh\nif [ $? -eq 0 ]; then\n  beacon --pass \"Application deployed successfully\"\nelse\n  beacon --fail \"Application deployment failed\"\n  exit 1\nfi\n```\n\n### Project-Based Tracking\n\n```bash\n#!/bin/bash\nexport BEACON_PROJECT=\"webapp-fleet\"\n\nbeacon --info \"Starting webapp deployment\"\n# Deployment steps...\nbeacon --pass \"Webapp successfully deployed\"\n```\n\n## Building From Source\n\nPrerequisites:\n- Go 1.24+\n- [Task](https://taskfile.dev) (v3.x)\n\n```bash\n# Clone the repository\ngit clone https://github.com/scottbrown/beacon.git\ncd beacon\n\n# Build\ntask build\n\n# Run tests\ntask test\n\n# Build for all platforms\ntask dist\n\n# Create release artifacts (requires VERSION env var)\ntask release VERSION=1.1.0\n```\n\nYou can list all available tasks with:\n\n```bash\ntask\n```\n\n## Cost Considerations\n\nCloudWatch Events has associated costs:\n- $1.00 per million custom events\n- Additional costs for targets (SNS, Lambda, etc.)\n\nWhile costs are minimal for most use cases, be mindful when implementing at scale.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\nCopyright © Scott Brown\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottbrown%2Fbeacon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottbrown%2Fbeacon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottbrown%2Fbeacon/lists"}