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, consider the following information:

• You must manually configure the integration with PagerDuty.
• You must provide the PagerDuty API key.

After you create a view, check the view in the 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 auditing events 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"}

Getting views

When you retrieve all the views and alerts for the instance using the GET method, consider the following information:

• The GET method will return all configured views and associated alerts for the instance.

• The data returned can be imported into a different instance to create the same views and alerts in that instance.

  If presets are defined, importing the data received from the GET method will fail. {: note

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 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:

Table 2. 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
Get all configured views and alerts	GET
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 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 UI, the value that is set for Source in the Line identifiers section corresponds to the hosts value of the service that generates that auditing event.

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 auditing event.

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

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

Notice that the apps value for global auditing events is the CRN of the account where the event is generated.

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": "reason.reasonCode:200",
  "hosts": ["ibm-cloud-databases-prod"],
  "category": ["<MY_CATEGORY>"]
}'

A response similar to the following will be returned:

{"name":"My RC 200","query":"reason.reasonCode:200","hosts":["ibm-cloud-databases-prod"],"category":["89610d13a7"],"viewid":"VIEWID"}

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": "reason.reasonCode:200",
        "hosts": ["ibm-cloud-databases-prod"],
        "category": ["TEST"],
      "channels": [
        {
          "integration": "email",
          "emails": ["myemail@ibm.com"],
          "triggerlimit": 15,
          "triggerinterval": "5m",
          "immediate": true,
          "terminal": true,
          "operator": "presence",
          "timezone": "Europe/London"
        }
      ]
    }'

A response similar to the following will be returned:

{"name":"My RC 200","query":"reason.reasonCode:200","hosts":["ibm-cloud-databases-prod"],"category":["89610d13a7"],"channels":[{"integration":"email","emails":"myemail@ibm.com","triggerlimit":15,"triggerinterval":300,"immediate":true,"terminal":true,"operator":"presence","timezone":"Europe/London","alertid":"<ALERTID>"}],"viewid":"VIEWID"}

Get all configured views and alerts

The following sample gets all configured views and alerts for the instance.

curl --request GET  https://api.eu-de.logging.cloud.ibm.com/v1/config/view  -H "content-type: application/json"  -H "servicekey: <SERVICE_KEY>"

A response similar to the following will be returned:

[{"viewid":"cf1a53da31","name":"(_platform:xxx create) OR (_platform:xxx delete)","query":"(_platform:xxx .create) OR (_platform:xxx .delete)","category":["Instance"],"account":"xxxxxxxxx"},{"viewid":"de6de89f6c","name":"[All] Logins","query":"reason.reasonCode:200 _platform:iam-identity (action login)","category":["Login"],"account":"xxxxxxxx"},{"viewid":"dfd136707e","name":"[All] Events","category":["COS"],"account":"xxxxxxxx","hosts":["cloud-object-storage"]}]

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": "reason.reasonCode:200",
  "hosts": ["ibm-cloud-databases-prod"],
  "category": ["<CATEGORY"],
  "channels": [
    {
      "integration": "email",
      "emails": ["myemail@ibm.com"],
      "triggerlimit": 15,
      "triggerinterval": "5m",
      "immediate": true,
      "terminal": true,
      "operator": "presence",
      "timezone": "Europe/London"
 }
  ]
}'

A response similar to the following is returned:

{"name":"My RC 200","query":"reason.reasonCode:200","hosts":["ibm-cloud-databases-prod"],"category":["89610d13a7"],"channels":[{"integration":"email","emails":"myemail@ibm.com","triggerlimit":15,"triggerinterval":300,"immediate":true,"terminal":true,"operator":"presence","timezone":"Europe/London","alertid":"<ALERTID>"}],"viewid":"<VIEWID>"}

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>'  \

The following response will be returned when the view is successfully deleted:

{"deleted":true}