AWS batch documentation change
Summary
Restructured documentation to focus on fair-share scheduling monitoring. Removed detailed service job monitoring sections and added new 'Active shares' section explaining capacity utilization tracking for share identifiers.
Security assessment
The changes focus on improving visibility into resource allocation patterns rather than addressing security vulnerabilities. While the documentation now better explains fair-share scheduling mechanics, there's no evidence of patching security flaws or introducing new security controls. The removed service job monitoring sections were operational rather than security-focused.
Diff
diff --git a/batch/latest/userguide/job_queue_viewing_status.md b/batch/latest/userguide/job_queue_viewing_status.md index 8acc57992..e6dda63c5 100644 --- a//batch/latest/userguide/job_queue_viewing_status.md +++ b//batch/latest/userguide/job_queue_viewing_status.md @@ -5 +5 @@ -View job queue information Monitor service jobs +View job queue information @@ -7 +7 @@ View job queue information Monitor service jobs -# View job queue status +# View a job queue in AWS Batch @@ -21,59 +21 @@ To find this information through the AWS Command Line Interface, use the [`Descr -### Job queue snapshot - -This section provides a static list of the first 100 `RUNNABLE`jobs that are in queue. You can use the search field to narrow the list by searching for information from any column in the results section. The jobs in the snapshot results area are sorted according to the job queue’s run strategy. For first-in-first-out (FIFO) job queues, the ordering of the jobs is based on the submission time. For [fair-share scheduling](./fair-share-scheduling.html) job queues, the ordering of the jobs is based on the job priority and share usage. - -Because the results are a snapshot of the job queue, the results list doesn’t automatically update. To update the list, choose the refresh at the top of the section. Choose the job’s name hyperlink to navigate to **Job details** and view the job’s status and other related information. - -To find this information through the AWS CLI, use the [`GetJobQueueSnapshot`](https://docs.aws.amazon.com/batch/latest/APIReference/API_GetJobQueueSnapshot.html) operation along with the job queue name or the corresponding ARN. - - - aws batch get-job-queue-snapshot --job-queue my-sm-training-fifo-jq - -### Job state limits - -Use this tab to review configuration information about the amount of time that a job can remain in a `RUNNABLE` state before it’s canceled. - -To find this information through the AWS CLI, use the [`DescribeJobQueues`](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeJobQueues.html) operation along with the job queue name or the corresponding ARN. - -### Environment order - -If your job queue runs in multiple environments, this tab provides their order and an overview. - -To find this information through the AWS CLI, use the [`DescribeJobQueues`](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeJobQueues.html) operation along with the job queue name or the corresponding ARN. - -### Tags - -Use this tab to review and manage tags that are associated to this job queue. - -### JSON - -Use this tab to copy the JSON code that’s associated with this job queue. You can then reuse the JSON for AWS CloudFormation templates and AWS CLI scripts. - -## Monitor service jobs - -You can monitor the status of service jobs in your job queue using several AWS Batch commands. Service jobs are jobs that run on AWS services such as SageMaker Training, where AWS Batch provides scheduling and queuing capabilities while the target service handles job execution. - -### List service jobs by status - -Use the [`ListServiceJobs`](https://docs.aws.amazon.com/batch/latest/APIReference/API_ListServiceJobs.html) operation to view service jobs in your queue filtered by status. Service jobs can have the following statuses: - - * `SUBMITTED` \- Job has been submitted but not yet processed - - * `PENDING` \- Job is pending and waiting for resources - - * `RUNNABLE` \- Job is ready to run and waiting in the queue - - * `STARTING` \- Job is being started - - * `RUNNING` \- Job is currently running - - * `SCHEDULED` \- Job has been submitted to the target service but not yet running - - * `SUCCEEDED` \- Job completed successfully - - * `FAILED` \- Job failed to complete - - - - -View running jobs in your queue: +### Active shares @@ -80,0 +23 @@ View running jobs in your queue: +For job queues using fair-share scheduling, AWS Batch provides visibility into how different share identifiers consume capacity. This information helps you understand resource distribution and identify shares that may need adjustment. @@ -82,3 +25 @@ View running jobs in your queue: - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --job-status RUNNING +###### Note @@ -86 +27 @@ View running jobs in your queue: -View jobs waiting in the queue: +The **Active shares** tab is only present when the job queue's **Scheduling algorithm** is Fair-share. @@ -87,0 +29 @@ View jobs waiting in the queue: +The top 20 active shares section shows share identifiers whose scheduled, starting, and running jobs. This view includes: @@ -89,3 +31 @@ View jobs waiting in the queue: - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --job-status RUNNABLE + * **Share identifier name** \- The unique identifier for the share. @@ -93 +33 @@ View jobs waiting in the queue: -View jobs that have been submitted to SageMaker but not yet running: +Share identifiers are labels that group jobs for fair-share scheduling. When you submit jobs with the same share identifier, AWS Batch treats them as part of the same workload for resource allocation purposes. Share identifiers help ensure equitable distribution of compute capacity across different teams, projects, or workload types. For more information, see [Use share identifiers to identify workloads](./share-identifiers.html). @@ -94,0 +35 @@ View jobs that have been submitted to SageMaker but not yet running: + * **Capacity utilization** \- The amount of resources the job is configured to use. This is measured in `instances`, `cpu`, or `vCPU` depending on the environment. @@ -96,3 +37 @@ View jobs that have been submitted to SageMaker but not yet running: - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --job-status SCHEDULED + * **View jobs action** \- A link to see all jobs for that share. @@ -100 +38,0 @@ View jobs that have been submitted to SageMaker but not yet running: -View all succeeded jobs: @@ -103,3 +40,0 @@ View all succeeded jobs: - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --job-status SUCCEEDED @@ -107 +42 @@ View all succeeded jobs: -View failed jobs for troubleshooting: +You can view this information in both list and chart formats: @@ -108,0 +44 @@ View failed jobs for troubleshooting: + * **List view** \- Tabular display with exact capacity numbers @@ -110,3 +46 @@ View failed jobs for troubleshooting: - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --job-status FAILED + * **Chart view** \- Visual bar chart showing relative utilization @@ -114,68 +47,0 @@ View failed jobs for troubleshooting: -### Filter service jobs - -You can filter service jobs by name using pattern matching. If a filter value ends with an asterisk (*), it matches any job name that begins with the string before the '*'. - -Find jobs with names starting with "training": - - - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --filters name=JOB_NAME,values=training* - -Find jobs with specific names: - - - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --filters name=JOB_NAME,values=my-training-job-1,my-training-job-2 - -Combine status and name filters: - - - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --job-status RUNNING \ - --filters name=JOB_NAME,values=production* - -### Handle large result sets - -When you have many service jobs, use pagination to manage the results effectively. - -Limit the number of results returned: - - - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --max-results 10 - -Use the next token to get additional results: - - - aws batch list-service-jobs \ - --job-queue my-sm-training-fifo-jq \ - --max-results 10 \ - --next-token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... - -### Get detailed service job information - -Use the [`DescribeServiceJob`](https://docs.aws.amazon.com/batch/latest/APIReference/API_DescribeServiceJob.html) operation to get comprehensive information about a specific service job, including its current status, service resource identifiers, and detailed attempt information. - -View detailed information about a specific job: - - - aws batch describe-service-job \ - --job-id a4d6c728-8ee8-4c65-8e2a-9a5e8f4b7c3d - -This command returns comprehensive information about the job, including: - - * Job ARN and current status - - * Service resource identifiers (such as SageMaker Training job ARN) - - * Scheduling priority and retry configuration - - * Service request payload containing the original service parameters - - * Detailed attempt information with start and stop times - - * Status messages from the target service @@ -184,0 +51 @@ This command returns comprehensive information about the job, including: +### Job queue snapshot @@ -186 +53 @@ This command returns comprehensive information about the job, including: -### Monitor SageMaker Training jobs +This section provides a static list of the first 100 `RUNNABLE` jobs that are in queue. You can use the search field to narrow the list by searching for information from any column in the results section. The jobs in the snapshot results area are sorted according to the job queue’s run strategy. For first-in-first-out (FIFO) job queues, the ordering of the jobs is based on the submission time. For [fair-share scheduling](./fair-share-scheduling.html) job queues, the ordering of the jobs is based on the job priority and share usage. The **Capacity required** field show the amount of resources the job is configured to use. @@ -188 +55 @@ This command returns comprehensive information about the job, including: -When monitoring SageMaker Training jobs through AWS Batch, you can access both AWS Batch job information and the underlying SageMaker Training job details. +Because the results are a snapshot of the job queue, the results list doesn’t automatically update. To update the list, choose the refresh at the top of the section. Choose the job’s name hyperlink to navigate to **Job details** and view the job’s status and other related information. @@ -190 +57 @@ When monitoring SageMaker Training jobs through AWS Batch, you can access both A -The service resource identifier in the job details contains the SageMaker Training job ARN: +To find this information through the AWS CLI, use the [`GetJobQueueSnapshot`](https://docs.aws.amazon.com/batch/latest/APIReference/API_GetJobQueueSnapshot.html) operation along with the job queue name or the corresponding ARN. @@ -193,8 +60 @@ The service resource identifier in the job details contains the SageMaker Traini - { - "latestAttempt": { - "serviceResourceId": { - "name": "TrainingJobArn", - "value": "arn:aws:sagemaker:us-east-1:123456789012:training-job/my-training-job"