monitors

Creates, updates, deletes, gets or lists a monitors resource.

Overview

Name	`monitors`
Type	Resource
Id	`aws.internetmonitor.monitors`

Fields

The following fields are returned by SELECT queries:

get_monitor
list_monitors

Name	Datatype	Description
`created_at`	`string (date-time)`	The time when the monitor was created.
`health_events_config`	`object`	A complex type with the configuration information that determines the threshold and other conditions for when Internet Monitor creates a health event for an overall performance or availability issue, across an application's geographies. Defines the percentages, for overall performance scores and availability scores for an application, that are the thresholds for when Amazon CloudWatch Internet Monitor creates a health event. You can override the defaults to set a custom threshold for overall performance or availability scores, or both. You can also set thresholds for local health scores,, where Internet Monitor creates a health event when scores cross a threshold for one or more city-networks, in addition to creating an event when an overall score crosses a threshold. If you don't set a health event threshold, the default value is 95%. For local thresholds, you also set a minimum percentage of overall traffic that is impacted by an issue before Internet Monitor creates an event. In addition, you can disable local thresholds, for performance scores, availability scores, or both. For more information, see Change health event thresholds in the Internet Monitor section of the CloudWatch User Guide.
`internet_measurements_log_delivery`	`object`	Publish internet measurements to an Amazon S3 bucket in addition to CloudWatch Logs.
`max_city_networks_to_monitor`	`integer`	The maximum number of city-networks to monitor for your resources. A city-network is the location (city) where clients access your application resources from and the ASN or network provider, such as an internet service provider (ISP), that clients access the resources through. This limit can help control billing costs. To learn more, see Choosing a city-network maximum value in the Amazon CloudWatch Internet Monitor section of the CloudWatch User Guide.
`modified_at`	`string (date-time)`	The last time that the monitor was modified.
`monitor_arn`	`string`	The Amazon Resource Name (ARN) of the monitor. (pattern: <code>arn:.*</code>)
`monitor_name`	`string`	The name of the monitor. (pattern: <code>[a-zA-Z0-9_.-]+</code>)
`processing_status`	`string`	The health of the data processing for the monitor. (OK, INACTIVE, COLLECTING_DATA, INSUFFICIENT_DATA, FAULT_SERVICE, FAULT_ACCESS_CLOUDWATCH)
`processing_status_info`	`string`	Additional information about the health of the data processing for the monitor.
`resources`	`array`	The resources monitored by the monitor. Resources are listed by their Amazon Resource Names (ARNs).
`status`	`string`	The status of the monitor. (PENDING, ACTIVE, INACTIVE, ERROR)
`tags`	`object`	The tags that have been added to monitor.
`traffic_percentage_to_monitor`	`integer`	The percentage of the internet-facing traffic for your application to monitor with this monitor. If you set a city-networks maximum, that limit overrides the traffic percentage that you set. To learn more, see Choosing an application traffic percentage to monitor in the Amazon CloudWatch Internet Monitor section of the CloudWatch User Guide.

