AWS CLI Command Reference

[ aws . cloudwatch ]

put-log-alarm

Description

Creates or updates a log alarm. A log alarm evaluates the results of a CloudWatch Logs scheduled query against the configured threshold and comparison operator to determine its state.

When you create a log alarm, the operation creates a service-managed CloudWatch Logs scheduled query that runs the query string you provide on the schedule you configure. Each scheduled query execution returns one or more aggregated values determined by the AggregationExpression , and each aggregated value is compared against the alarm Threshold to determine the alarm state. The alarm uses M-out-of-N evaluation: if QueryResultsToAlarm out of the most recent QueryResultsToEvaluate query results breach the threshold, the alarm transitions to ALARM .

Log alarms support the alarm states (OK , ALARM , INSUFFICIENT_DATA ). Configure transition actions using OKActions , AlarmActions , and InsufficientDataActions .

If you call this operation with the name of an existing log alarm, the operation replaces the previous configuration of that alarm.

Permissions

To create or update a log alarm, you must have the cloudwatch:PutLogAlarm permission. The IAM role specified in ScheduledQueryRoleARN must grant the CloudWatch Alarms service permission to execute scheduled queries on the specified log groups. If you set ActionLogLineCount , the role specified in ActionLogLineRoleArn must grant permission to retrieve log events for inclusion in alarm notifications.

See also: AWS API Documentation

Synopsis

  put-log-alarm
--alarm-name <value>
[--alarm-description <value>]
--scheduled-query-configuration <value>
[--action-log-line-count <value>]
[--action-log-line-role-arn <value>]
[--actions-enabled | --no-actions-enabled]
[--ok-actions <value>]
[--alarm-actions <value>]
[--insufficient-data-actions <value>]
--query-results-to-evaluate <value>
--query-results-to-alarm <value>
--threshold <value>
--comparison-operator <value>
[--treat-missing-data <value>]
[--tags <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]
[--cli-error-format <value>]

Options

--alarm-name (string) [required]

The name for the alarm. This name must be unique within the Amazon Web Services account and Region.

Constraints:

  • min: 1
  • max: 255

--alarm-description (string)

The description for the alarm.

Constraints:

  • min: 0
  • max: 1024

--scheduled-query-configuration (structure) [required]

The configuration of the underlying CloudWatch Logs scheduled query that this alarm evaluates, including the query string, log groups, schedule, and aggregation expression.

QueryString -> (string) [required]

The CloudWatch Logs query to execute on each scheduled run. Length constraints: maximum of 10,000 characters.

Constraints:

  • min: 0
  • max: 10000

LogGroupIdentifiers -> (list)

The log groups to query. Each entry can be a log group name or ARN. Use the ARN form when querying log groups in a different account (for example, when running cross-account queries from a monitoring account). The list must contain between 1 and 50 entries.

Constraints:

  • min: 1
  • max: 50

(string)

Constraints:

  • min: 1
  • max: 1024

QueryARN -> (string)

The Amazon Resource Name (ARN) of the CloudWatch Logs scheduled query that the alarm uses. This field is populated in DescribeAlarms responses.

Constraints:

  • min: 1
  • max: 1024

ScheduledQueryRoleARN -> (string) [required]

The Amazon Resource Name (ARN) of the IAM role that CloudWatch assumes when executing the scheduled query against the configured log groups.

Constraints:

  • min: 1
  • max: 1024

ScheduleConfiguration -> (structure) [required]

The schedule and time-range offset configuration for the underlying scheduled query.

ScheduleExpression -> (string) [required]

The schedule expression that defines how often the underlying CloudWatch Logs scheduled query runs. Specify a rate() expression, for example rate(5 minutes) .

Constraints:

  • min: 1
  • max: 256

StartTimeOffset -> (long)

The offset, in seconds, before the scheduled execution time at which the query time range begins. For example, an offset of 360 (6 minutes) on a query running at 12:05:00 starts the query time range at 11:59:00.

