Scaling logs in AWS PCS

Scaling logs give you a record of how AWS Parallel Computing Service scales the compute node groups in your cluster. Each log entry records one state transition for one compute node: for example, an instance launch, a node registration, a scale-down, or a launch failure with its reason. You can use scaling logs to answer questions such as why a node group did not reach its target size, which launches failed for capacity reasons, and when a specific node started or stopped.

You can send scaling logs to Amazon CloudWatch, Amazon Simple Storage Service (Amazon S3), and Amazon Data Firehose. For each transition, AWS PCS records the following data:

AWS PCS delivers scaling logs through the PCS_SCALING_LOGS log type. Scaling log delivery is opt-in. AWS PCS does not deliver scaling logs for a cluster until you configure a delivery for it.

Prerequisites

The IAM principal that manages the AWS PCS cluster must allow the pcs:AllowVendedLogDeliveryForResource action.

The following example IAM policy grants the required permissions.

{
    "Version": "2012-10-17",
    "Statement": [ 
        {
            "Sid": "PcsAllowVendedLogsDelivery",
            "Effect": "Allow",
            "Action": ["pcs:AllowVendedLogDeliveryForResource"],
            "Resource": [
                "arn:aws:pcs:*::cluster/*"
            ]
        }
    ]
}

Set up scaling logs

You can set up scaling logs for your AWS PCS cluster with the AWS Management Console or AWS CLI.

AWS Management Console

To set up scaling logs with the console

1. Open the AWS PCS console.

2. In the navigation pane, choose Clusters.

3. Choose the cluster where you want to add scaling logs.

4. On the cluster details page, choose the Logs tab.

5. Under Scaling Logs, choose Add to add up to 3 log delivery destinations from among CloudWatch Logs, Amazon S3, and Firehose.

6. Choose Update log deliveries.

AWS CLI

To set up scaling logs with the AWS CLI

1. Create a log delivery destination:

   aws logs put-delivery-destination --region region \
     --name pcs-logs-destination \
     --delivery-destination-configuration \
     destinationResourceArn=resource-arn

   Replace:

   • region — The AWS Region where you want to create the destination, such as us-east-1

   • pcs-logs-destination — A name for the destination

   • resource-arn — The Amazon Resource Name (ARN) of a CloudWatch Logs log group, S3 bucket, or Firehose delivery stream.

   For more information, see PutDeliveryDestination in the Amazon CloudWatch Logs API Reference.

2. Set the PCS cluster as a log delivery source:

   aws logs put-delivery-source --region region \
     --name cluster-logs-source-name \
     --resource-arn cluster-arn \
     --log-type PCS_SCALING_LOGS

   Replace:

   • region — The AWS Region of your cluster, such as us-east-1

   • cluster-logs-source-name — A name for the source

   • cluster-arn — the ARN of your AWS PCS cluster

   For more information, see PutDeliverySource in the Amazon CloudWatch Logs API Reference.

3. Connect the delivery source to the delivery destination:

   aws logs create-delivery --region region \
     --delivery-source-name cluster-logs-source \
     --delivery-destination-arn destination-arn

   Replace:

   • region — The AWS Region, such as us-east-1

   • cluster-logs-source — The name of your delivery source

   • destination-arn — The ARN of your delivery destination

   For more information, see CreateDelivery in the Amazon CloudWatch Logs API Reference.

Finding scaling logs

You can configure log destinations in CloudWatch Logs and Amazon S3. AWS PCS uses the following structured path names and file names.

CloudWatch Logs

AWS PCS uses the following name format for the CloudWatch Logs stream:

AWSLogs/PCS/cluster-id/node_lifecycle.log

For example: AWSLogs/PCS/pcs_abc123de45/node_lifecycle.log

Amazon S3

AWS PCS uses the following name format for the S3 path:

AWSLogs/account-id/PCS/region/cluster-id/node_lifecycle/year/month/day/hour/

For example: AWSLogs/111122223333/PCS/us-east-1/pcs_abc123de45/node_lifecycle/2026/09/03/11/

AWS PCS uses the following name format for the log files:

PCS_cluster-id_node_lifecycle_year-month-day-hour_random-id.log.gz

For example: PCS_pcs_abc123de45_node_lifecycle_2026-09-03-11_04be080b.log.gz

Scaling log fields

AWS PCS writes scaling log data as JSON objects. Each log entry contains top-level metadata fields and a details object. The top-level fields identify the cluster, event time, and compute node group and scheduler node ids. The details object holds the transition details.

The following table describes the top-level fields in each log entry.

The following table describes the keys that can appear inside the details object.

Status codes and reason codes

The status_code field tells you the state the node entered. The reason_code field tells you why. For example, a LAUNCH_FAILED status with an INSUFFICIENT_CAPACITY reason means Amazon EC2 could not provide capacity for the requested instance type in the targeted subnet. A LIMIT_EXCEEDED means an Amazon EC2 quota blocked the launch.

Example scaling logs

The following example shows a successful instance launch:

{
    "resource_id": "pcs_abc123de45",
    "resource_type": "PCS_CLUSTER",
    "event_timestamp": 1789179816460,
    "compute_node_group_id": "pcs_abcdef01",
    "scheduler_node_id": "compute-1",
    "status_code": "LAUNCHED",
    "reason_code": "SCHEDULER_REQUESTED",
    "description": "Instance launched to satisfy a scheduler scale-up request.",
    "details": {
        "instance_id": "i-0abc12345def67890",
        "instance_type": "c6i.xlarge",
        "subnet_id": "subnet-0123456789abcdef0"
    }
}

The following example shows a launch failure caused by insufficient EC2 capacity. No instance_id is present because no instance was launched.

{
    "resource_id": "pcs_abc123de45",
    "resource_type": "PCS_CLUSTER",
    "event_timestamp": 1789179816460,
    "compute_node_group_id": "pcs_abcdef01",
    "scheduler_node_id": "compute-2",
    "status_code": "LAUNCH_FAILED",
    "reason_code": "INSUFFICIENT_CAPACITY",
    "description": "Node did not get an instance because there was not enough capacity available.",
    "details": {
        "ec2_error_code": "InsufficientInstanceCapacity"
    }
}