CloudWatchOmni / Client / create_alert

create_alert

CloudWatchOmni.Client.create_alert(**kwargs)

Creates a new alert within a space.

Use GetAlert and ListAlerts to retrieve alerts, UpdateAlert to modify one, and DeleteAlert to remove it.

See also: AWS API Documentation

Request Syntax

response = client.create_alert(
    spaceId='string',
    profileId='string',
    name='string',
    description='string',
    rule={
        'telemetryRule': {
            'query': {
                'language': 'SQL'|'PROMQL',
                'expression': 'string'
            },
            'condition': {
                'thresholdMode': 'COUNT_OF_RESULTS'|'FIELD_VALUE',
                'thresholdField': 'string',
                'comparator': 'GT'|'LT'|'GTE'|'LTE',
                'warningThreshold': 123.0,
                'criticalThreshold': 123.0
            },
            'evaluation': {
                'intervalSeconds': 123,
                'pendingDurationSeconds': 123,
                'recoveryDurationSeconds': 123
            },
            'noData': {
                'treatAs': 'OK'|'WARNING'|'CRITICAL'|'NODATA'
            }
        }
    },
    notificationsEnabled=True|False,
    tags={
        'string': 'string'
    },
    notificationRules=[
        {
            'trigger': {
                'stateValues': [
                    'OK'|'WARNING'|'CRITICAL'|'NODATA',
                ]
            },
            'target': {
                'type': 'sns'|'slack'|'pagerduty',
                'arn': 'string',
                'metadata': {
                    'string': 'string'
                }
            }
        },
    ],
    clientToken='string'
)
Parameters:

  • spaceId (string) –

    [REQUIRED]

    The unique ID of the space to create the alert in.

  • profileId (string) –

    [REQUIRED]

    The ID of the access profile the alert uses to evaluate its query and execute notifications. The caller supplies it: there is no managed alert profile, and the service does not pick one on the caller’s behalf.

  • name (string) –

    [REQUIRED]

    Alert name, for display. Max 256 (the AlarmName budget). Not the alert’s identity: the backend mints a separate uuid as the {@link AlertId}, so the name need not be unique within a space and addressing an alert never depends on it. UpdateAlert accepts a new name to rename the alert.

  • description (string) – An optional description of the alert.

  • rule (dict) –

    [REQUIRED]

    The rule that defines how the alert is evaluated.

    Note

    This is a Tagged Union structure. Only one of the following top level keys can be set: telemetryRule.

    • telemetryRule (dict) –

      The telemetry-based rule definition.

      • query (dict) –

        The query expression to evaluate.

        • language (string) – [REQUIRED]

          The query language of the expression.

        • expression (string) – [REQUIRED]

          The query expression to evaluate.

      • condition (dict) –

        The condition that determines when the alert fires.

        • thresholdMode (string) –

          How the threshold is applied to query results.

        • thresholdField (string) –

          The field the threshold is evaluated against.

        • comparator (string) –

          The comparison operator applied to the threshold.

        • warningThreshold (float) –

          The value at which the alert enters the WARNING state.

        • criticalThreshold (float) –

          The value at which the alert enters the CRITICAL state.

      • evaluation (dict) –

        The evaluation cadence and durations.

        • intervalSeconds (integer) – [REQUIRED]

          The interval between evaluations, in seconds.

        • pendingDurationSeconds (integer) –

          The duration a breach must persist before the alert fires, in seconds.

        • recoveryDurationSeconds (integer) –

          The duration a recovery must persist before the alert clears, in seconds.

      • noData (dict) –

        How the alert behaves when a query produces no data.

        • treatAs (string) – [REQUIRED]

          The state to report when an evaluation produces no data.

  • notificationsEnabled (boolean) – Whether actions (notifications) are enabled for this alert. Defaults to true when omitted.

  • tags (dict) –

    The tags to associate with the alert.

    • (string) –

      Tag key. Must be non-empty; AWS-standard maximum length. Constraining the key (rather than a bare String) rejects empty-key payloads at the edge with a 400 ValidationException instead of faulting downstream as a 500.

      • (string) –

        Tag value. AWS-standard maximum length; may be empty.

  • notificationRules (list) –

    The notification rules that determine when and where notifications are sent.

    • (dict) –

      Single notification rule: which transitions trigger this rule and where the resulting notification should be sent.

      • trigger (dict) – [REQUIRED]

        The conditions that trigger this notification rule.

        • stateValues (list) –

          Alert state(s) that trigger this rule. Empty / omitted = any state.

          • (string) –

            Flat alert state. Severity is folded in: a WARNING/CRITICAL alert reports that state directly. {@code NODATA} indicates the evaluation produced no data (subject to the rule’s noData.treatAs handling).

      • target (dict) – [REQUIRED]

        The destination for notifications from this rule.

        • type (string) – [REQUIRED]

          The type of notification target.

        • arn (string) – [REQUIRED]

          The Amazon Resource Name (ARN) of the notification target. For {@code slack} and {@code pagerduty}, an integration ARN as returned by {@code ListIntegrations}.

        • metadata (dict) –

          Additional target-specific metadata.

          • (string) –

            • (string) –

  • clientToken (string) –

    Idempotency token for safe retries. Retrying with the same token within the idempotency window returns the original alert instead of creating a duplicate.

    This field is autopopulated if not provided.