EndTimeOffset -> (long)

The offset, in seconds, before the scheduled execution time at which the query time range ends. Must be non-negative and less than StartTimeOffset . The default is 0.

AggregationExpression -> (string) [required]

The expression that defines how to aggregate query results into one or more scalar values for alarm evaluation. For example, count(*) or avg(latency) by host | sort desc . Length constraints: minimum 1 character, maximum 2048 characters.

Constraints:

  • min: 1
  • max: 256

Tags -> (list)

A list of key-value pairs to associate with the underlying scheduled query resource.

(structure)

A key-value pair associated with a CloudWatch resource.

Key -> (string) [required]

A string that you can use to assign a value. The combination of tag keys and values can help you organize and categorize your resources.

Constraints:

  • min: 1
  • max: 128

Value -> (string) [required]

The value for the specified tag key.

Constraints:

  • min: 0
  • max: 256

Shorthand Syntax:

QueryString=string,LogGroupIdentifiers=string,string,QueryARN=string,ScheduledQueryRoleARN=string,ScheduleConfiguration={ScheduleExpression=string,StartTimeOffset=long,EndTimeOffset=long},AggregationExpression=string,Tags=[{Key=string,Value=string},{Key=string,Value=string}]

JSON Syntax:

{
  "QueryString": "string",
  "LogGroupIdentifiers": ["string", ...],
  "QueryARN": "string",
  "ScheduledQueryRoleARN": "string",
  "ScheduleConfiguration": {
    "ScheduleExpression": "string",
    "StartTimeOffset": long,
    "EndTimeOffset": long
  },
  "AggregationExpression": "string",
  "Tags": [
    {
      "Key": "string",
      "Value": "string"
    }
    ...
  ]
}

--action-log-line-count (integer)

The number of log lines from the most recent scheduled query execution to include in alarm action notifications. Valid range is 0 through 50. The default is 0, which means no log lines are included.

--action-log-line-role-arn (string)

The Amazon Resource Name (ARN) of an IAM role that CloudWatch assumes to retrieve log events for inclusion in alarm action notifications. Required when ActionLogLineCount is greater than 0.

--actions-enabled | --no-actions-enabled (boolean)

Indicates whether actions should be executed during any changes to the alarm state. The default is true .

--ok-actions (list)

The actions to execute when this alarm transitions to the OK state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Valid Values:

Amazon SNS actions:

``arn:aws:sns:region :account-id :sns-topic-name ``

Lambda actions:

  • Invoke the latest version of a Lambda function: ``arn:aws:lambda:region :account-id :function:function-name ``
  • Invoke a specific version of a Lambda function: ``arn:aws:lambda:region :account-id :function:function-name :version-number ``
  • Invoke a function by using an alias Lambda function: ``arn:aws:lambda:region :account-id :function:function-name :alias-name ``

Constraints:

  • max: 5

(string)

Constraints:

  • min: 1
  • max: 1024

Syntax:

"string" "string" ...

--alarm-actions (list)

The actions to execute when this alarm transitions to the ALARM state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Valid Values:

Amazon SNS actions:

``arn:aws:sns:region :account-id :sns-topic-name ``

Lambda actions:

  • Invoke the latest version of a Lambda function: ``arn:aws:lambda:region :account-id :function:function-name ``
  • Invoke a specific version of a Lambda function: ``arn:aws:lambda:region :account-id :function:function-name :version-number ``
  • Invoke a function by using an alias Lambda function: ``arn:aws:lambda:region :account-id :function:function-name :alias-name ``

Systems Manager actions:

``arn:aws:ssm:region :account-id :opsitem:severity ``

Constraints:

  • max: 5

(string)

Constraints:

  • min: 1
  • max: 1024

Syntax:

"string" "string" ...

--insufficient-data-actions (list)

The actions to execute when this alarm transitions to the INSUFFICIENT_DATA state from any other state. Each action is specified as an Amazon Resource Name (ARN).

Valid Values:

