Managing views and alerts programmatically

Creating views

When you create a view, consider the following information:

• You can create a view with no alerts.
• You can create a view with 1 or more notification channels. Valid alert notification channels that are supported by the Configuration API are: email, webhook, or PagerDuty.
• The response to an API request to create a view includes the ID of the view.
• The name body parameter, that defines the name of the view, is always required.
• A category must exist before you create a view. The request fails if a category is not valid or is not specified.
• You can define body parameters to refine the data that is displayed through the view. You must specify 1 or more of the following body parameters: query, apps, levels, hosts, or tags.

When you create a PagerDuty notification channel, you need to do the following:

• You must manually configure the integration of logging with PagerDuty. See Integrating with PagerDuty.
• You must provide logging with the PagerDuty API key.

After you create a view, check the view in the logging web UI.

1. Refresh the browser to see the view listed in the Views section.

2. Select the view to display it.

3. Check the data that is available through the view is the one that you expect.

   • If you do not see any data, check that data is being generated for the logs that you are planning to monitor through this view. For example, you can check the Everything view and look for events.

   • If data is being generated, and you still cannot see any data, check the body parameter values that you have defined for the view. One of them might be set to the wrong value and the search criteria does not find any matching events.

If you try to create a view without defining a category, you get the following error message:

{"details":[{"message":"\"category[0]\" is not allowed to be empty","key":"category[0]"}],"error":"\"category[0]\" is not allowed to be empty","code":"BadRequest","status":"error"}

If you try to create a view without a valid category, you get the following error message:

{"error":"Invalid category name(s): CATEGORYNAME","code":"BadRequest","status":"error"}

If you try to define a view and you do not define any of the following body parameters, query, hosts, apps, levels, tags, you can get the following error:

{"details":[{"message":"\"value\" must contain at least one of [query, hosts, apps, levels, tags]","key":"value"}],"error":"\"value\" must contain at least one of [query, hosts, apps, levels, tags]","code":"BadRequest","status":"error"}

Modifying views

When you modify a view, consider the following information:

• You must specify the name and the view ID of the view.
• If you are viewing a view in the logging web UI, the view is not refreshed automatically after you run an API request to modify the view. To refresh the view in the UI, you must navigate to the Everything view and back to the view.

An API request to modify a view replaces the existing view definition and associated alerts with your request body data. Any properties that are not specified in your PUT request will be removed.

If the viewid that you are trying to modify does not exist, a response similar to the following will be returned:

{"error":"Nothing to configure","code":"BadRequest","status":"error"}

Deleting views

When you delete a view, consider the following information:

• You must specify the ID of the view that you plan to delete.
• You delete the view and all the alerts that are configured for the view.

content-type

Define the Content-Type header to make successful requests to the API. The content-type header specifies that the request body is in JSON format.

You must pass the content-type in the header parameter (-H) of your requests.

For example, in a cURL request, you must set the content-type header as follows:

-H 'content-type: application/json'

name (string)

Specifies the name of the view.

The following table indicates when the name parameter is required:

Required status per method

Action	Request	Field required
Create a view and attach an alert to a view.	POST
Modify an existing view and the alerts that are attached to the view.	PUT
Delete a view and its associated alerts.	DELETE

query (string)

Specifies the search query that is applied to the view.

Check the query in the logging web UI to validate that the data that is displayed through the view matches the data entry that you plan to monitor through that view.

hosts (array of strings)

Specifies the list of services from which you want to view data.

In the logging web UI, the value that is set for Source in the Line identifiers section corresponds to the hosts value of the service that generates that log.

For example, to enter multiple hosts, you must separate the hosts with a comma:

"hosts": ["is", "event-streams"]

apps (array of strings)

Specifies the service instance ID that generates the log.

For example, to enter multiple apps, you must separate the apps with a comma:

"apps": ["apps1", "apps2"]

channels (array of objects)

Specifies the notification channels and trigger conditions that are associated with a view.

• You can configure 1 or more channels per view.
• You can configure any of the following channels through the Configuration API: email, webhook, PagerDuty.

"channels": [
    {
      "integration": "email",
      "emails": ["LIST OF EMAILS"],    // array of strings (emails) that are comma-separated
      "triggerlimit": 15,
      "triggerinterval": "5m",
      "immediate": true,
      "terminal": true,
      "operator": "presence",
      "timezone": "TIMEZONE"
    },
    {
      "integration": "webhook",
      "url": "WEBHOOK_URL",
      "triggerlimit": 25,
      "triggerinterval": "30",
      "operator": "presence",
      "immediate": true,
      "terminal": true,
      "method": "post",
      "headers": {
        "X-MY-HEADER": "My Header Value"
      },
      "bodyTemplate": {
        "my_log_lines": "{{ lines }}"
      }
    },
    {
      "integration": "pagerduty",
      "key": "PAGERDUTY_KEY",
      "triggerlimit": 150,
      "triggerinterval": "15m",
      "operator": "absence",
      "immediate": false,
      "terminal": true
    }
  ]

category (array of strings)

Specifies the classification of views.

• You can include a view in 1 or more categories.

For example, to associate a view to a category named My category, you can set it as follows:

"category": ["My category"],

Creating a view

The following sample creates a view.

curl https://api.us-south.logging.cloud.ibm.com/v1/config/view \
  -H 'content-type: application/json' \
  -H 'servicekey: <SERVICE_KEY>' \
  -d '{
  "name": "My RC 200",
  "query": "reasonCode:200",
  "hosts": ["myHostName"],
  "category": ["<MY_CATEGORY>"]
}'

Creating a view and attaching an alert

The following sample creates a view and associates an email alert with the view.

curl https://api.eu-de.logging.cloud.ibm.com/v1/config/view \
        -H 'content-type: application/json' \
        -H 'servicekey: <SERVICE_KEY>' \
        -d '{
        "name": "My RC 200",
        "query": "reasonCode:200",
        "hosts": ["myHostName"],
        "category": ["TEST"],
      "channels": [
        {
          "integration": "email",
          "emails": ["myemail@ibm.com"],
          "triggerlimit": 15,
          "triggerinterval": "5m",
          "immediate": true,
          "terminal": true,
          "operator": "presence",
          "timezone": "Europe/London"
        }
      ]
    }'

Modifying a view by adding an alert

The following modifies a view by adding an alert.

curl --request PUT \
  --url https://api.us-south.logging.cloud.ibm.com/v1/config/view/<VIEWID> \
  --header 'Content-Type: application/json' \
  -H 'servicekey: <SERVICE_KEY>'  \
-d '{
  "name": "My RC 200",
  "query": "reasonCode:200",
  "hosts": ["myHostName"],
  "category": ["<CATEGORY"],
  "channels": [
    {
      "integration": "email",
      "emails": ["myemail@ibm.com"],
      "triggerlimit": 15,
      "triggerinterval": "5m",
      "immediate": true,
      "terminal": true,
      "operator": "presence",
      "timezone": "Europe/London"
 }
  ]
}'

Deleting a view

The following sample deletes a view.

curl --request DELETE \
  --url https://api.us-south.logging.cloud.ibm.com/v1/config/view/<VIEWID> \
  -H 'content-type: application/json' \
  -H 'servicekey: <SERVICE_KEY>'  \