Amazon CloudWatch Internet Monitor

2023/11/17 - Amazon CloudWatch Internet Monitor - 4 new api methods

Changes  Adds new querying capabilities for running data queries on a monitor

StartQuery (new) Link ¶

Start a query to return data for a specific query type for the Amazon CloudWatch Internet Monitor query interface. Specify a time period for the data that you want returned by using StartTime and EndTime . You filter the query results to return by providing parameters that you specify with FilterParameters .

For more information about using the query interface, including examples, see Using the Amazon CloudWatch Internet Monitor query interface in the Amazon CloudWatch Internet Monitor User Guide.

See also: AWS API Documentation

Request Syntax

client.start_query(
    MonitorName='string',
    StartTime=datetime(2015, 1, 1),
    EndTime=datetime(2015, 1, 1),
    QueryType='MEASUREMENTS'|'TOP_LOCATIONS'|'TOP_LOCATION_DETAILS',
    FilterParameters=[
        {
            'Field': 'string',
            'Operator': 'EQUALS'|'NOT_EQUALS',
            'Values': [
                'string',
            ]
        },
    ]
)
type MonitorName

string

param MonitorName

[REQUIRED]

The name of the monitor to query.

type StartTime

datetime

param StartTime

[REQUIRED]

The timestamp that is the beginning of the period that you want to retrieve data for with your query.

type EndTime

datetime

param EndTime

[REQUIRED]

The timestamp that is the end of the period that you want to retrieve data for with your query.

type QueryType

string

param QueryType

[REQUIRED]

The type of query to run. The following are the three types of queries that you can run using the Internet Monitor query interface:

  • MEASUREMENTS : TBD definition

  • TOP_LOCATIONS : TBD definition

  • TOP_LOCATION_DETAILS : TBD definition

For lists of the fields returned with each query type and more information about how each type of query is performed, see Using the Amazon CloudWatch Internet Monitor query interface in the Amazon CloudWatch Internet Monitor User Guide.

type FilterParameters

list

param FilterParameters

The FilterParameters field that you use with Amazon CloudWatch Internet Monitor queries is a string the defines how you want a query to be filtered. The filter parameters that you can specify depend on the query type, since each query type returns a different set of Internet Monitor data.

For more information about specifying filter parameters, see Using the Amazon CloudWatch Internet Monitor query interface in the Amazon CloudWatch Internet Monitor User Guide.

  • (dict) --

    A filter that you use with the results of a Amazon CloudWatch Internet Monitor query that you created and ran. The query sets up a repository of data that is a subset of your application's Internet Monitor data. FilterParameter is a string that defines how you want to filter the repository of data to return a set of results, based on your criteria.

    The filter parameters that you can specify depend on the query type that you used to create the repository, since each query type returns a different set of Internet Monitor data.

    For each filter, you specify a field (such as city ), an operator (such as not_equals , and a value or array of values (such as ["Seattle", "Redmond"] ). Separate values in the array with commas.

    For more information about specifying filter parameters, see Using the Amazon CloudWatch Internet Monitor query interface in the Amazon CloudWatch Internet Monitor User Guide.

    • Field (string) --

      A data field that you want to filter, to further scope your application's Internet Monitor data in a repository that you created by running a query. A field might be city , for example. The field must be one of the fields that was returned by the specific query that you used to create the repository.

    • Operator (string) --

      The operator to use with the filter field and a value, such as not_equals .

    • Values (list) --

      One or more values to be used, together with the specified operator, to filter data for a query. For example, you could specify an array of values such as ["Seattle", "Redmond"] . Values in the array are separated by commas.

      • (string) --

rtype

dict

returns

Response Syntax

{
    'QueryId': 'string'
}

Response Structure

  • (dict) --

    • QueryId (string) --

      The internally-generated identifier of a specific query.

StopQuery (new) Link ¶

Stop a query that is progress for a specific monitor.

See also: AWS API Documentation

Request Syntax

client.stop_query(
    MonitorName='string',
    QueryId='string'
)
type MonitorName

string

param MonitorName

[REQUIRED]

The name of the monitor.

type QueryId

string

param QueryId

[REQUIRED]

The ID of the query that you want to stop. A QueryId is an internally-generated identifier for a specific query.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

GetQueryResults (new) Link ¶

Return the data for a query with the Amazon CloudWatch Internet Monitor query interface. Specify the query that you want to return results for by providing a QueryId and a monitor name.

For more information about using the query interface, including examples, see Using the Amazon CloudWatch Internet Monitor query interface in the Amazon CloudWatch Internet Monitor User Guide.

See also: AWS API Documentation

Request Syntax

client.get_query_results(
    MonitorName='string',
    QueryId='string',
    NextToken='string',
    MaxResults=123
)
type MonitorName

string

param MonitorName

[REQUIRED]

The name of the monitor to return data for.

type QueryId

string

param QueryId

[REQUIRED]

The ID of the query that you want to return data results for. A QueryId is an internally-generated identifier for a specific query.

type NextToken

string

param NextToken

The token for the next set of results. You receive this token from a previous call.

type MaxResults

integer

param MaxResults

The number of query results that you want to return with this call.

rtype

dict

returns

Response Syntax

{
    'Fields': [
        {
            'Name': 'string',
            'Type': 'string'
        },
    ],
    'Data': [
        [
            'string',
        ],
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Fields (list) --

      The fields that the query returns data for. Fields are name-data type pairs, such as availability_score -float .

      • (dict) --

        Defines a field to query for your application's Amazon CloudWatch Internet Monitor data. You create a data repository by running a query of a specific type. Each QueryType includes a specific set of fields and datatypes to retrieve data for.

        • Name (string) --

          The name of a field to query your application's Amazon CloudWatch Internet Monitor data for, such as availability_score .

        • Type (string) --

          The data type for a query field, which must correspond to the field you're defining for QueryField . For example, if the query field name is availability_score , the data type is float .

    • Data (list) --

      The data results that the query returns. Data is returned in arrays, aligned with the Fields for the query, which creates a repository of Amazon CloudWatch Internet Monitor information for your application. Then, you can filter the information in the repository by using FilterParameters that you define.

      • (list) --

        • (string) --

    • NextToken (string) --

      The token for the next set of results. You receive this token from a previous call.

GetQueryStatus (new) Link ¶

Returns the current status of a query for the Amazon CloudWatch Internet Monitor query interface, for a specified query ID and monitor. When you run a query, check the status to make sure that the query has SUCCEEDED before you review the results.

  • QUEUED : The query is scheduled to run.

  • RUNNING : The query is in progress but not complete.

  • SUCCEEDED : The query completed sucessfully.

  • FAILED : The query failed due to an error.

  • CANCELED : The query was canceled.

See also: AWS API Documentation

Request Syntax

client.get_query_status(
    MonitorName='string',
    QueryId='string'
)
type MonitorName

string

param MonitorName

[REQUIRED]

The name of the monitor.

type QueryId

string

param QueryId

[REQUIRED]

The ID of the query that you want to return the status for. A QueryId is an internally-generated dentifier for a specific query.

rtype

dict

returns

Response Syntax

{
    'Status': 'QUEUED'|'RUNNING'|'SUCCEEDED'|'FAILED'|'CANCELED'
}

Response Structure

  • (dict) --

    • Status (string) --

      The current status for a query.