Amazon CloudWatch Logs

{'destinationConfiguration': {'s3Configuration': {'kmsKeyId': 'string',
                                                  'ownerAccountId': 'string'}}}

Creates a scheduled query that runs CloudWatch Logs Insights queries at regular intervals. Scheduled queries enable proactive monitoring by automatically executing queries to detect patterns and anomalies in your log data. Query results can be delivered to Amazon S3 for analysis or further processing.

See also: AWS API Documentation

Request Syntax

client.create_scheduled_query(
    name='string',
    description='string',
    queryLanguage='CWLI'|'SQL'|'PPL',
    queryString='string',
    logGroupIdentifiers=[
        'string',
    ],
    scheduleExpression='string',
    timezone='string',
    startTimeOffset=123,
    destinationConfiguration={
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string',
            'ownerAccountId': 'string',
            'kmsKeyId': 'string'
        }
    },
    scheduleStartTime=123,
    scheduleEndTime=123,
    executionRoleArn='string',
    state='ENABLED'|'DISABLED',
    tags={
        'string': 'string'
    }
)

type name:

string

param name:

[REQUIRED]

The name of the scheduled query. The name must be unique within your account and region. Valid characters are alphanumeric characters, hyphens, underscores, and periods. Length must be between 1 and 255 characters.

type description:

string

param description:

An optional description for the scheduled query to help identify its purpose and functionality.

type queryLanguage:

string

param queryLanguage:

[REQUIRED]

The query language to use for the scheduled query. Valid values are CWLI, PPL, and SQL.

type queryString:

string

param queryString:

[REQUIRED]

The query string to execute. This is the same query syntax used in CloudWatch Logs Insights. Maximum length is 10,000 characters.

type logGroupIdentifiers:

list

param logGroupIdentifiers:

An array of log group names or ARNs to query. You can specify between 1 and 50 log groups. Log groups can be identified by name or full ARN.

• (string) --

type scheduleExpression:

string

param scheduleExpression:

[REQUIRED]

A cron expression that defines when the scheduled query runs. The expression uses standard cron syntax and supports minute-level precision. Maximum length is 256 characters.

type timezone:

string

param timezone:

The timezone for evaluating the schedule expression. This determines when the scheduled query executes relative to the specified timezone.

type startTimeOffset:

integer

param startTimeOffset:

The time offset in seconds that defines the lookback period for the query. This determines how far back in time the query searches from the execution time.

type destinationConfiguration:

dict

param destinationConfiguration:

Configuration for where to deliver query results. Currently supports Amazon S3 destinations for storing query output.

• s3Configuration (dict) -- [REQUIRED]

  Configuration for delivering query results to Amazon S3.

  • destinationIdentifier (string) -- [REQUIRED]

    The Amazon S3 URI where query results are delivered. Must be a valid S3 URI format.

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that grants permissions to write query results to the specified Amazon S3 destination.

  • ownerAccountId (string) --

    The AWS accountId for the bucket owning account.

  • kmsKeyId (string) --

    The Amazon Resource Name (ARN) of the KMS encryption key. Must belong to the same AWS Region as the destination Amazon S3 bucket.

type scheduleStartTime:

integer

param scheduleStartTime:

The start time for the scheduled query in Unix epoch format. The query will not execute before this time.

type scheduleEndTime:

integer

param scheduleEndTime:

The end time for the scheduled query in Unix epoch format. The query will stop executing after this time.

type executionRoleArn:

string

param executionRoleArn:

[REQUIRED]

The ARN of the IAM role that grants permissions to execute the query and deliver results to the specified destination. The role must have permissions to read from the specified log groups and write to the destination.

type state:

string

param state:

The initial state of the scheduled query. Valid values are ENABLED and DISABLED. Default is ENABLED.

type tags:

dict

param tags:

Key-value pairs to associate with the scheduled query for resource management and cost allocation.

• (string) --

  • (string) --

