Monitoring (ibmcloud monitoring) CLI

The IBM Cloud® command-line interface (CLI) provides extra capabilities for service offerings. This information describes how you can use the CLI to access information in IBM Cloud Monitoring.

Prerequisites

Install the IBM Cloud CLI.
Install the IBM Cloud Monitoring CLI by running the following command:
```
ibmcloud plugin install monitoring
```

You are notified on the command line when updates to the IBM Cloud CLI and plug-ins are available. Be sure to keep your CLI up to date so that you can use the latest commands. You can view the current version of all installed plug-ins by running ibmcloud plugin list.

ibmcloud monitoring alert add

Use this command to add an alert.

ibmcloud monitoring alert add --name NAME [--alert-name ALERT_NAME] [--description DESCRIPTION] [--type TYPE] [--timespan TIMESPAN] [--condition CONDITION] [--severity SEVERITY] [--severity-label LOW, MEDIUM OR HIGH] [--disable] [--segment SEGMENT] [--segment-condition SEGMENT_CONDITION] [--user-filter USER_FILTER] [--notify NOTIFY] [--file JSON_FILE] [--region REGION] [--output FORMAT] [--team TEAM_NAME]

Command options

--name <NAME> | --n <NAME>

Name of the instance.

--alert-name <ALERT_NAME>

Name of the alert.

--description <DESCRIPTION>

Information about the alert.

--type <TYPE>

Type of alert. Valid values are MANUAL, BASELINE, and HOST_COMPARISON.

--timespan <TIMESPAN>

Minimum time interval, in microseconds, for which the alert condition must be met before the alert is triggered. The default value is 60,000,000 microseconds.

--condition <CONDITION>

Threshold of the alert. This parameter is required for manual alerts, and does not apply to other alert types.

--severity <SEVERITY> | -s <SEVERITY>

Level of severity. Valid values range from 0 to 7. 0 means emergency and 7 means debug. By default, severity is set to 4.

--severity-label <LOW | MEDIUM | HIGH>

Criticality of an alert. Valid values are HIGH, MEDIUM, LOW. A lower severity value indicates a higher severity.

--disable

State of the alert. By default, an alert is enabled when it is created. You must set this parameter to disable the alert when it is created.

--segment <SEGMENT>

Additional segmentation criteria. For example, you can segment an alert by ['host.mac', 'proc.name'].

--segment-condition <SEGMENT_CONDITION>

Defines when the alert is triggered for each monitored entity that is specified in the --segment parameter. This parameter is required for manual alerts, and does not apply to other alert types. Valid values are ANY and ALL. ANY indicates that the alert is triggered when at least one of the monitored entities satisfies the condition. ALL indicates that the alert is triggered when all of the monitored entities satisfy the condition.

--user-filter <USER_FILTER>

Boolean expression that you can set to reduce the scope of the alert. Use this parameter to configure segments, such as filters like kubernetes.namespace.name='production' or container.image='nginx'.

--notify <NOTIFY>

Type of notification that you want this alert to generate. Options are EMAIL, SNS, PAGER_DUTY, and SYSDIG_DUMP.

--file <FILE> | -f <JSON_FILE>

Name of the JSON file that contains the data set for a new alert creation. Make sure you create the alert.json file before invoking this command.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--output <FORMAT>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--team <TEAM_NAME>

The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring alert add command.

Add an alert for the IBM Cloud Monitoring abc instance to detect a CrashLoopBackOff in the last 5 minutes.

ibmcloud monitoring alert add \
        --name "IBM Cloud Monitoring abc" \
        --description "Alert to report crashLoopBackOffs that are detected" \
        --severity 2 \
        --timespan 300 \
        --condition 'sum(avg(kubernetes.pod.restart.count)) > 1' \
        --alert-name '[Kubernetes] Pod crash/restart loop'

Add an alert for the IBM Cloud Monitoring abc instance to detect a CrashLoopBackOff in the last 5 minutes with severity set to medium.