Amazon SNS actions:

``arn:aws:sns:region :account-id :sns-topic-name ``

Lambda actions:

  • Invoke the latest version of a Lambda function: ``arn:aws:lambda:region :account-id :function:function-name ``
  • Invoke a specific version of a Lambda function: ``arn:aws:lambda:region :account-id :function:function-name :version-number ``
  • Invoke a function by using an alias Lambda function: ``arn:aws:lambda:region :account-id :function:function-name :alias-name ``

Constraints:

  • max: 5

(string)

Constraints:

  • min: 1
  • max: 1024

Syntax:

"string" "string" ...

--query-results-to-evaluate (integer) [required]

The number of most recent scheduled query results to evaluate against the threshold (the N in M-of-N evaluation). Valid range is 1 through 100.

Constraints:

  • min: 1

--query-results-to-alarm (integer) [required]

The number of query results, out of the most recent QueryResultsToEvaluate results, that must breach the threshold to trigger the alarm to transition to ALARM (the M in M-of-N evaluation). Must be less than or equal to QueryResultsToEvaluate .

Constraints:

  • min: 1

--threshold (double) [required]

The value to compare with the aggregated query result.

--comparison-operator (string) [required]

The arithmetic operation to use when comparing the aggregated query result and the threshold. The aggregated query result is used as the first operand. Valid values are GreaterThanThreshold , GreaterThanOrEqualToThreshold , LessThanThreshold , and LessThanOrEqualToThreshold .

Possible values:

  • GreaterThanOrEqualToThreshold
  • GreaterThanThreshold
  • LessThanThreshold
  • LessThanOrEqualToThreshold
  • LessThanLowerOrGreaterThanUpperThreshold
  • LessThanLowerThreshold
  • GreaterThanUpperThreshold

--treat-missing-data (string)

Sets how this alarm is to handle missing data points. Valid values are breaching , notBreaching , ignore , and missing . If this parameter is omitted, the default behavior of missing is used.

Constraints:

  • min: 1
  • max: 255

--tags (list)

A list of key-value pairs to associate with the alarm. You can use tags to categorize and manage your alarms.

(structure)

A key-value pair associated with a CloudWatch resource.

Key -> (string) [required]

A string that you can use to assign a value. The combination of tag keys and values can help you organize and categorize your resources.

Constraints:

  • min: 1
  • max: 128

Value -> (string) [required]

The value for the specified tag key.

Constraints:

  • min: 0
  • max: 256

Shorthand Syntax:

Key=string,Value=string ...

JSON Syntax:

[
  {
    "Key": "string",
    "Value": "string"
  }
  ...
]

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally. This may not be specified along with --cli-input-yaml.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command. The generated JSON skeleton is not stable between versions of the AWS CLI and there are no backwards compatibility guarantees in the JSON skeleton generated.

Global Options

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command’s default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

  • json
  • text
  • table
  • yaml
  • yaml-stream
  • off

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

  • on
  • off
  • auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

--cli-binary-format (string)

The formatting style to be used for binary blobs. The default format is base64. The base64 format expects binary blobs to be provided as a base64 encoded string. The raw-in-base64-out format preserves compatibility with AWS CLI V1 behavior and binary values must be passed literally. When providing contents from a file that map to a binary blob fileb:// will always be treated as binary and use the file contents directly regardless of the cli-binary-format setting. When using file:// the file contents will need to properly formatted for the configured cli-binary-format.

  • base64
  • raw-in-base64-out

--no-cli-pager (boolean)

Disable cli pager for output.

--cli-auto-prompt (boolean)

Automatically prompt for CLI input parameters.

--no-cli-auto-prompt (boolean)

Disable automatically prompt for CLI input parameters.

--cli-error-format (string)

The formatting style for error output. By default, errors are displayed in enhanced format.

  • legacy
  • json
  • yaml
  • text
  • table
  • enhanced

Output

None

© Copyright 2026, Amazon Web Services. Created using Sphinx.