rtype:

dict

returns:

Response Syntax

{
    'scheduledQueryArn': 'string',
    'state': 'ENABLED'|'DISABLED'
}

Response Structure

• (dict) --

  • scheduledQueryArn (string) --

    The ARN of the created scheduled query.

  • state (string) --

    The current state of the scheduled query.

{'queryDefinitions': {'parameters': [{'defaultValue': 'string',
                                      'description': 'string',
                                      'name': 'string'}]}}

This operation returns a paginated list of your saved CloudWatch Logs Insights query definitions. You can retrieve query definitions from the current account or from a source account that is linked to the current account.

You can use the queryDefinitionNamePrefix parameter to limit the results to only the query definitions that have names that start with a certain string.

See also: AWS API Documentation

Request Syntax

client.describe_query_definitions(
    queryLanguage='CWLI'|'SQL'|'PPL',
    queryDefinitionNamePrefix='string',
    maxResults=123,
    nextToken='string'
)

type queryLanguage:

string

param queryLanguage:

The query language used for this query. For more information about the query languages that CloudWatch Logs supports, see Supported query languages.

type queryDefinitionNamePrefix:

string

param queryDefinitionNamePrefix:

Use this parameter to filter your results to only the query definitions that have names that start with the prefix you specify.

type maxResults:

integer

param maxResults:

Limits the number of returned query definitions to the specified number.

type nextToken:

string

param nextToken:

The token for the next set of items to return. The token expires after 24 hours.

rtype:

dict

returns:

Response Syntax

{
    'queryDefinitions': [
        {
            'queryLanguage': 'CWLI'|'SQL'|'PPL',
            'queryDefinitionId': 'string',
            'name': 'string',
            'queryString': 'string',
            'lastModified': 123,
            'logGroupNames': [
                'string',
            ],
            'parameters': [
                {
                    'name': 'string',
                    'defaultValue': 'string',
                    'description': 'string'
                },
            ]
        },
    ],
    'nextToken': 'string'
}

Response Structure

• (dict) --

  • queryDefinitions (list) --

    The list of query definitions that match your request.

    • (dict) --

      This structure contains details about a saved CloudWatch Logs Insights query definition.

      • queryLanguage (string) --

        The query language used for this query. For more information about the query languages that CloudWatch Logs supports, see Supported query languages.

      • queryDefinitionId (string) --

        The unique ID of the query definition.

      • name (string) --

        The name of the query definition.

      • queryString (string) --

        The query string to use for this definition. For more information, see CloudWatch Logs Insights Query Syntax.

      • lastModified (integer) --

        The date that the query definition was most recently modified.

      • logGroupNames (list) --

        If this query definition contains a list of log groups that it is limited to, that list appears here.

        • (string) --

      • parameters (list) --

        If this query definition contains a list of query parameters that define placeholder variables for the query string, that list appears here.

        • (dict) --

          This structure defines a query parameter for a saved CloudWatch Logs Insights query definition. Query parameters are supported only for Logs Insights QL queries. They are placeholder variables that you can reference in a query string using the {{parameterName}} syntax. Each parameter can include a default value and a description.

          • name (string) --

            The name of the query parameter. A query parameter name must start with a letter or underscore, and contain only letters, digits, and underscores.

          • defaultValue (string) --

            The default value to use for this query parameter if no value is supplied at execution time.

          • description (string) --

            A description of the query parameter that explains its purpose or expected values.

  • nextToken (string) --

    The token for the next set of items to return. The token expires after 24 hours.

{'destinationConfiguration': {'s3Configuration': {'kmsKeyId': 'string',
                                                  'ownerAccountId': 'string'}}}

Retrieves details about a specific scheduled query, including its configuration, execution status, and metadata.

See also: AWS API Documentation

Request Syntax

client.get_scheduled_query(
    identifier='string'
)

type identifier:

string

param identifier:

[REQUIRED]