Return type:

dict

Returns:

Response Syntax

{
    'alertArn': 'string',
    'alert': {
        'name': 'string',
        'alertId': 'string',
        'description': 'string',
        'accountId': 'string',
        'spaceId': 'string',
        'profileId': 'string',
        'rule': {
            'telemetryRule': {
                'query': {
                    'language': 'SQL'|'PROMQL',
                    'expression': 'string'
                },
                'condition': {
                    'thresholdMode': 'COUNT_OF_RESULTS'|'FIELD_VALUE',
                    'thresholdField': 'string',
                    'comparator': 'GT'|'LT'|'GTE'|'LTE',
                    'warningThreshold': 123.0,
                    'criticalThreshold': 123.0
                },
                'evaluation': {
                    'intervalSeconds': 123,
                    'pendingDurationSeconds': 123,
                    'recoveryDurationSeconds': 123
                },
                'noData': {
                    'treatAs': 'OK'|'WARNING'|'CRITICAL'|'NODATA'
                }
            }
        },
        'notificationStatus': 'ENABLED'|'DISABLED',
        'state': {
            'value': 'OK'|'WARNING'|'CRITICAL'|'NODATA',
            'transitionedAt': datetime(2015, 1, 1),
            'contributorSummary': {
                'warningCount': 123,
                'criticalCount': 123
            },
            'data': {
                'thresholdBreached': 123.0
            }
        },
        'notificationRules': [
            {
                'trigger': {
                    'stateValues': [
                        'OK'|'WARNING'|'CRITICAL'|'NODATA',
                    ]
                },
                'target': {
                    'type': 'sns'|'slack'|'pagerduty',
                    'arn': 'string',
                    'metadata': {
                        'string': 'string'
                    }
                }
            },
        ],
        'createdAt': datetime(2015, 1, 1),
        'updatedAt': datetime(2015, 1, 1),
        'alertArn': 'string'
    }
}

