eventbridge-cli

Amazon EventBridge is a serverless event bus that makes it easy to connect applications together using data from your own applications, integrated Software-as-a-Service (SaaS) applications, and AWS services.

Eventbridge-cli is a tool to listen to an EventBus events. Useful for debugging, event pattern testing, CI pipelines integration.

EventBus --> EventBrige Rule --> SQS <-- poller

Features:

• Listen to Event Bus messages
• Filter messages by event pattern
• Read event pattern from cli, file or SAM template
• Authentication via profile or env variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
• Pretty JSON output
• CI mode
• Dry event test
• ...

Install from releases binary:

wget https://github.com/spezam/eventbridge-cli/releases/download/<version>/eventbridge-cli_<version>_darwin_amd64.tar.gz
tar xvfz eventbridge-cli_<version>_darwin_amd64.tar.gz
mv eventbridge-cli /somewhere/in/PATH

with go install

GO111MODULE=on go install github.com/spezam/eventbridge-cli

or build from source:

git clone https://github.com/spezam/eventbridge-cli.git
cd eventbridge-cli
go build

Standard mode

Flags:

NAME:
   eventbridge-cli - AWS EventBridge cli

USAGE:
   eventbridge [global options] command [command options] [arguments...]

VERSION:
   1.0.0

AUTHOR:
   matteo ridolfi

COMMANDS:
   ci       AWS EventBridge cli - CI mode
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --profile value, -p value       AWS profile (default: "default") [$AWS_PROFILE]
   --region value, -r value        AWS region [$AWS_DEFAULT_REGION]
   --eventbusname value, -b value  EventBridge Bus Name (default: "default")
   --eventpattern value, -e value  EventBridge event pattern. Can be prefixed by 'file://' or 'sam://' (default: "{\"source\": [{\"anything-but\": [\"eventbridge-cli\"]}]}")
   --prettyjson, -j                Pretty JSON output (default: false)
   --help, -h                      show help (default: false)
   --version, -v                   print the version (default: false)

Usage

Authenticate via environment variable:

AWS_PROFILE=myawsprofile eventbridge-cli
AWS_DEFAULT_REGION=eu-north-1 AWS_ACCESS_KEY_ID=zzZZ AWS_SECRET_ACCESS_KEY=abbC eventbridge-cli

Authenticate via cli flags:

eventbridge-cli -p myawsprofile
eventbridge-cli -p myawsprofile -r eu-north-1

Event pattern can be specified directly in the cli -e '{}', using a JSON file -e file://... or from a SAM template -e sam://<template_file>/<serverless_function_name>:

eventbridge-cli -p myawsprofile -j \
	-b fishnchips-eventbus \
	-e '{"source":["gamma"],"detail":{"channel":["web"]}}'

eventbridge-cli -p myawsprofile -j \
	-b fishnchips-eventbus \
	-e file://testdata/eventpattern.json

eventbridge-cli -p myawsprofile -j \
	-b fishnchips-eventbus \
	-e sam://testdata/template.yaml/BetaFunction

CI mode

CI mode can be used to perform integration testing in an automated way.

Given an event pattern (global flag -e) and an input event (ci flag -i), verifies the message goes through the event bus within timeout (ci flag -t).

Note: global flags are position sensitive and can't be used under 'ci' command. For example:

eventbridge-cli -j ci -t 20

Flags:

NAME:
   eventbridge-cli ci - AWS EventBridge cli - CI mode

USAGE:
   eventbridge-cli ci [command options] [arguments...]

DESCRIPTION:
   run eventbridge-cli in CI mode

OPTIONS:
   --timeout value, -t value  CI timeout in seconds (default: 12)
   --inputevent value, -i value  Input event. Can be omitted if coming from other sources or prefixed by 'file://'
   --help, -h                 show help (default: false)

Usage

Event pattern and input event from cli:

eventbridge-cli -p myawsprofile -j \
   -e '{"source": ["beta"]}' \
   ci -i '{"source":"beta", "detail":"{\"channel\":\"web\"}", "detail-type": "poc"}'