The ARN or name of the scheduled query to retrieve.

rtype:

dict

returns:

Response Syntax

{
    'scheduledQueryArn': 'string',
    'name': 'string',
    'description': 'string',
    'queryLanguage': 'CWLI'|'SQL'|'PPL',
    'queryString': 'string',
    'logGroupIdentifiers': [
        'string',
    ],
    'scheduleExpression': 'string',
    'timezone': 'string',
    'startTimeOffset': 123,
    'destinationConfiguration': {
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string',
            'ownerAccountId': 'string',
            'kmsKeyId': 'string'
        }
    },
    'state': 'ENABLED'|'DISABLED',
    'lastTriggeredTime': 123,
    'lastExecutionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
    'scheduleStartTime': 123,
    'scheduleEndTime': 123,
    'executionRoleArn': 'string',
    'creationTime': 123,
    'lastUpdatedTime': 123
}

Response Structure

• (dict) --

  • scheduledQueryArn (string) --

    The ARN of the scheduled query.

  • name (string) --

    The name of the scheduled query.

  • description (string) --

    The description of the scheduled query.

  • queryLanguage (string) --

    The query language used by the scheduled query.

  • queryString (string) --

    The query string executed by the scheduled query.

  • logGroupIdentifiers (list) --

    The log groups queried by the scheduled query.

    • (string) --

  • scheduleExpression (string) --

    The cron expression that defines when the scheduled query runs.

  • timezone (string) --

    The timezone used for evaluating the schedule expression.

  • startTimeOffset (integer) --

    The time offset in seconds that defines the lookback period for the query.

  • destinationConfiguration (dict) --

    Configuration for where query results are delivered.

    • s3Configuration (dict) --

      Configuration for delivering query results to Amazon S3.

      • destinationIdentifier (string) --

        The Amazon S3 URI where query results are delivered. Must be a valid S3 URI format.

      • roleArn (string) --

        The ARN of the IAM role that grants permissions to write query results to the specified Amazon S3 destination.

      • ownerAccountId (string) --

        The AWS accountId for the bucket owning account.

      • kmsKeyId (string) --

        The Amazon Resource Name (ARN) of the KMS encryption key. Must belong to the same AWS Region as the destination Amazon S3 bucket.

  • state (string) --

    The current state of the scheduled query.

  • lastTriggeredTime (integer) --

    The timestamp when the scheduled query was last executed.

  • lastExecutionStatus (string) --

    The status of the most recent execution of the scheduled query.

  • scheduleStartTime (integer) --

    The start time for the scheduled query in Unix epoch format.

  • scheduleEndTime (integer) --

    The end time for the scheduled query in Unix epoch format.

  • executionRoleArn (string) --

    The ARN of the IAM role used to execute the query and deliver results.

  • creationTime (integer) --

    The timestamp when the scheduled query was created.

  • lastUpdatedTime (integer) --

    The timestamp when the scheduled query was last updated.

{'scheduledQueries': {'destinationConfiguration': {'s3Configuration': {'kmsKeyId': 'string',
                                                                       'ownerAccountId': 'string'}}}}

Lists all scheduled queries in your account and region. You can filter results by state to show only enabled or disabled queries.

See also: AWS API Documentation

Request Syntax

client.list_scheduled_queries(
    maxResults=123,
    nextToken='string',
    state='ENABLED'|'DISABLED'
)

type maxResults:

integer

param maxResults:

The maximum number of scheduled queries to return. Valid range is 1 to 1000.

type nextToken:

string

param nextToken:

The token for the next set of items to return. The token expires after 24 hours.

type state:

string

param state:

Filter scheduled queries by state. Valid values are ENABLED and DISABLED. If not specified, all scheduled queries are returned.

rtype:

dict

returns:

Response Syntax