Response Structure

  • (dict) –

    • alertArn (string) –

      Deprecated. Use alert.alertArn, which carries the same value. Kept so an existing caller keeps working while it moves to alert.

    • alert (dict) –

      The alert that was created. The same Alert shape GetAlert returns, so a caller need not read the alert back to learn its timestamps or its minted alert id.

      {@code alert.state} is absent here — see the state member of Alert. Every other member is populated exactly as GetAlert populates it.

      • name (string) –

        The name of the alert.

      • alertId (string) –

        The stable alert identifier (see {@link AlertId}), minted on create and immutable across updates. Use it (not {@code name}) to address the alert on GetAlert/UpdateAlert/DeleteAlert; it is also the ARN’s resource id.

      • description (string) –

        An optional description of the alert.

      • accountId (string) –

        The AWS account ID that owns the alert.

      • spaceId (string) –

        The ID of the space the alert belongs to.

      • profileId (string) –

        The ID of the access profile associated with the alert.

      • rule (dict) –

        The rule that defines how the alert is evaluated.

        Note

        This is a Tagged Union structure. Only one of the following top level keys will be set: telemetryRule. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:

        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}

        • telemetryRule (dict) –

          The telemetry-based rule definition.

          • query (dict) –

            The query expression to evaluate.

            • language (string) –

              The query language of the expression.

            • expression (string) –

              The query expression to evaluate.

          • condition (dict) –

            The condition that determines when the alert fires.

            • thresholdMode (string) –

              How the threshold is applied to query results.

            • thresholdField (string) –

              The field the threshold is evaluated against.

            • comparator (string) –

              The comparison operator applied to the threshold.

            • warningThreshold (float) –

              The value at which the alert enters the WARNING state.

            • criticalThreshold (float) –

              The value at which the alert enters the CRITICAL state.

          • evaluation (dict) –

            The evaluation cadence and durations.

            • intervalSeconds (integer) –

              The interval between evaluations, in seconds.

            • pendingDurationSeconds (integer) –

              The duration a breach must persist before the alert fires, in seconds.

            • recoveryDurationSeconds (integer) –

              The duration a recovery must persist before the alert clears, in seconds.

          • noData (dict) –

            How the alert behaves when a query produces no data.

            • treatAs (string) –

              The state to report when an evaluation produces no data.

      • notificationStatus (string) –

        Whether notifications are enabled.

      • state (dict) –

        Live evaluation state (read-only, system-managed). Populated by GetAlert. ListAlerts reports state on AlertSummary instead, where it stays required.

        Absent on CreateAlert: a newly created alert has never been evaluated, so any state reported there would be a default rather than an observation. Call GetAlert for live state. Not @required for that reason — GetAlert always populates it.

        contributorSummary is nested inside this member, so it too is absent on CreateAlert.

        • value (string) –

          Current flat state.

        • transitionedAt (datetime) –

          When the alert transitioned to its current state.

        • contributorSummary (dict) –

          Counts of contributors currently breaching each severity threshold. Present only when contributor-level tracking is active; absent until the first contributor breaches a {@code WARNING} or {@code CRITICAL} threshold.

          • warningCount (integer) –

            Number of contributors currently breaching the warning threshold.

          • criticalCount (integer) –

            Number of contributors currently breaching the critical threshold.

        • data (dict) –

          Structured detail about why the alert is in its current state.

          • thresholdBreached (float) –

            For COUNT_OF_RESULTS alerts, the row count that breached; null for FIELD_VALUE (multi-contributor) alerts.

      • notificationRules (list) –

        The notification rules for the alert.

        • (dict) –

          Single notification rule: which transitions trigger this rule and where the resulting notification should be sent.

          • trigger (dict) –

            The conditions that trigger this notification rule.

            • stateValues (list) –

              Alert state(s) that trigger this rule. Empty / omitted = any state.

              • (string) –

                Flat alert state. Severity is folded in: a WARNING/CRITICAL alert reports that state directly. {@code NODATA} indicates the evaluation produced no data (subject to the rule’s noData.treatAs handling).

          • target (dict) –

            The destination for notifications from this rule.

            • type (string) –

              The type of notification target.

            • arn (string) –

              The Amazon Resource Name (ARN) of the notification target. For {@code slack} and {@code pagerduty}, an integration ARN as returned by {@code ListIntegrations}.

            • metadata (dict) –

              Additional target-specific metadata.

              • (string) –

                • (string) –

      • createdAt (datetime) –

        The timestamp when the alert was created.

      • updatedAt (datetime) –

        The timestamp when the alert was last updated.

      • alertArn (string) –

        The Amazon Resource Name (ARN) of the alert.

Exceptions