Name	Datatype	Description
`monitor_arn`	`string`	The Amazon Resource Name (ARN) of the monitor. (pattern: <code>arn:.*</code>)
`monitor_name`	`string`	The name of the monitor. (pattern: <code>[a-zA-Z0-9_.-]+</code>)
`processing_status`	`string`	The health of data processing for the monitor. (OK, INACTIVE, COLLECTING_DATA, INSUFFICIENT_DATA, FAULT_SERVICE, FAULT_ACCESS_CLOUDWATCH)
`status`	`string`	The status of a monitor. (PENDING, ACTIVE, INACTIVE, ERROR)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get_monitor`	`select`	`monitor_name`, `region`	`LinkedAccountId`	Gets information about a monitor in Amazon CloudWatch Internet Monitor based on a monitor name. The information returned includes the Amazon Resource Name (ARN), create time, modified time, resources included in the monitor, and status information.
`list_monitors`	`select`	`region`	`NextToken`, `MaxResults`, `MonitorStatus`, `IncludeLinkedAccounts`	Lists all of your monitors for Amazon CloudWatch Internet Monitor and their statuses, along with the Amazon Resource Name (ARN) and name of each monitor.
`create_monitor`	`insert`	`region`, `MonitorName`		Creates a monitor in Amazon CloudWatch Internet Monitor. A monitor is built based on information from the application resources that you add: VPCs, Network Load Balancers (NLBs), Amazon CloudFront distributions, and Amazon WorkSpaces directories. Internet Monitor then publishes internet measurements from Amazon Web Services that are specific to the city-networks. That is, the locations and ASNs (typically internet service providers or ISPs), where clients access your application. For more information, see Using Amazon CloudWatch Internet Monitor in the Amazon CloudWatch User Guide. When you create a monitor, you choose the percentage of traffic that you want to monitor. You can also set a maximum limit for the number of city-networks where client traffic is monitored, that caps the total traffic that Internet Monitor monitors. A city-network maximum is the limit of city-networks, but you only pay for the number of city-networks that are actually monitored. You can update your monitor at any time to change the percentage of traffic to monitor or the city-networks maximum. For more information, see Choosing a city-network maximum value in the Amazon CloudWatch User Guide.
`update_monitor`	`update`	`monitor_name`, `region`		Updates a monitor. You can update a monitor to change the percentage of traffic to monitor or the maximum number of city-networks (locations and ASNs), to add or remove resources, or to change the status of the monitor. Note that you can't change the name of a monitor. The city-network maximum that you choose is the limit, but you only pay for the number of city-networks that are actually monitored. For more information, see Choosing a city-network maximum value in the Amazon CloudWatch User Guide.
`delete_monitor`	`delete`	`monitor_name`, `region`		Deletes a monitor in Amazon CloudWatch Internet Monitor.
`start_query`	`exec`	`monitor_name`, `region`, `StartTime`, `EndTime`, `QueryType`		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.
`stop_query`	`exec`	`monitor_name`, `query_id`, `region`		Stop a query that is progress for a specific monitor.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`monitor_name`	`string`	The name of the monitor.
`query_id`	`string`	The ID of the query that you want to stop. A QueryId is an internally-generated identifier for a specific query.
`region`	`string`	AWS region (default: us-east-1)
`IncludeLinkedAccounts`	`boolean`	A boolean option that you can set to TRUE to include monitors for linked accounts in a list of monitors, when you've set up cross-account sharing in Amazon CloudWatch Internet Monitor. You configure cross-account sharing by using Amazon CloudWatch Observability Access Manager. For more information, see Internet Monitor cross-account observability in the Amazon CloudWatch Internet Monitor User Guide.
`LinkedAccountId`	`string`	The account ID for an account that you've set up cross-account sharing for in Amazon CloudWatch Internet Monitor. You configure cross-account sharing by using Amazon CloudWatch Observability Access Manager. For more information, see Internet Monitor cross-account observability in the Amazon CloudWatch Internet Monitor User Guide.
`MaxResults`	`integer`	The number of monitor objects that you want to return with this call.
`MonitorStatus`	`string`	The status of a monitor. This includes the status of the data processing for the monitor and the status of the monitor itself. For information about the statuses for a monitor, see Monitor.
`NextToken`	`string`	The token for the next set of results. You receive this token from a previous call.

`SELECT` examples

get_monitor
list_monitors

Gets information about a monitor in Amazon CloudWatch Internet Monitor based on a monitor name. The information returned includes the Amazon Resource Name (ARN), create time, modified time, resources included in the monitor, and status information.

SELECT
created_at,
health_events_config,
internet_measurements_log_delivery,
max_city_networks_to_monitor,
modified_at,
monitor_arn,
monitor_name,
processing_status,
processing_status_info,
resources,
status,
tags,
traffic_percentage_to_monitor
FROM aws.internetmonitor.monitors
WHERE monitor_name = '{{ monitor_name }}' -- required
AND region = '{{ region }}' -- required
AND LinkedAccountId = '{{ LinkedAccountId }}'
;

Lists all of your monitors for Amazon CloudWatch Internet Monitor and their statuses, along with the Amazon Resource Name (ARN) and name of each monitor.

SELECT
monitor_arn,
monitor_name,
processing_status,
status
FROM aws.internetmonitor.monitors
WHERE region = '{{ region }}' -- required
AND NextToken = '{{ NextToken }}'
AND MaxResults = '{{ MaxResults }}'
AND MonitorStatus = '{{ MonitorStatus }}'
AND IncludeLinkedAccounts = '{{ IncludeLinkedAccounts }}'
;

`INSERT` examples

create_monitor
Manifest

Creates a monitor in Amazon CloudWatch Internet Monitor. A monitor is built based on information from the application resources that you add: VPCs, Network Load Balancers (NLBs), Amazon CloudFront distributions, and Amazon WorkSpaces directories. Internet Monitor then publishes internet measurements from Amazon Web Services that are specific to the city-networks. That is, the locations and ASNs (typically internet service providers or ISPs), where clients access your application. For more information, see Using Amazon CloudWatch Internet Monitor in the Amazon CloudWatch User Guide. When you create a monitor, you choose the percentage of traffic that you want to monitor. You can also set a maximum limit for the number of city-networks where client traffic is monitored, that caps the total traffic that Internet Monitor monitors. A city-network maximum is the limit of city-networks, but you only pay for the number of city-networks that are actually monitored. You can update your monitor at any time to change the percentage of traffic to monitor or the city-networks maximum. For more information, see Choosing a city-network maximum value in the Amazon CloudWatch User Guide.

INSERT INTO aws.internetmonitor.monitors (
MonitorName,
Resources,
ClientToken,
Tags,
MaxCityNetworksToMonitor,
InternetMeasurementsLogDelivery,
TrafficPercentageToMonitor,
HealthEventsConfig,
region
)
SELECT 
'{{ MonitorName }}' /* required */,
'{{ Resources }}',
'{{ ClientToken }}',
'{{ Tags }}',
{{ MaxCityNetworksToMonitor }},
'{{ InternetMeasurementsLogDelivery }}',
{{ TrafficPercentageToMonitor }},
'{{ HealthEventsConfig }}',
'{{ region }}'
RETURNING
arn,
status
;

# Description fields are for documentation purposes
- name: monitors
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the monitors resource.
  - name: MonitorName
    value: "{{ MonitorName }}"
  - name: Resources
    value:
      - "{{ Resources }}"
  - name: ClientToken
    value: "{{ ClientToken }}"
  - name: Tags
    value: "{{ Tags }}"
  - name: MaxCityNetworksToMonitor
    value: {{ MaxCityNetworksToMonitor }}
  - name: InternetMeasurementsLogDelivery
    description: |
      Publish internet measurements to an Amazon S3 bucket in addition to CloudWatch Logs.
    value:
      S3Config:
        BucketName: "{{ BucketName }}"
        BucketPrefix: "{{ BucketPrefix }}"
        LogDeliveryStatus: "{{ LogDeliveryStatus }}"
  - name: TrafficPercentageToMonitor
    value: {{ TrafficPercentageToMonitor }}
  - name: HealthEventsConfig
    description: |
      A complex type with the configuration information that determines the threshold and other conditions for when Internet Monitor creates a health event for an overall performance or availability issue, across an application's geographies. Defines the percentages, for overall performance scores and availability scores for an application, that are the thresholds for when Amazon CloudWatch Internet Monitor creates a health event. You can override the defaults to set a custom threshold for overall performance or availability scores, or both. You can also set thresholds for local health scores,, where Internet Monitor creates a health event when scores cross a threshold for one or more city-networks, in addition to creating an event when an overall score crosses a threshold. If you don't set a health event threshold, the default value is 95%. For local thresholds, you also set a minimum percentage of overall traffic that is impacted by an issue before Internet Monitor creates an event. In addition, you can disable local thresholds, for performance scores, availability scores, or both. For more information, see Change health event thresholds in the Internet Monitor section of the CloudWatch User Guide.
    value:
      AvailabilityScoreThreshold: {{ AvailabilityScoreThreshold }}
      PerformanceScoreThreshold: {{ PerformanceScoreThreshold }}
      AvailabilityLocalHealthEventsConfig:
        Status: "{{ Status }}"
        HealthScoreThreshold: {{ HealthScoreThreshold }}
        MinTrafficImpact: {{ MinTrafficImpact }}
      PerformanceLocalHealthEventsConfig:
        Status: "{{ Status }}"
        HealthScoreThreshold: {{ HealthScoreThreshold }}
        MinTrafficImpact: {{ MinTrafficImpact }}

`UPDATE` examples

update_monitor

Updates a monitor. You can update a monitor to change the percentage of traffic to monitor or the maximum number of city-networks (locations and ASNs), to add or remove resources, or to change the status of the monitor. Note that you can't change the name of a monitor. The city-network maximum that you choose is the limit, but you only pay for the number of city-networks that are actually monitored. For more information, see Choosing a city-network maximum value in the Amazon CloudWatch User Guide.

UPDATE aws.internetmonitor.monitors
SET 
ResourcesToAdd = '{{ ResourcesToAdd }}',
ResourcesToRemove = '{{ ResourcesToRemove }}',
Status = '{{ Status }}',
ClientToken = '{{ ClientToken }}',
MaxCityNetworksToMonitor = {{ MaxCityNetworksToMonitor }},
InternetMeasurementsLogDelivery = '{{ InternetMeasurementsLogDelivery }}',
TrafficPercentageToMonitor = {{ TrafficPercentageToMonitor }},
HealthEventsConfig = '{{ HealthEventsConfig }}'
WHERE 
monitor_name = '{{ monitor_name }}' --required
AND region = '{{ region }}' --required
RETURNING
monitor_arn,
status;

`DELETE` examples

delete_monitor

Deletes a monitor in Amazon CloudWatch Internet Monitor.

DELETE FROM aws.internetmonitor.monitors
WHERE monitor_name = '{{ monitor_name }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

start_query
stop_query

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.

EXEC aws.internetmonitor.monitors.start_query 
@monitor_name='{{ monitor_name }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"StartTime": "{{ StartTime }}", 
"EndTime": "{{ EndTime }}", 
"QueryType": "{{ QueryType }}", 
"FilterParameters": "{{ FilterParameters }}", 
"LinkedAccountId": "{{ LinkedAccountId }}"
}'
;

Stop a query that is progress for a specific monitor.

EXEC aws.internetmonitor.monitors.stop_query 
@monitor_name='{{ monitor_name }}' --required, 
@query_id='{{ query_id }}' --required, 
@region='{{ region }}' --required
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​