{
    'nextToken': 'string',
    'scheduledQueries': [
        {
            'scheduledQueryArn': 'string',
            'name': 'string',
            'state': 'ENABLED'|'DISABLED',
            'lastTriggeredTime': 123,
            'lastExecutionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
            'scheduleExpression': 'string',
            'timezone': 'string',
            'destinationConfiguration': {
                's3Configuration': {
                    'destinationIdentifier': 'string',
                    'roleArn': 'string',
                    'ownerAccountId': 'string',
                    'kmsKeyId': 'string'
                }
            },
            'creationTime': 123,
            'lastUpdatedTime': 123
        },
    ]
}

Response Structure

• (dict) --

  • nextToken (string) --

    The token for the next set of items to return. The token expires after 24 hours.

  • scheduledQueries (list) --

    An array of scheduled query summary information.

    • (dict) --

      Summary information about a scheduled query, including basic configuration and execution status.

      • scheduledQueryArn (string) --

        The ARN of the scheduled query.

      • name (string) --

        The name of the scheduled query.

      • state (string) --

        The current state of the scheduled query.

      • lastTriggeredTime (integer) --

        The timestamp when the scheduled query was last executed.

      • lastExecutionStatus (string) --

        The status of the most recent execution.

      • scheduleExpression (string) --

        The cron expression that defines when the scheduled query runs.

      • timezone (string) --

        The timezone used for evaluating the schedule expression.

      • destinationConfiguration (dict) --

        Configuration for where query results are delivered.

        • s3Configuration (dict) --

          Configuration for delivering query results to Amazon S3.

          • destinationIdentifier (string) --

            The Amazon S3 URI where query results are delivered. Must be a valid S3 URI format.

          • roleArn (string) --

            The ARN of the IAM role that grants permissions to write query results to the specified Amazon S3 destination.

          • ownerAccountId (string) --

            The AWS accountId for the bucket owning account.

          • kmsKeyId (string) --

            The Amazon Resource Name (ARN) of the KMS encryption key. Must belong to the same AWS Region as the destination Amazon S3 bucket.

      • creationTime (integer) --

        The timestamp when the scheduled query was created.

      • lastUpdatedTime (integer) --

        The timestamp when the scheduled query was last updated.

{'parameters': [{'defaultValue': 'string',
                 'description': 'string',
                 'name': 'string'}]}

Creates or updates a query definition for CloudWatch Logs Insights. For more information, see Analyzing Log Data with CloudWatch Logs Insights.

To update a query definition, specify its queryDefinitionId in your request. The values of name, queryString, and logGroupNames are changed to the values that you specify in your update operation. No current values are retained from the current query definition. For example, imagine updating a current query definition that includes log groups. If you don't specify the logGroupNames parameter in your update operation, the query definition changes to contain no log groups.

You must have the logs:PutQueryDefinition permission to be able to perform this operation.

See also: AWS API Documentation

Request Syntax

client.put_query_definition(
    queryLanguage='CWLI'|'SQL'|'PPL',
    name='string',
    queryDefinitionId='string',
    logGroupNames=[
        'string',
    ],
    queryString='string',
    clientToken='string',
    parameters=[
        {
            'name': 'string',
            'defaultValue': 'string',
            'description': 'string'
        },
    ]
)

type queryLanguage:

string

param queryLanguage:

Specify the query language to use for this query. The options are Logs Insights QL, OpenSearch PPL, and OpenSearch SQL. For more information about the query languages that CloudWatch Logs supports, see Supported query languages.

type name:

string

param name:

[REQUIRED]

A name for the query definition. If you are saving numerous query definitions, we recommend that you name them. This way, you can find the ones you want by using the first part of the name as a filter in the queryDefinitionNamePrefix parameter of DescribeQueryDefinitions.

type queryDefinitionId:

string

param queryDefinitionId:

If you are updating a query definition, use this parameter to specify the ID of the query definition that you want to update. You can use DescribeQueryDefinitions to retrieve the IDs of your saved query definitions.

