# AWS Batch event stream for Amazon EventBridge
You can use the AWS Batch event stream for Amazon EventBridge to receive near real-time notifications regarding the current state of jobs in your job queues.
You can use EventBridge to gain further insights about your AWS Batch service. More specifically, you can use it to check the progress of jobs, build AWS Batch custom workflows, generate usage reports or metrics, or build your own dashboards. With AWS Batch and EventBridge, you don't need scheduling and monitoring code that continuously polls AWS Batch for job status changes. Instead, you can handle AWS Batch job state changes asynchronously using a variety of Amazon EventBridge targets. These include AWS Lambda, Amazon Simple Queue Service, Amazon Simple Notification Service, or Amazon Kinesis Data Streams.
Events from the AWS Batch event stream are ensured to be delivered at least one time. In the event that duplicate events are sent, the event provides enough information to identify duplicates. That way, you can compare the time stamp of the event and the job status.
AWS Batch jobs are available as EventBridge targets. Using simple rules, you can match events and submit AWS Batch jobs in response to them. For more information, see [What is EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) in the *Amazon EventBridge User Guide*. You can also use EventBridge to schedule automated actions that self-trigger at certain times using **cron** or rate expressions. For more information, see [Creating an Amazon EventBridge rule that runs on a schedule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html) in the *Amazon EventBridge User Guide*. For an example walkthrough, see [AWS Batch jobs as EventBridge targets](batch-cwe-target.md). For information about using the EventBridge Scheduler, see [Setting up Amazon EventBridge Scheduler](https://docs.aws.amazon.com/scheduler/latest/UserGuide/setting-up.html) in the Amazon EventBridge User Guide.
**Topics**
+ [
# AWS Batch events
](batch_cwe_events.md)
+ [
# Tutorial: Use AWS user notifications with AWS Batch
](using-user-notifications.md)
+ [
# AWS Batch jobs as EventBridge targets
](batch-cwe-target.md)
+ [
# Tutorial: Listen for AWS Batch job events using EventBridge
](batch_cwet.md)
+ [
# Tutorial: Sending Amazon Simple Notification Service alerts for failed job events
](batch_sns_tutorial.md)
# AWS Batch events
AWS Batch sends job status change events to EventBridge. AWS Batch tracks the state of your jobs. If a previously submitted job's status changes, an event is invoked. For example, if a job in the `RUNNING` status moves to the `FAILED` status. These events are classified as job state change events.
**Note**
AWS Batch might add other event types, sources, and details in the future. If you're programmatically deserializing event JSON data, make sure that your application is prepared to handle unknown properties. This is to avoid issues if and when these additional properties are added.
# Job state change events
Anytime that an existing (previously submitted) job changes states, an event is created. For more information about AWS Batch job states, see [Job states](job_states.md).
**Note**
Events aren't created for the initial job submission.
**Example Job State Change Event**
Job state change events are delivered in the following format. The `detail` section resembles the [JobDetail](https://docs.aws.amazon.com/batch/latest/APIReference/API_JobDetail.html) object that's returned from a [DescribeJobs](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeJobs.html) API operation in the *AWS Batch API Reference*. For more information about EventBridge parameters, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
```
{
"version": "0",
"id": "c8f9c4b5-76e5-d76a-f980-7011e206042b",
"detail-type": "Batch Job State Change",
"source": "aws.batch",
"account": "123456789012",
"time": "2022-01-11T23:36:40Z",
"region": "us-east-1",
"resources": [
"arn:aws:batch:us-east-1:123456789012:job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8"
],
"detail": {
"jobArn": "arn:aws:batch:us-east-1:123456789012:job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"jobName": "event-test",
"jobId": "4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"jobQueue": "arn:aws:batch:us-east-1:123456789012:job-queue/PexjEHappyPathCanary2JobQueue",
"status": "RUNNABLE",
"attempts": [],
"createdAt": 1641944200058,
"retryStrategy": {
"attempts": 2,
"evaluateOnExit": []
},
"dependsOn": [],
"jobDefinition": "arn:aws:batch:us-east-1:123456789012:job-definition/first-run-job-definition:1",
"parameters": {},
"container": {
"image": "137112412989.dkr.ecr.us-east-1.amazonaws.com/amazonlinux:latest",
"command": [
"sleep",
"600"
],
"volumes": [],
"environment": [],
"mountPoints": [],
"ulimits": [],
"networkInterfaces": [],
"resourceRequirements": [
{
"value": "2",
"type": "VCPU"
}, {
"value": "256",
"type": "MEMORY"
}
],
"secrets": []
},
"propagateTags": false,
"platformCapabilities": []
}
}
```
# Job queue blocked events
Anytime that AWS Batch detects a job in the `RUNNABLE` state and thus blocking a queue, an event is created in Amazon CloudWatch Events. For more information about supported blocked queue causes, see [Jobs stuck in a `RUNNABLE` status](job_stuck_in_runnable.md). The same reason is also available in the `statusReason` field in the [https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeJobs.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeJobs.html) API action.
**Example Job queue blocked event**
Job queue blocked events are delivered in the following format. The `detail` section resembles the [JobDetail](https://docs.aws.amazon.com/batch/latest/APIReference/API_JobDetail.html) object that's returned from a [DescribeJobs](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeJobs.html) API operation in the *AWS Batch API Reference*. For more information about EventBridge parameters, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
```
{
"version": "0",
"id": "c8f9c4b5-76e5-d76a-f980-7011e206042b",
"detail-type": "Batch Job Queue Blocked",
"source": "aws.batch",
"account": "123456789012",
"time": "2022-01-11T23:36:40Z",
"region": "us-east-1",
"resources": [
"arn:aws:batch:us-east-1:123456789012:job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"arn:aws:batch:us-east-1:123456789012:job-queue/PexjEHappyPathCanary2JobQueue"
],
"detail": {
"jobArn": "arn:aws:batch:us-east-1:123456789012:job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"jobName": "event-test",
"jobId": "4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"jobQueue": "arn:aws:batch:us-east-1:123456789012:job-queue/PexjEHappyPathCanary2JobQueue",
"status": "RUNNABLE",
"statusReason": "blocked-reason",
"attempts": [],
"createdAt": 1641944200058,
"retryStrategy": {
"attempts": 2,
"evaluateOnExit": []
},
"dependsOn": [],
"jobDefinition": "arn:aws:batch:us-east-1:123456789012:job-definition/first-run-job-definition:1",
"parameters": {},
"container": {
"image": "137112412989.dkr.ecr.us-east-1.amazonaws.com/amazonlinux:latest",
"command": [
"sleep",
"600"
],
"volumes": [],
"environment": [],
"mountPoints": [],
"ulimits": [],
"networkInterfaces": [],
"resourceRequirements": [
{
"value": "2",
"type": "VCPU"
}, {
"value": "256",
"type": "MEMORY"
}
],
"secrets": []
},
"propagateTags": false,
"platformCapabilities": []
}
}
```
# Service job state change events
Anytime that an existing service job changes states, an event is created. For more information about service job states, see [Mapping AWS Batch service job status to SageMaker AI status](service-job-status.md).
**Note**
Events aren't created for the initial job submission.
**Example Service Job State Change Event**
Service job state change events are delivered in the following format. The `detail` section resembles the response that's returned from a [DescribeServiceJob](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeServiceJob.html) API operation in the *AWS Batch API Reference*. For more information about EventBridge parameters, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
The `tags` and `serviceRequestPayload` fields are not included in the event `detail`.
```
{
"version": "0",
"id": "c8f9c4b5-76e5-d76a-f980-7011e206042b",
"detail-type": "Batch Service Job State Change",
"source": "aws.batch",
"account": "123456789012",
"time": "2022-01-11T23:36:40Z",
"region": "us-east-1",
"resources": [
"arn:aws:batch:us-east-1:123456789012:service-job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8"
],
"detail": {
"attempts": [
{
"serviceResourceId": {
"name": "TrainingJobArn",
"value": "arn:aws:sagemaker:us-east-1:123456789012:training-job/AWSBatchmy-training-job88b610a69aa8380ca5b0a7aba3f81cb8"
},
"startedAt": 1641944300058,
"stoppedAt": 1641944400058,
"statusReason": "Received status from SageMaker: Training job completed"
}
],
"createdAt": 1641944200058,
"jobArn": "arn:aws:batch:us-east-1:123456789012:service-job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"jobId": "0bb17543-ece6-4480-b1a7-a556d344746b",
"jobName": "event-test",
"jobQueue": "arn:aws:batch:us-east-1:123456789012:job-queue/HappyPathJobQueue",
"latestAttempt": {
"serviceResourceId": {
"name": "TrainingJobArn",
"value": "arn:aws:sagemaker:us-east-1:123456789012:training-job/AWSBatchmy-training-job88b610a69aa8380ca5b0a7aba3f81cb8"
}
},
"serviceJobType": "SAGEMAKER_TRAINING",
"startedAt": 1641944300058,
"status": "SUCCEEDED",
"statusReason": "Received status from SageMaker: Training job completed",
"stoppedAt": 1641944400058,
"timeoutConfig": {
"attemptDurationSeconds": 60
}
}
}
```
# Service job queue blocked events
Anytime that AWS Batch detects a blocked queue, an event is created in Amazon CloudWatch Events. The reason for the blocked queue is available in the `statusReason` field in the [https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeServiceJob.html](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeServiceJob.html) API action.
**Example Service Job Queue Blocked Event**
Service job queue blocked events are delivered in the following format. The `detail` section resembles the response that's returned from the [DescribeServiceJob](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeServiceJob.html) API operation in the *AWS Batch API Reference*. For more information about EventBridge parameters, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
The `tags` and `serviceRequestPayload` fields are not included in the event `detail`.
```
{
"version": "0",
"id": "c8f9c4b5-76e5-d76a-f980-7011e206042b",
"detail-type": "Batch Service Job Queue Blocked",
"source": "aws.batch",
"account": "123456789012",
"time": "2022-01-11T23:36:40Z",
"region": "us-east-1",
"resources": [
"arn:aws:batch:us-east-1:123456789012:service-job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8"
],
"detail": {
"attempts": [],
"createdAt": 1641944200058,
"jobArn": "arn:aws:batch:us-east-1:123456789012:service-job/4c7599ae-0a82-49aa-ba5a-4727fcce14a8",
"jobId": "6271dfdf-d8a7-41b1-a4d2-55a2224f5375",
"jobName": "event-test",
"jobQueue": "arn:aws:batch:us-east-1:123456789012:job-queue/HappyPathJobQueue",
"serviceJobType": "SAGEMAKER_TRAINING",
"status": "RUNNABLE",
"statusReason": "blocked-reason",
"timeoutConfig": {
"attemptDurationSeconds": 60
}
}
}
```
# Service job preemption events
Preemption events are published whenever a preemption sequence starts or completes. A started event is created when preemption is first triggered to reclaim borrowed capacity. A completed event is created when the preemption sequence finishes and includes a summary of the preempted attempts.
**Example Service Job Preemption Started Event**
Service job preemption started events are delivered in the following format. For more information about EventBridge parameters, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
```
{
"version": "0",
"id": "1b4a511e-2737-226a-a1e7-fc97f1cd9681",
"detail-type": "Batch Service Job Preemption Started",
"source": "aws.batch",
"account": "123456789012",
"time": "2026-03-16T19:57:27Z",
"region": "us-east-1",
"resources": [
"arn:aws:batch:us-east-1:123456789012:service-job/51f245a9-2995-4a53-bced-7b3c00028f84"
],
"detail": {
"statusReason": "PREEMPTION_IN_PROGRESS: Cross-share preemption triggered to reclaim borrowed capacity",
"preemptedJobArn": "arn:aws:batch:us-east-1:123456789012:service-job/51f245a9-2995-4a53-bced-7b3c00028f84",
"status": "RUNNING"
}
}
```
**Example Service Job Preemption Completed Event**
Service job preemption completed events are delivered in the following format. The `preemptionSummary` field contains details about the preempted attempts, including the count and the most recent preempted attempt information.
```
{
"version": "0",
"id": "2b1c6151-c166-edf5-822c-211b3bfd46b2",
"detail-type": "Batch Service Job Preemption Completed",
"source": "aws.batch",
"account": "123456789012",
"time": "2026-03-16T19:57:47Z",
"region": "us-east-1",
"resources": [
"arn:aws:batch:us-east-1:123456789012:service-job/51f245a9-2995-4a53-bced-7b3c00028f84"
],
"detail": {
"preemptedJobArn": "arn:aws:batch:us-east-1:123456789012:service-job/51f245a9-2995-4a53-bced-7b3c00028f84",
"preemptionSummary": {
"preemptedAttemptCount": 1,
"recentPreemptedAttempts": [
{
"serviceResourceId": {
"name": "TrainingJobArn",
"value": "arn:aws:sagemaker:us-east-1:123456789012:training-job/AWSBatchqm-training-job9b2f08f911cf3dd794c1b3e72ae7ca5f"
},
"startedAt": 1773690923359,
"stoppedAt": 1773691064669,
"statusReason": "Cross-share preemption triggered to reclaim borrowed capacity"
}
]
},
"status": "RUNNABLE"
}
}
```
# Tutorial: Use AWS user notifications with AWS Batch
You can use [AWS User Notifications](https://docs.aws.amazon.com/notifications/latest/userguide/what-is.html) to set up delivery channels to get notified about AWS Batch events. You receive a notification when an event matches a rule that you specify. You can receive notifications for events through multiple channels, including email, [Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/what-is.html) chat notifications, or [AWS Console Mobile Application](https://docs.aws.amazon.com/consolemobileapp/latest/userguide/what-is-consolemobileapp.html) push notifications. You can also see notifications in the [Console Notifications Center](https://console.aws.amazon.com/notifications/). User Notifications supports aggregation, which can reduce the number of notifications you receive during specific events.
To configure User Notifications in AWS Batch:
1. Open the [AWS Batch console](https://console.aws.amazon.com/batch/home).
1. Choose **Dashboard**.
1. Choose **Configure Notifications**.
1. In** AWS User Notifications**, choose **Create notification configuration**.
For more information about how to configure and view user notifications, see [Getting started with AWS User Notifications](https://docs.aws.amazon.com/notifications/latest/userguide/getting-started.html).
# AWS Batch jobs as EventBridge targets
Amazon EventBridge delivers a near real-time stream of system events that describe changes in Amazon Web Services resources. Typically, AWS Batch on Amazon Elastic Container Service, Amazon Elastic Kubernetes Service, and AWS Fargate jobs are available as EventBridge targets. Using simple rules, you can match events and submit AWS Batch jobs in response to them. For more information, see [What is EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) in the *Amazon EventBridge User Guide*.
You can also use EventBridge to schedule automated actions that are invoked at certain times using **cron** or rate expressions. For more information, see [Creating an Amazon EventBridge rule that runs on a schedule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html) in the *Amazon EventBridge User Guide*.
For information about how to create a rule that runs when an event matches an event pattern, see [Creating Amazon EventBridge rules that react to events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html) in the *Amazon EventBridge User Guide*.
Common use cases for AWS Batch jobs as an EventBridge target include the following use cases:
+ A scheduled job occurs at regular time intervals. For example, a **cron** job occurs only during low-usage hours when Amazon EC2 Spot Instances are less expensive.
+ An AWS Batch job runs in response to an API operation that's logged in CloudTrail. For example, a job is submitted whenever an object is uploaded to a specified Amazon S3 bucket. Each time this happens, the EventBridge input transformer passes the bucket and key name of the object to AWS Batch parameters.
**Note**
In this scenario, all of related AWS resources must be in the same Region. This includes resources such as the Amazon S3 bucket, EventBridge rule, and CloudTrail logs.
Before you can submit AWS Batch jobs with EventBridge rules and targets, the EventBridge service requires several permissions to run AWS Batch jobs. When you create a rule in the EventBridge console that specifies an AWS Batch job as a target, you can also create this role. For more information about the required service principal and IAM permissions for this role, see [EventBridge IAM role](CWE_IAM_role.md).
**Topics**
+ [
# Tutorial: Create a scheduled AWS Batch job
](scheduled-batch-job.md)
+ [
# Tutorial: Create a rule with an event pattern
](event-pattern-batch-job.md)
+ [
# Tutorial: Pass event information to an AWS Batch target on a schedule using the EventBridge input transformer
](cwe-input-transformer.md)
# Tutorial: Create a scheduled AWS Batch job
The following procedure covers how to create a scheduled AWS Batch job and the required EventBridge IAM role.
**To create a scheduled AWS Batch job with EventBridge**
**Note**
This procedure works for all AWS Batch on Amazon ECS, Amazon EKS, and AWS Fargate jobs.
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. From the navigation bar, select the AWS Region to use.
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. For **Name**, specify a unique name for your compute environment. The name can contain up to 64 characters. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
**Note**
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. (Optional) For **Description**, enter a description for the rule.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **default**. When an AWS service in your account emits an event, it always goes to your account's default event bus.
1. (Optional) Turn off the rule on the selected bus if you don't want to run the rule immediately.
1. For **Rule type**, choose **Schedule**.
1. Choose **Continue to create rule** or **Next**.
1. For **Schedule pattern**, do one of the following:
+ Choose **A fine-grained schedule that runs at a specific time, such as 8:00 a.m. PST on the first Monday of every month** and then enter a cron expression. For more information, see [Cron Expressions](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html#eb-cron-expressions) in the *Amazon EventBridge User Guide*.
+ Choose **A schedule that runs at a regular rate, such as every 10 minutes.** and then enter a rate expression.
1. Choose **Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, choose **Batch job queue**. Then, configure the following:
+ **Job queue:** Enter the Amazon Resource Name (ARN) of the job queue to schedule your job in.
+ **Job definition:** Enter the name and revision or full ARN of the job definition to use for your job.
+ **Job name:** Enter a name for your job.
+ **Array size:** (Optional) Enter an array size for your job to run more than one copy. For more information, see [Array jobs](array_jobs.md).
+ **Job attempts:** (Optional) Enter the number of times to retry your job if it fails. For more information, see [Automated job retries](job_retries.md).
1. For **Batch job queue** target types, EventBridge needs permission to send events to the target. EventBridge can create the IAM role needed for your rule to run. Do one of the following:
+ To create an IAM role automatically, choose **Create a new role for this specific resource**.
+ To use an IAM role that you've already created, choose **Use existing role**.
1. (Optional) Expand **Additional settings**.
1. For **Configure target input**, choose how the text from an event is processed before it's passed to the target.
1. For **Maximum age of event**, specify the time interval for how long unprocessed events are kept.
1. For **Retry attempts**, enter the number of times that an event is retried.
1. For **Dead-letter queue,** choose an option for how unprocessed events are handled. If necessary, specify the Amazon SQS queue to use as the dead-letter queue.
1. (Optional) Choose **Add another target** to add another target for this rule.
1. Choose **Next**.
1. (Optional) For **Tags**, choose **Add new tag** to add a resource label for the rule. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html).
1. Choose **Next**.
1. For **Review and create**, review the configuration steps. If you need to make changes, choose **Edit**. When you're finished, choose **Create rule**.
For more information about creating rules, see [Creating an Amazon EventBridge rule that runs on a schedule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html) in the *Amazon EventBridge User Guide*.
# Tutorial: Create a rule with an event pattern
The following procedure covers how to create a rule with an event pattern.
**To create a rule that sends the event to a target when the event matches a defined pattern**
**Note**
This procedure works for all AWS Batch on Amazon ECS, Amazon EKS, and AWS Fargate jobs.
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. From the navigation bar, select the AWS Region to use.
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. For **Name**, specify a unique name for your compute environment. The name can contain up to 64 characters. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
**Note**
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. (Optional) For **Description**, enter a description for the rule.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **default**. When an AWS service in your account emits an event, it always goes to your account's default event bus.
1. (Optional) Turn off the rule on the selected bus if you don't want to run the rule immediately.
1. For **Rule type**, choose **Rule with an event pattern**.
1. Choose** Next**.
1. For **Event Source**, choose **AWS event or EventBridge partner events**.
1. (Optional) For **Sample event**:
1. For **Sample event type**, choose **AWS events**.
1. For **Sample events**, choose **Batch Job State Change**.
1. For **Creation method**, choose **Use pattern form**.
1. For **Event pattern**:
1. For **Event source**, choose **AWS services**.
1. For **AWS service**, choose **Batch**.
1. For **Event type**, choose **Batch Job State Change**.
1. Choose** Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, choose a target type. For example, choose **Batch job queue**. Then specify the following:
+ **Job queue:** Enter the Amazon Resource Name (ARN) of the job queue to schedule your job in.
+ **Job definition:** Enter the name and revision or full ARN of the job definition to use for your job.
+ **Job name:** Enter a name for your job.
+ **Array size:** (Optional) Enter an array size for your job to run more than one copy. For more information, see [Array jobs](array_jobs.md).
+ **Job attempts:** (Optional) Enter the number of times to retry your job if it fails. For more information, see [Automated job retries](job_retries.md).
1. For **Batch job queue** target types, EventBridge needs permission to send events to the target. EventBridge can create the IAM role needed for your rule to run. Do one of the following:
+ To create an IAM role automatically, choose **Create a new role for this specific resource**.
+ To use an IAM role that you created before, choose **Use existing role**.
1. (Optional) Expand **Additional settings**.
1. For **Configure target input**, choose how text from an event is processed.
1. For **Maximum age of event**, specify the time interval for how long unprocessed events are kept.
1. For **Retry attempts**, enter the number of times that an event is retried.
1. For **Dead-letter queue,** choose an option for how unprocessed events are handled. If necessary, specify the Amazon SQS queue to use as the dead-letter queue.
1. (Optional) Choose **Add another target** to add an additional target.
1. Choose **Next**.
1. (Optional) For **Tags**, choose **Add new tag** to add a resource label. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. For **Review and create**, review the configuration steps. If you need to make changes, choose **Edit**. After you're finished, choose **Create rule**.
For more information about creating rules, see [Creating Amazon EventBridge rules that react to events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html) in the *Amazon EventBridge User Guide*.
# Tutorial: Pass event information to an AWS Batch target on a schedule using the EventBridge input transformer
You can use the EventBridge input transformer to pass event information to AWS Batch in a job submission. This can be especially valuable if you invoke jobs as a result of other AWS event information. One example is an object upload to an Amazon S3 bucket. You can also use a job definition with parameter substitution values in the container's command. The EventBridge input transformer can provide the parameter values based on the event data.
Then, afterwards, you create an AWS Batch event target that parses information from the event that starts it and transforms it into a `parameters` object. When the job runs, the parameters from the trigger event are passed to the command of the job container.
**Note**
In this scenario, all of the AWS resources (such as Amazon S3 buckets, EventBridge rules, and CloudTrail logs) must be in the same Region.
**To create an AWS Batch target that uses the input transformer**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. From the navigation bar, select the AWS Region to use.
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. For **Name**, specify a unique name for your compute environment. The name can contain up to 64 characters. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (\$1).
**Note**
A rule can't have the same name as another rule in the same AWS Region and on the same event bus.
1. (Optional) For **Description**, enter a description for the rule.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **default**. When an AWS service in your account emits an event, it always goes to your account's default event bus.
1. (Optional) Turn off the rule on the selected bus if you don't want to run the rule immediately.
1. For **Rule type**, choose **Schedule**.
1. Choose **Continue to create rule** or **Next**.
1. For **Schedule pattern**, do one of the following:
+ Choose **A fine-grained schedule that runs at a specific time, such as 8:00 a.m. PST on the first Monday of every month** and then enter a cron expression. For more information, see [Cron Expressions](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html#eb-cron-expressions) in the *Amazon EventBridge User Guide*.
+ Choose **A schedule that runs at a regular rate, such as every 10 minutes.** and then enter a rate expression.
1. Choose **Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, choose **Batch job queue**. Then, configure the following:
+ **Job queue:** Enter the Amazon Resource Name (ARN) of the job queue to schedule your job in.
+ **Job definition:** Enter the name and revision or full ARN of the job definition to use for your job.
+ **Job name:** Enter a name for your job.
+ **Array size:** (Optional) Enter an array size for your job to run more than one copy. For more information, see [Array jobs](array_jobs.md).
+ **Job attempts:** (Optional) Enter the number of times to retry your job if it fails. For more information, see [Automated job retries](job_retries.md).
1. For **Batch job queue** target types, EventBridge needs permission to send events to the target. EventBridge can create the IAM role needed for your rule to run. Do one of the following:
+ To create an IAM role automatically, choose **Create a new role for this specific resource**.
+ To use an IAM role that you've already created, choose **Use existing role**.
1. (Optional) Expand **Additional settings**.
1. In the **Additional settings** section, for **Configure target input**, choose **Input Transformer**.
1. Choose **Configure input transformer**.
1. (Optional) For **Sample event**:
1. For **Sample event type**, choose **AWS events**.
1. For **Sample events**, choose **Batch Job State Change**.
1. In the **Target input transformer** section, for **Input path**, specify the values to parse from the triggering event. For example, to parse **Batch Job State Change** event, use the following JSON format.
```
{
"instance": "$.detail.jobId",
"state": "$.detail.status"
}
```
1. For **Template**, enter the following.
```
{
"instance": ,
"status":
}
```
1. Choose **Confirm**.
1. For **Maximum age of event**, specify the time interval for how long unprocessed events are kept.
1. For **Retry attempts**, enter the number of times that an event is retried.
1. For **Dead-letter queue,** choose an option for how unprocessed events are handled. If necessary, specify the Amazon SQS queue to use as the dead-letter queue.
1. (Optional) Choose **Add another target** to add an additional target.
1. Choose **Next**.
1. (Optional) For **Tags**, choose **Add new tag** to add a resource label. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. For **Review and create**, review the configuration steps. If you need to make changes, choose **Edit**. After you're finished, choose **Create rule**.
# Tutorial: Listen for AWS Batch job events using EventBridge
In this tutorial, you set up a simple AWS Lambda function that listens for AWS Batch job events and writes them out to a CloudWatch Logs log stream.
## Prerequisites
This tutorial assumes that you have a working compute environment and job queue that are ready to accept jobs. If you don't have a running compute environment and job queue to capture events from, follow the steps in [Getting started with AWS Batch tutorials](Batch_GetStarted.md) to create one. At the end of this tutorial, you can optionally submit a job to this job queue to test that you have configured your Lambda function correctly.
**Topics**
+ [
## Prerequisites
](#cwet_prereqs)
+ [
# Tutorial: Create the Lambda function
](cwet_create_lam.md)
+ [
# Tutorial: Register the event rule
](cwet_register_event_rule.md)
+ [
# Tutorial: Test your configuration
](cwet_test.md)
# Tutorial: Create the Lambda function
In this procedure, you create a simple Lambda function to serve as a target for AWS Batch event stream messages.
**To create a target Lambda function**
1. Open the AWS Lambda console at [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).
1. Choose **Create function**, **Author from scratch**.
1. For **Function name**, enter **batch-event-stream-handler**.
1. For **Runtime**, choose **Python 3.8**.
1. Choose **Create function**.
1. In the **Code source** section, edit the sample code to match the following example:
```
import json
def lambda_handler(event, _context):
# _context is not used
del _context
if event["source"] != "aws.batch":
raise ValueError("Function only supports input from events with a source type of: aws.batch")
print(json.dumps(event))
```
This is a simple Python 3.8 function that prints the events sent by AWS Batch. If everything is configured correctly, at the end of this tutorial, the event details appear in the CloudWatch Logs log stream that's associated with this Lambda function.
1. Choose **Deploy**.
# Tutorial: Register the event rule
In this section, you create an EventBridge event rule that captures job events that are coming from your AWS Batch resources. This rule captures all events coming from AWS Batch within the account where it's defined. The job messages themselves contain information about the event source, including the job queue where it was submitted. You can use this information to filter and sort events programmatically.
**Note**
If you use the AWS Management Console to create an event rule, the console automatically adds the IAM permissions for EventBridge to call your Lambda function. However, if you're creating an event rule using the AWS CLI, you must grant permissions explicitly. For more information, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
**To create your EventBridge rule**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. Enter a name and description for the rule.
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **AWS default event bus**. When an AWS service in your account emits an event, it always goes to your account's default event bus.
1. For **Rule type**, choose **Rule with an event pattern**.
1. Choose **Next**.
1. For **Event source**, choose **Other**.
1. For **Event pattern**, select **Custom patterns (JSON editor)**.
1. Paste the following event pattern into the text area.
```
{
"source": [
"aws.batch"
]
}
```
This rule applies across all of your AWS Batch groups and to every AWS Batch event. Alternatively, you can create a more specific rule to filter out some results.
1. Choose **Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, choose **Lambda function**, and select your Lambda function.
1. (Optional) For **Additional settings**, do the following:
1. For **Maximum age of event**, enter a value between one minute (00:01) and 24 hours (24:00).
1. For **Retry attempts**, enter a number between 0 and 185.
1. For **Dead-letter queue**, choose whether to use a standard Amazon SQS queue as a dead-letter queue. EventBridge sends events that match this rule to the dead-letter queue if they are not successfully delivered to the target. Do one of the following:
+ Choose **None** to not use a dead-letter queue.
+ Choose **Select an Amazon SQS queue in the current AWS account to use as the dead-letter queue** and then select the queue to use from the dropdown.
+ Choose **Select an Amazon SQS queue in an other AWS account as a dead-letter queue** and then enter the ARN of the queue to use. You must attach a resource-based policy to the queue that grants EventBridge permission to send messages to it. For more information, see [Granting permissions to the dead-letter queue](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-dlq.html#eb-dlq-perms) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. (Optional) Enter one or more tags for the rule. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. Review the details of the rule and choose **Create rule**.
# Tutorial: Test your configuration
You can now test your EventBridge configuration by submitting a job to your job queue. If everything is configured properly, your Lambda function is triggered and it writes the event data to a CloudWatch Logs log stream for the function.
**To test your configuration**
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. Submit a new AWS Batch job. For more information, see [Tutorial: submit a job](submit_job.md).
1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. On the navigation pane, choose **Logs** and select the log group for your Lambda function (for example, **/aws/lambda/***my-function*).
1. Select a log stream to view the event data.
# Tutorial: Sending Amazon Simple Notification Service alerts for failed job events
In this tutorial, you configure an Amazon EventBridge event rule that only captures job events where the job has moved to a `FAILED` status. At the end of this tutorial, you can optionally also submit a job to this job queue. This is to test that you have configured your Amazon SNS alerts correctly.
## Prerequisites
This tutorial assumes that you have a working compute environment and job queue that are ready to accept jobs. If you don't have a running compute environment and job queue to capture events from, follow the steps in [Getting started with AWS Batch tutorials](Batch_GetStarted.md) to create one.
**Topics**
+ [
## Prerequisites
](#batch_sns_prereq)
+ [
# Tutorial: Create and subscribe to an Amazon SNS topic
](batch_sns_create_topic.md)
+ [
# Tutorial: Register an event rule
](batch_sns_reg_rule.md)
+ [
# Tutorial: Test your rule
](batch_sns_test_rule.md)
+ [
## Alternate rule: Batch job queue blocked
](#test_blocked_job_queue)
# Tutorial: Create and subscribe to an Amazon SNS topic
For this tutorial, you configure an Amazon SNS topic to serve as an event target for your new event rule.
**To create an Amazon SNS topic**
1. Open the Amazon SNS console at [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
1. Choose **Topics**, **Create topic**.
1. For **Type**, choose **Standard**.
1. For **Name**, enter **JobFailedAlert** and choose **Create topic**.
1. On the **JobFailedAlert** screen, choose **Create subscription**.
1. For **Protocol**, choose **Email**.
1. For **Endpoint**, enter an email address that you currently have access to and choose **Create subscription**.
1. Check your email account, and wait to receive a subscription confirmation email message. When you receive it, choose **Confirm subscription**.
# Tutorial: Register an event rule
Next, register an event rule that captures only job-failed events.
**To register your EventBridge rule**
1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/).
1. In the navigation pane, choose **Rules**.
1. Choose **Create rule**.
1. Enter a name and description for the rule.
A rule can't have the same name as another rule in the same Region and on the same event bus.
1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **AWS default event bus**. When an AWS service in your account emits an event, it always goes to your account's default event bus.
1. For **Rule type**, choose **Rule with an event pattern**.
1. Choose **Next**.
1. For **Event source**, choose **Other**.
1. For **Event pattern**, select **Custom patterns (JSON editor)**.
1. Paste the following event pattern into the text area.
```
{
"detail-type": [
"Batch Job State Change"
],
"source": [
"aws.batch"
],
"detail": {
"status": [
"FAILED"
]
}
}
```
This code defines an EventBridge rule that matches any event where the job status is `FAILED`. For more information about event patterns, see [Events and Event Patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. For **Target types**, choose **AWS service**.
1. For **Select a target**, choose **SNS topic**, and for **Topic**, choose **JobFailedAlert**.
1. (Optional) For **Additional settings**, do the following:
1. For **Maximum age of event**, enter a value between one minute (00:01) and 24 hours (24:00).
1. For **Retry attempts**, enter a number between 0 and 185.
1. For **Dead-letter queue**, choose whether to use a standard Amazon SQS queue as a dead-letter queue. EventBridge sends events that match this rule to the dead-letter queue if they are not successfully delivered to the target. Do one of the following:
+ Choose **None** to not use a dead-letter queue.
+ Choose **Select an Amazon SQS queue in the current AWS account to use as the dead-letter queue** and then select the queue to use from the dropdown.
+ Choose **Select an Amazon SQS queue in an other AWS account as a dead-letter queue** and then enter the ARN of the queue to use. You must attach a resource-based policy to the queue that grants EventBridge permission to send messages to it. For more information, see [Granting permissions to the dead-letter queue](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rule-dlq.html#eb-dlq-perms) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. (Optional) Enter one or more tags for the rule. For more information, see [Amazon EventBridge tags](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-tagging.html) in the *Amazon EventBridge User Guide*.
1. Choose **Next**.
1. Review the details of the rule and choose **Create rule**.
# Tutorial: Test your rule
To test your rule, submit a job that exits shortly after it starts with a non-zero exit code. If your event rule is configured correctly, you should receive an email message within a few minutes with the event text.
**To test a rule**
1. Open the AWS Batch console at [https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/).
1. Submit a new AWS Batch job. For more information, see [Tutorial: submit a job](submit_job.md). For the job's command, substitute this command to exit the container with an exit code of 1.
```
/bin/sh, -c, 'exit 1'
```
1. Check your email to confirm that you received an email alert for the failed job notification.
## Alternate rule: Batch job queue blocked
To create an event rule that monitors for *batch job queue blocked*, repeat these tutorials with the following alterations:
1. **In [Tutorial: Create and subscribe to an Amazon SNS topic](batch_sns_create_topic.md) **, use *BlockedJobQueue* as the topic name.
1. **In [Tutorial: Register an event rule](batch_sns_reg_rule.md) **, use the following pattern in the JSON editor:
```
{
"detail-type": [
"Batch Job Queue Blocked"
],
"source": [
"aws.batch"
]
}
```