THIS FORK IS NO LONGER BEING UPDATED. PLEASE FOLLOW IT AT @ljacobsson/evb-cli
Pattern generator and debugging tool for EventBridge
npm install -g @mhlabs/evb-cli
evb pattern - Will prompt you with a wizard that helps you build pattern for event matching. This is using EventBridge's schema registry (currently in preview) to let you navigate the schema you want to react on.
evb pattern --format <yaml|json> - Output format. Default is json
For AWS events, such as aws.codepipeline it's already enabled, but for custom events you will have to enable it in the AWS Management Console.
EventBridge Pipes was one of the more exciting serverless announcements at re:Invent 2022. It lets you create a one-to-one mapping between a source and a target service so you can build event driven applications with less Lambda glue functions.
evb pipes helps you create pipes between resources in your CloudFormation/SAM template. Although the AWS::Pipes::Pipe resource is easy to compose, the IAM role that goes with it isn't that straight forward.
Use the --guided flag to get prompted for all optional parameters.
Input transformers are useful when you only want a small portion of the event sent to your target. This command helps you navigate the JSON payload and generate the InputTransformer CloudFormation object
evb input will prompt you with a wizard that helps you build the InputTransformer object. This is using EventBridge's schema registry (currently in preview).
evb input --format <yaml|json> - Output format. Default is json
Select a schema from the schema registry and list its targets. Select a target to browse details such as ARN, event pattern, input transformation, etc.
evb browse will let you browse your schemas and get insights into the targets listening to the source/detail-type combination of your event. This only works with explicit matching on source and detail-type.
Usage: evb diagram|d [options]
Builds an interactive diagram over an eventbus' rules
Options:
-b, --eventbus [eventbus] Eventbus to create diagram for (default: "default")
-p, --profile [profile] AWS profile to use
-h, --help output usage information
This is an experimental feature. Grouping by tag is possible for the following target types: Lambda, StepFunctions, SNS, SQS, Kinesis. More will follow.
Sometimes you start off with a simple EventBridgeRule transform on you AWS::Serverless::Function resource. Later on you might want to evolve it and start using an InputTransformer or retry/DLQ configurations which is only supported by AWS::Events::Rule
Use evb extract-sam-event to unfold the SAM event to full CloudFormation syntax.
Usage: evb test-event|t [options]
Tests an event payload against existing rules on a bus
Options:
-e, --event-input-file [event-file] Path to test event (default: "event.json")
-n, --name-prefix [name-prefix] Name prefix for rules; helpful to narrow against one or a few rules only
-b, --eventbus [eventbus] The eventbus to test against (default: "default")
-a, --all Show all rules, even unmatched ones (default: false)
Example event input can be found here
Usage: evb code-binding|cb [options]
Generates code bindings from the schema registry based on the defined InputPath or InputTransformer
Options:
-t, --template [template] Path to template file
-n, --type-name [typeName] Type name (default: "MyType")
-o, --output-file [outputFile] Output file name. Writes to std out if skipped
-l, --language [language] Output language
-h, --help output usage information
)
If --template is provided, the tool will parse your template and generate code bindings that match the InputPath or InputTransformer that is defined.
If no template is passed to the command, then you will get prompted to select a schema from the registry.
This is using quicktype. See their docs for target languages
Usage: evb find-usages|f [options]
Searches all rules on a bus for matching event patterns.
I.e to find all rules that match on an s3:PutObject event from CloudTrail, use:
evb find-usages -f $.source=aws.s3,$.detail-type=.+CloudTrail,$.detail.eventName=PutObject
Options:
-b, --eventbus [eventbus] Name of the event bus to search. (default: "default")
-f, --filters [filters] Comma separated list of '$.path.to.property=regex-pattern' to filter the event patterns with
-p, --profile [profile] AWS profile to use
--region [region] The AWS region to use. Falls back on AWS_REGION environment variable if not specified
-h, --help output usage information
This command allows you to find usages of specific fields across all event rules on a bus. This could be useful in order to find individual consumers of a specific field in your event payload.
Some examples:
- Find all rules that match on a specific
sourceanddetail-typecombination on a custom bus:evb find-usages --filters $.source=my-custom-source,$.detail-type=my-custom-detail-type--eventbus custombus - Find all rules that trigger on any of AWS CodePipeline, CodeBuild, CodeDeploy, etc events:
evb find-usages --filters $.source=aws\.code.* - Find all rules that trigger on a Lambda failure destination:
evb find-usages --filters $.detail-type='Lambda Function Invocation Result - Failure'
Usage: evb api-destination|api [options]
Generates API Destination SAM template resources
Options:
-t, --template [template] Path to template file (default: "template.yaml")
-p, --profile [profile] AWS profile to use
--region [region] The AWS region to use. Falls back on AWS_REGION environment variable if not specified
-u --url [url] URL to OpenAPI specification of API
Pass a URL to OpenAPI specification of an API and the tool will generate SAM template resources for API Destination resources. It will guide you through the third party OpenAPI schema and let you build mappings between their parameters and your event payload.
Supports OpenAPI 2 and 3.
)
Example of creating a an API Destination that posts codepipeline status updates to Slack
Usage: evb replay|r [options]
Starts a replay of events against a specific destination
Options:
-b, --eventbus [eventbus] The eventbus the archive is stored against (default: "default")
-r, --rule-prefix [rulePrefix] Rule name prefix
-p, --profile [profile] AWS profile to use
-s, --replay-speed [speed] The speed of the replay in % where 0 == all at once and 100 == real time speed
-n, --replay-name [name] The replay name (default: "evb-cli-replay-1605913422337")
--region [region] The AWS region to use. Falls back on AWS_REGION environment variable if not specified
-h, --help output usage information
** Requires evb local >= v0.0.7 **
Evb-cli provides support for paced replay delivery where you can pass a replay speed scalar between 0 and 100 where 0 is as fast as possible (native EventBridge way) and 100 is real time speed where a one hour replay takes one hour. Passing --replay-speed 10 to a one hour replay will scale the replay speed to 6 minutes, but will still retain the same order and a scaled delay between messages.
Currently EventBridge will run your replay at the fastest possible speed. Due to the unordered nature of EventBridge, this means there's an increased likelyhood that your events will be delivered more randomly during a replay than when live.
Your EventBridge targets should always be idempotent, but for debugging purposes you might want the likely order of the events.
For example, you might replay 5 hours of order events and want to expect each order to transition from OPEN to CONFIRMED to DELIVERED in the logical order. If you run a default replay it's likely that these events will be delivered in the wrong order.
When using --replay-speed > 0, each event in the replay will be sent through a Step Functions state machine of 5 state transitions. See Step Functions pricing for you region.
- At delivery, the
replay-namefield will be stripped. - Step Functions is used to pace the replay. EventBridge will consider the replay a success as long as the events were delivered to Step Functions.
Local debugging makes use to API Gateway V2 websockets to forward actual events in the cloud to your developer machine. The requires a Serverless Application Repository app to be installed in your account. Note that depending on your traffic, there will be some small effect on your billing in the form of Lambda invocations, API Gateway invocations, CloudWatch Logs and DynamoDB R/W.
Example of testing a rule before deploying the stack. The user quickly gets feedback on their patterns and input transforms. In this example we're listening to all aws.* events and transforming the output to
{
"source": <source>,
"time": <time>
}
The user then decided to add detail-type to the transform:
{
"source": <source>,
"detail-type": <detail-type>,
"time": <time>
}
There are three methods of consuming events covering three use cases:
Command: evb local --stack-name <stack-name>
Use case: You have a deployed stack and want to analyse the events matching any rule in the stack. Useful if you want to real-time monitor actual behaviour of the application.
Command: evb local --rule <rule logical id (optional)>
Use cases:
- You want to test a pattern or input transformation without deploying the entire stack. This speeds up trial and error resolutions.
- You want to analyse traffic for a given pattern over time
If the rule's logical ID is omitted such as
evb local --rulethe tool will parse the template and let you navigate and choose the rule
Command: evb local --arn <rule-arn>
Use cases:
- You want to test the behaviour of an already deployed rule where you don't know the stack's name or where it doesn't belong to a stack.
Add --replay option to command. This will guide you through a wizard to find the archive and set the time range to replay.
Note that this currently only works together with the -t flag and it requires at least v0.0.8 of the evb-local backend
All evb local commands support a --sam-local flag. When used, events will be passed on to sam-local for more advanced debugging