If you are creating a query definition, do not specify this parameter. CloudWatch generates a unique ID for the new query definition and include it in the response to this operation.

type logGroupNames:

list

param logGroupNames:

Use this parameter to include specific log groups as part of your query definition. If your query uses the OpenSearch Service query language, you specify the log group names inside the querystring instead of here.

If you are updating an existing query definition for the Logs Insights QL or OpenSearch Service PPL and you omit this parameter, then the updated definition will contain no log groups.

• (string) --

type queryString:

string

param queryString:

[REQUIRED]

The query string to use for this definition. For more information, see CloudWatch Logs Insights Query Syntax.

type clientToken:

string

param clientToken:

Used as an idempotency token, to avoid returning an exception if the service receives the same request twice because of a network error.

This field is autopopulated if not provided.

type parameters:

list

param parameters:

Use this parameter to include specific query parameters as part of your query definition. Query parameters are supported only for Logs Insights QL queries. Query parameters allow you to use placeholder variables in your query string that are substituted with values at execution time. Use the {{parameterName}} syntax in your query string to reference a parameter.

• (dict) --

  This structure defines a query parameter for a saved CloudWatch Logs Insights query definition. Query parameters are supported only for Logs Insights QL queries. They are placeholder variables that you can reference in a query string using the {{parameterName}} syntax. Each parameter can include a default value and a description.

  • name (string) -- [REQUIRED]

    The name of the query parameter. A query parameter name must start with a letter or underscore, and contain only letters, digits, and underscores.

  • defaultValue (string) --

    The default value to use for this query parameter if no value is supplied at execution time.

  • description (string) --

    A description of the query parameter that explains its purpose or expected values.

rtype:

dict

returns:

Response Syntax

{
    'queryDefinitionId': 'string'
}

Response Structure

• (dict) --

  • queryDefinitionId (string) --

    The ID of the query definition.

{'destinationConfiguration': {'s3Configuration': {'kmsKeyId': 'string',
                                                  'ownerAccountId': 'string'}}}

Updates an existing scheduled query with new configuration. This operation uses PUT semantics, allowing modification of query parameters, schedule, and destinations.

See also: AWS API Documentation

Request Syntax

client.update_scheduled_query(
    identifier='string',
    description='string',
    queryLanguage='CWLI'|'SQL'|'PPL',
    queryString='string',
    logGroupIdentifiers=[
        'string',
    ],
    scheduleExpression='string',
    timezone='string',
    startTimeOffset=123,
    destinationConfiguration={
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string',
            'ownerAccountId': 'string',
            'kmsKeyId': 'string'
        }
    },
    scheduleStartTime=123,
    scheduleEndTime=123,
    executionRoleArn='string',
    state='ENABLED'|'DISABLED'
)

type identifier:

string

param identifier:

[REQUIRED]

The ARN or name of the scheduled query to update.

type description:

string

param description:

An updated description for the scheduled query.

type queryLanguage:

string

param queryLanguage:

[REQUIRED]

The updated query language for the scheduled query.

type queryString:

string

param queryString:

[REQUIRED]

The updated query string to execute.

type logGroupIdentifiers:

list

param logGroupIdentifiers:

The updated array of log group names or ARNs to query.

• (string) --

type scheduleExpression:

string

param scheduleExpression:

[REQUIRED]

The updated cron expression that defines when the scheduled query runs.

type timezone:

string

param timezone:

The updated timezone for evaluating the schedule expression.

type startTimeOffset:

integer

param startTimeOffset:

The updated time offset in seconds that defines the lookback period for the query.

type destinationConfiguration:

dict

param destinationConfiguration:

The updated configuration for where to deliver query results.