Use the -t flag to specify timeout:

eventbridge-cli -p myawsprofile -j \
   -e '{"source": ["beta"]}' \
   ci -i '{"source":"beta", "detail":"{\"channel\":\"web\"}", "detail-type": "poc"}' \
   -t 20

Event pattern and input event from file:

eventbridge-cli -p myawsprofile -j \
   -e file://testdata/eventpattern.json \
   ci -i file://testdata/event_ci_success.json

# failing CI
eventbridge-cli -p myawsprofile -j \
   -e file://testdata/eventpattern.json \
   ci -i file://testdata/event_ci_fail.json

Event pattern from SAM template, BetaFunction lambda function:

eventbridge-cli -p myawsprofile -j \
   -e sam://testdata/template.yaml/BetaFunction \
   ci -i file://testdata/event_ci_success.json

Listen to events from any other source (lambda, aws cli, sam local, ...)

eventbridge-cli -p myawsprofile -j \
   -e file://testdata/eventpattern.json \
   ci

Test Event Rule

Test event payloads against deployed event rules on a specific eventbus.

Given an optional bus (global flag -b) an event rule (test-event flag -e) and an input event (test-event flag -i), verifies the payload will match the rule. Rule is treated as prefix, so can be a subset of the rule name (ie. -e fish will test all rules starting with fish)

Note: global flags are position sensitive and can't be used under 'test-event' command. For example:

eventbridge-cli -b somebus test-event

Flags:

NAME:
   eventbridge-cli test-event - AWS EventBridge test-event

USAGE:
   eventbridge-cli test-event [command options] [arguments...]

DESCRIPTION:
   run eventbridge-cli to test an event against a deployed event pattern

OPTIONS:
   --eventrule value, -e value   EventBridge rule name. Can be a prefix
   --inputevent value, -i value  Input event. Can be prefixed by 'file://' or omitted if coming from other sources
   --help, -h                    show help (default: false)

Usage

eventbridge-cli -p myawsprofile -b fishnchips-eventbus \
   test-event -i file://testdata/event.json -e fishnch

eventbridge-cli -p myawsprofile -b fishnchips-eventbus \
   test-event \
   	-i file://testdata/event.json \
   	-e fishnchips-eventbridge-BetaFunctionEventListener

eventbridge-cli -p myawsprofile -b fishnchips-eventbus \
   test-event \
   	-i '{"version":"0", "id": "cwe-test", "account": "123456789012", "region": "eu-north-1", "time": "2017-04-11T20:11:04Z", "source": ["beta"], "detail": {"channel": ["web"]}, "detail-type": ["poc.succeeded"]}' \
   	-e fishnchips-eventbridge-BetaFunctionEventListener

Content-based Filtering with Event Patterns reference:

https://docs.aws.amazon.com/eventbridge/latest/userguide/content-filtering-with-event-patterns.html

Here is a summary of all the comparison operators available in EventBridge:

Comparison	Example	Rule syntax
Null	UserID is null	"UserID": [ null ]
Empty	LastName is empty	"LastName": [""]
Equals	Name is "Alice"	"Name": [ "Alice" ]
And	Location is "New York" and Day is "Monday"	"Location": [ "New York" ], "Day": [ "Monday" ]
Or	PaymentType is "Credit" or "Debit"	"PaymentType": [ "Credit", "Debit" ]
Not	Weather is anything but "Raining"	"Weather": [{ "anything-but": [ "Raining" ] }]
Numeric (equals)	Price is 100	"Price": [{ "numeric": [ "=", 100 ] }]
Numeric (range)	Price is more than 10, and less than or equal to 20	"Price": [{ "numeric": [ ">", 10, "<=", 20 ] }]
Exists	ProductName exists	"ProductName": [{ "exists": true }]
Does not exist	ProductName does not exist	"ProductName": [{ "exists": false }]
Begins with	Region is in the US	"Region": [{ "prefix": "us-" }]