ibmcloud monitoring alert add \
        --name "IBM Cloud Monitoring abc" \
        --description "Alert to report crashLoopBackOffs that are detected" \
        --severity 2 \
        --severity-label MEDIUM \
        --timespan 300 \
        --condition 'sum(avg(kubernetes.pod.restart.count)) > 1' \
        --alert-name '[Kubernetes] Pod crash/restart loop'

ibmcloud monitoring alert list

Use this command to list the alerts for the specified instance.

ibmcloud monitoring alert list --name NAME [--severity SEVERITY] [--enabled TRUE or FALSE] [--region REGION] [--output FORMAT] [--team TEAM_NAME]

Command options

--name <NAME> | --n <NAME>

Name of the instance.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--severity <SEVERITY> | -s <SEVERITY>

A comma-separated list of severity values enclosed in double-quotes ("). If only a single severity is specified, the double-quotes can be omitted.

--output <FORMAT>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--enabled <TRUE | FALSE> | -e <TRUE | FALSE>

Boolean that indicates the alerts to be listed based on the alert notification settings. If specified, --enabled true will list alerts for instances where notifications, for example, email or Slack, are enabled. Specifying --enabled false will return a list of alerts for instances where notifications are not enabled.

--team <TEAM_NAME>

The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring alert list command.

List all alerts for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring alert list --name "IBM Cloud Monitoring abc"

List all alerts for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring alert list --name "IBM Cloud Monitoring abc" --region us-south

List all alerts for the IBM Cloud Monitoring abc instance with low and medium severity where notifications are not enabled.

ibmcloud monitoring alert list --name "IBM Cloud Monitoring abc" --enabled false --severity low,medium

ibmcloud monitoring alert get

Use this command to get details on an alert by using the alert ID.

ibmcloud monitoring alert get --name NAME --id ALERT_ID [--region REGION] [--output FORMAT] [--team TEAM_NAME]

Command options

--name <NAME> | --n <NAME>

Name of the instance.

--id <ALERT_ID>

ID of the alert.

--region <REGIO> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--output <FORMAT>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--team <TEAM_NAME>

The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring alert get command.

Get details for an alert with ID 1234567 for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring alert get --name "IBM Cloud Monitoring abc" --id 1234567

Get details for an alert with ID 1234567 for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring alert get --name "IBM Cloud Monitoring abc" --id 1234567 --region us-south

ibmcloud monitoring alert update

Use this command to modify an alert by using a JSON file.

To update of an alert, you must modify the JSON file that you get by running the ibmcloud monitoring alert get command.

ibmcloud monitoring alert update --name NAME --id ALERT_ID --file JSON_FILE [--region REGION] [--output FORMAT] [--team TEAM_NAME]

Command options

--name <NAME> | --n <NAME>

Name of the instance.

--id <ALERT_ID>

ID of the alert.

--file <FILE> | -f <JSON_FILE>

Name of the JSON file that contains the data with the alert definition. Make sure you create or modify the alert.json file before invoking this command.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--output <TYPE>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--team <TEAM_NAME>

The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring alert update command.

Update an alert with ID 1234567 for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring alert update --name "IBM Cloud Monitoring abc" --id 1234567 --file alert.json

Update an alert with ID 1234567 for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring alert update --name "IBM Cloud Monitoring abc" --id 1234567 --file alert.json --region us-south

ibmcloud monitoring alert delete

Use this command to delete an alert.

ibmcloud monitoring alert delete --name NAME --id ALERT_ID [--region REGION] [--force] [--team TEAM_NAME]

Command options

--name <NAME> | --n <NAME>: Name of the instance.
--id <ALERT_ID>: ID of the alert.
--region <REGION> | -r <REGION>: Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.
--force: Supresses the prompt and deletes the alert from the instance that is specified by --name.
--team <TEAM_NAME>: The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.
--help | -h: List options available for the command.

Examples

The following are examples using the ibmcloud monitoring alert delete command.

Delete an alert with ID 1234567 for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring alert delete --name "IBM Cloud Monitoring abc" --id 1234567 --file alert.json

Delete an alert with ID 1234567 for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring alert delete --name "IBM Cloud Monitoring abc" --id 1234567 --file alert.json --region us-south

ibmcloud monitoring service-instances

Use this command to list IBM Cloud Monitoring service instances.

ibmcloud monitoring service-instances [--region REGION] [--all-regions] [--g RESOURCE_GROUP] [--all-resource-groups] [--quiet] [--output FORMAT]

Command options

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--all-regions

Services hosted across all regions.

-g <RESOURCE_GROUP>

Resource Group associated with the hosted service.

--all-resource-groups

Services hosted across all resource groups.

--quiet | -q

Supresses verbose output.

--output <FORMAT>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring service-instances command.

List all monitoring service instances.

ibmcloud monitoring service-instances

List all instances that are in the test-rg resource group.

ibmcloud monitoring service-instances -g test-rg

List all instances and include additional details, such as ID, GUID, and Resource ID.

ibmcloud monitoring service-instances --output wide

List all instances and include only the minimal details of Name, Region and State.

ibmcloud monitoring service-instances --quiet

List all instances for the us-south region.

ibmcloud monitoring service-instances --region us-south

Lists all instances in the us-south region and returns the output in JSON format.

ibmcloud monitoring service-instances --region us-south --output json

ibmcloud monitoring platform-metrics-receiver

Use this command to configure the specified IBM Cloud Monitoring service instance to receive platform metrics. When run, the command prompts the user to keep an existing service instance or replace it with the specified instance.

ibmcloud monitoring platform-metrics-receiver --name NAME [--region REGION] [--force]

Command options

--name <NAME> | --n <NAME>: Name of the instance.
--region <REGION> | -r <REGION>: Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted is used.
--force: Supresses the prompt and replaces the existing platform metric instance with the instance specified by --name.
--help | -h: List options available for the command.

Examples

The following are examples using the ibmcloud monitoring platform-metrics-receiver command.

Configures the IBM Cloud Monitoring abc as the instance to receive platform metrics.

ibmcloud monitoring platform-metrics-receiver --name "IBM Cloud Monitoring abc"

Configures the IBM Cloud Monitoring abc in the eu-gb region as the instance to receive platform metrics.

ibmcloud monitoring platform-metrics-receiver --name "IBM Cloud Monitoring abc" --region eu-gb

ibmcloud monitoring dashboard list

Use this command to list all the dashboards that are visible to a user in a Monitoring instance.

ibmcloud monitoring dashboard list --name NAME [--region REGION] [--output FORMAT] [--team TEAM_NAME]

Command options

--name <NAME> | --sn <NAME>

Name of the instance.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--output <TYPE>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--team <TEAM_NAME>

The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring dashboard list command.

List all dashboards for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring dashboard list

List all dashboards for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring dashboard list --region us-south

ibmcloud monitoring dashboard get

Use this command to get details for a dashboard by using the dashboard ID.

ibmcloud monitoring dashboard get --id DASHBOARD_ID --name NAME [OPTIONS] [--team TEAM_NAME]

Command options

--name <NAME> | --sn <NAME>: Name of the instance.
--id <DASHBOARD_ID>: Dashboard_ID of a specific service Instance.
--region <REGION> | -r <REGION>: Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.
--team <TEAM_NAME>: The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.
--help | -h: List options available for the command.

Examples

The following are examples using the ibmcloud monitoring dashboard get command.

Get information for a dashboard with ID 1234567 for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring dashboard get --name "IBM Cloud Monitoring abc"

Get information for a dashboard with ID 1234567 for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring dashboard get --name "IBM Cloud Monitoring abc" --region us-south

ibmcloud monitoring dashboard add-json

Use this command to create a dashboard by using a JSON file.

ibmcloud monitoring dashboard add-json --file JSON_FILE --name NAME [--region REGION] [--team TEAM_NAME]

Command options

--file <FILE> | -f <JSON_FILE>: Name of the JSON file that contains the information for a new dashboard creation. Make sure you create the dashboard.json file before invoking this command.
--name <NAME> | --sn <NAME>: Name of the instance.
--region <REGION> | -r <REGION>: Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.
--team <TEAM_NAME>: The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.
--help | -h: List options available for the command.

Examples

The following are examples using the ibmcloud monitoring dashboard add-json command.

Create a dashboard for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring dashboard add-json --name "IBM Cloud Monitoring abc" --file dashboard.json

Create a dashboard for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring dashboard add-json --name "IBM Cloud Monitoring abc" --file dashboard.json --region us-south

ibmcloud monitoring event list

Use this command to list the events.

ibmcloud monitoring event list --name NAME [--region REGION] [--last DURATION] [--from TIMESTAMP] [--to TIMESTAMP] [--limit LIMIT] [--output FORMAT] [--team TEAM_NAME]

Command options

--name <NAME> | --sn <NAME>

Name of the instance.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--last <DURATION>

Period of time for which you want to list events. For example, you can set 12h to show events for the last 12 hours, 15m to show events for the last 15 minutes, or 10d to show events for the last 10 days.

--from <TIMESTAMP>

The UNIX timestamp in seconds for the beginning of the events.

--to <TIMESTAMP>

The UNIX timestamp in seconds for the end of the events.

--limit <LIMIT>

Maximum number of events to print in the period of time specified in the request. By default, the parameter is set to a 100 events. The maximum number of events hat you can set is 10000.

--output <TYPE>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--team <TEAM_NAME>

The name of the IBM Cloud Monitoring team to be used for authorization. If no team is specified, the default team will be used.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring event list command.

List events for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring event list --name "IBM Cloud Monitoring abc"

List events for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring event list --name "IBM Cloud Monitoring abc" --region us-south

List events for the IBM Cloud Monitoring abc instance in the us-south region for the last hour.

ibmcloud monitoring event list --name "IBM Cloud Monitoring abc" --region us-south --duration 1H

ibmcloud monitoring settings notification list

Use this command to list notification channels.

ibmcloud monitoring settings notification list --name NAME [--region REGION] [--output FORMAT]

Command options

--name <NAME> | --sn <NAME>

Name of the instance.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--output <TYPE>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring settings notification list command.

List the notification channels for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring settings notification list --name "IBM Cloud Monitoring abc"

List the notification channels for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring settings notification list --name "IBM Cloud Monitoring abc" --region us-south

ibmcloud monitoring settings team list

Use this command to list teams.

ibmcloud monitoring settings team list --name NAME [--region REGION] [--output FORMAT]

Command options

--name <NAME> | --sn <NAME>

Name of the instance.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--output <TYPE>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring settings team list command.

List the teams for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring settings team list --name "IBM Cloud Monitoring abc"

List the teams for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring settings team list --name "IBM Cloud Monitoring abc" --region us-south

ibmcloud monitoring settings user list

Use this command to list users.

ibmcloud monitoring settings user list --name NAME [--region REGION] [--teamID TEAM_ID] [--output FORMAT]

Command options

--name <NAME> | --sn <NAME>

Name of the instance.

--region <REGION> | -r <REGION>

Name of the region, for example, us-south or eu-gb. If not specified, the region logged into or targeted will be used.

--teamID <TEAM_ID>

ID of the team.

--output <TYPE>

A comma-separated list of output preferences enclosed in double-quotes ("). If only a single preference is specified, the double-quotes can be omitted. Supported options are WIDE and JSON.

If JSON is specified, output will be returned in JSON format. If JSON is not specified, output will be returned in a tabular format.

WIDE returns additional details in the output.

--help | -h

List options available for the command.

Examples

The following are examples using the ibmcloud monitoring settings user list command.

List the users for the IBM Cloud Monitoring abc instance.

ibmcloud monitoring settings user list --name "IBM Cloud Monitoring abc"

List the users for the IBM Cloud Monitoring abc instance in the us-south region.

ibmcloud monitoring settings user list --name "IBM Cloud Monitoring abc" --region us-south