• s3Configuration (dict) -- [REQUIRED]

  Configuration for delivering query results to Amazon S3.

  • destinationIdentifier (string) -- [REQUIRED]

    The Amazon S3 URI where query results are delivered. Must be a valid S3 URI format.

  • roleArn (string) -- [REQUIRED]

    The ARN of the IAM role that grants permissions to write query results to the specified Amazon S3 destination.

  • ownerAccountId (string) --

    The AWS accountId for the bucket owning account.

  • kmsKeyId (string) --

    The Amazon Resource Name (ARN) of the KMS encryption key. Must belong to the same AWS Region as the destination Amazon S3 bucket.

type scheduleStartTime:

integer

param scheduleStartTime:

The updated start time for the scheduled query in Unix epoch format.

type scheduleEndTime:

integer

param scheduleEndTime:

The updated end time for the scheduled query in Unix epoch format.

type executionRoleArn:

string

param executionRoleArn:

[REQUIRED]

The updated ARN of the IAM role that grants permissions to execute the query and deliver results.

type state:

string

param state:

The updated state of the scheduled query.

rtype:

dict

returns:

Response Syntax

{
    'scheduledQueryArn': 'string',
    'name': 'string',
    'description': 'string',
    'queryLanguage': 'CWLI'|'SQL'|'PPL',
    'queryString': 'string',
    'logGroupIdentifiers': [
        'string',
    ],
    'scheduleExpression': 'string',
    'timezone': 'string',
    'startTimeOffset': 123,
    'destinationConfiguration': {
        's3Configuration': {
            'destinationIdentifier': 'string',
            'roleArn': 'string',
            'ownerAccountId': 'string',
            'kmsKeyId': 'string'
        }
    },
    'state': 'ENABLED'|'DISABLED',
    'lastTriggeredTime': 123,
    'lastExecutionStatus': 'Running'|'InvalidQuery'|'Complete'|'Failed'|'Timeout',
    'scheduleStartTime': 123,
    'scheduleEndTime': 123,
    'executionRoleArn': 'string',
    'creationTime': 123,
    'lastUpdatedTime': 123
}

Response Structure

• (dict) --

  • scheduledQueryArn (string) --

    The ARN of the updated scheduled query.

  • name (string) --

    The name of the updated scheduled query.

  • description (string) --

    The description of the updated scheduled query.

  • queryLanguage (string) --

    The query language of the updated scheduled query.

  • queryString (string) --

    The query string of the updated scheduled query.

  • logGroupIdentifiers (list) --

    The log groups queried by the updated scheduled query.

    • (string) --

  • scheduleExpression (string) --

    The cron expression of the updated scheduled query.

  • timezone (string) --

    The timezone of the updated scheduled query.

  • startTimeOffset (integer) --

    The time offset of the updated scheduled query.

  • destinationConfiguration (dict) --

    The destination configuration of the updated scheduled query.

    • s3Configuration (dict) --

      Configuration for delivering query results to Amazon S3.

      • destinationIdentifier (string) --

        The Amazon S3 URI where query results are delivered. Must be a valid S3 URI format.

      • roleArn (string) --

        The ARN of the IAM role that grants permissions to write query results to the specified Amazon S3 destination.

      • ownerAccountId (string) --

        The AWS accountId for the bucket owning account.

      • kmsKeyId (string) --

        The Amazon Resource Name (ARN) of the KMS encryption key. Must belong to the same AWS Region as the destination Amazon S3 bucket.

  • state (string) --

    The state of the updated scheduled query.

  • lastTriggeredTime (integer) --

    The timestamp when the updated scheduled query was last executed.

  • lastExecutionStatus (string) --

    The status of the most recent execution of the updated scheduled query.

  • scheduleStartTime (integer) --

    The start time of the updated scheduled query.

  • scheduleEndTime (integer) --

    The end time of the updated scheduled query.

  • executionRoleArn (string) --

    The execution role ARN of the updated scheduled query.

  • creationTime (integer) --

    The timestamp when the scheduled query was originally created.

  • lastUpdatedTime (integer) --

    The timestamp when the scheduled query was last updated.