IBM Cloud Docs
Searching events by using queries

Searching events by using queries

Through the IBM Cloud Activity Tracker web UI, you can apply search and filtering criteria to define the set of events that are displayed through a custom view.

As of 28 March 2024 the IBM Log Analysis and IBM Cloud Activity Tracker services are deprecated and will no longer be supported as of 30 March 2025. Customers will need to migrate to IBM Cloud Logs, which replaces these two services, prior to 30 March 2025.

Prerequisites

Before you start, check that your user ID has permissions to launch the web UI and view events. The following table lists the minimum roles that a user must have to be able to launch the IBM Cloud Activity Tracker web UI, and view, search, and filter events:

Table 1. IAM roles
Role Permission granted
Platform role: viewer Allows the user to view the list of service instances in the Observability dashboard.
Service role: reader Allows the user to launch the web UI and view events in the web UI.
Service role: standard-member Allows the user save a view based on a search.

For more information on how to configure policies for a user, see Granting user permissions to a user or service ID.

Step 1. Go to the web UI and select a view

Complete the following steps:

  1. Go to the web UI.
  2. Click the Views icon Views icon.
  3. Select Everything or a view.

Step 2. Select the set of events to display through a view by applying a search query

To search for specific events, you can apply a search query.

  • You can do simple searches (single term string search), compound search (multiple search terms and operators), field searches if the log line can be parsed, and others.
  • AND and OR operators are case-sensitive and must be capitalized.
  • Use FieldName:==FieldValue to search for a specific field value.
  • Use FieldName:Value to search for field values that start with that value.

You can only search events for the number of days that is specified through the instance's service plan.

Complete the following steps:

  1. Enter a search query.
  2. Press Enter.

As you apply a query, notice that the name of the view changes to Unsaved View.

Query for events that are generated by a service

To filter out events for a specific service, you need to enter the following query:

_platform:==SERVICENAME

Where SERVICENAME is the name of the service in the IBM Cloud.

The following table lists core services:

Table 2. Query by service name
Events that are generated by Value Sample query
IAM Access Management service iam-am _platform:==iam-am
IAM Identity service iam-identity _platform:==iam-identity
IAM Access Groups service iam-groups _platform:==iam-groups
Resource controller service BSS _platform:==BSS

Query for sets of events that are generated by a service

When a service generates different types of events, you can enter the following query:

_platform:==SERVICENAME [(action TYPEOFACTION)]

Where

  • SERVICENAME is the name of the service in the IBM Cloud
  • TYPEOFACTION is a compound query where you can use AND and OR operators, and also use - to exclude data. Notice that the AND and OR operators are case-sensitive and must be capitalized.

The following table show examples of how to query for a group of events that is generated by a service:

Table 3. Samples of more complex queries
Events that are generated by Type of events Sample query
IAM Identity service Login events _platform:==iam-identity (action login)
IAM Identity service API key events _platform:==iam-identity (action user-apikey) -(action login)
IAM Identity service Account service ID events _platform:==iam-identity (action account-serviceid)
Resource controller Provisioning and managing service instances _platform:==BSS (action instance)
Resource controller Managing users in the account _platform:==BSS (action user-management.user)

Query for events that have a specific action

Each event has an action field that informs about the action that triggered the event. You can enter the following query to search for all events that have the same action:

action ACTIONVALUE

Where ACTIONVALUE is the value of the action field or part of the value.

The following table show examples of queries for different actions:

Table 4. Samples of queries by action type
Action Sample query
Provision a service action instance.create
Remove an instance action instance.delete
Add a user action user-management.user.create

Query for events with a specific reason code

You can enter the following query to search for events with a specific reason code:

reason.reasonCode:VALUE

Where VALUE represents the reason code value.

For example, to filter events with reason code 500, you can enter the following query:

reason.reasonCode:500

Query for events whose action fails

When an action requested fails, the field outcome is set to failure. You can enter the following query to search for these type of events:

outcome:failure

Query by event criticallity

Each event has a severity field that defines the level of threat an action may have on the Cloud.

Valid values are normal, warning, and critical.

  • Normal is set for routine actions in the Cloud. For example, starting an instance, or refreshing a token.
  • Warning is set for actions where a Cloud resource is updated or its metadata is modified. For example, updating the version of a worker node, renaming a certificate, or renaming a service instance.
  • Critical is set for actions that affect security in the Cloud. For example, changing credentials of a user, deleting data, unauthorized access to work with a Cloud resource.

You can enter the following query to search for these type of events:

severity:VALUE

Where VALUE can be set to normal, warning, or critical

For example, to query for critical events, you can run the following query:

severity:critical

Step 3. Create a custom view

After you apply the search query to the Everything view or to an existing custom view, complete the following steps to save the outcome as a custom view:

  1. In the web UI, click Unsaved View.
  2. Select Save as new view / alert. The Create new view page opens.
  3. Enter a name for the view in the Name field.
  4. Optionally, add a category. Enter a name and then click Add this as new view category.
  5. Optionally, attach an alert. A new section is displayed for you to configure the alert.
  6. Click Save View

Step 4. Customize how event lines are displayed through a view

There are different options to customize how you see data in a view:

  • You can modify the properties of a view.
  • You can rename a view, add or modify its description, and apply a specific line format.
  • You can change the log format in the User preferences section.
  • You can apply a line template from the Tools section. Notice that this overrides any other line configuration. If you select Persist these settings, all views in the UI will show data per the line format that is specified in this section.
  • You can apply color to terms or strings by setting Highlight Terms in the Tools section.

Change the line format through the view properties page

Complete the following steps to modify the format of an event line in a single view:

  1. In your view, select Edit View Properties. The Edit View Properties page opens.

  2. Enter a custom line format in the Custom %LINE Template section. The default is set to {{line}}.

    For more information about the line template guidelines, see Guidelines.

  3. Click Save properties.

Change the line format through the user preferences section

In the User preferences section, you can modify the order of the data fields that are displayed per line.

Complete the following steps to modify the format of an event line:

  1. In the web UI, click the User preferences icon.
  2. Select User preferences. A new window opens.
  3. Select Log Format.
  4. Modify the Line Format section to match your requirements by dragging the boxes to the desired location.

Change the line format through the line template in the tools section

Complete the following steps to modify the format of an event line:

  1. In the view, click the Tools icon Tools icon.
  2. In the Line Template field, enter your custom line format. For more information about the line template guidelines, see Guidelines.
  3. Optionally, click Persist these settings to apply the line format to all views.

Highlight terms

Complete the following steps to highlight terms in a view:

  1. In the view, click the Tools icon Tools icon.
  2. In the Line Template field, enter a word or string in the Highlight Terms section.
  3. Optionally, click Persist these settings to apply these setting to all views.

Guidelines defining line templates

Consider the following guidelines that you must apply when you define a line template:

  • Use mustache style {{field.name}} or bash style ${field.name} variables to construct your template.
  • Use {{line}} or $@ to reference the original line.
  • All other characters or strings are interpreted as a text literal.

For example, you can define a line template as {{initiator.id}} -- {{action}} -- {{message}} to see these fields for each event in a view.

Change the name and description of a custom view

You can rename a view. You can add or modify the description of a view.

Complete the following steps:

  1. In your view, select Edit View Properties. The Edit View Properties page opens.

    You can rename the view, add or modify the description of the view, and apply a custom line format.

  2. Enter a new name in the Rename View section to rename the view.

  3. Enter or modify the description in the Description section.

  4. Click Save properties.