IBM Cloud Docs
Searching logs by using queries

Searching logs by using queries

Through the IBM Log Analysis web UI, you can apply search and filtering criteria to define the set of logs 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. For information about IBM Cloud Logs, see the IBM Cloud Logs documentation.

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 Log Analysis web UI, and view, search, and filter events:

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 logs to display through a view by applying a search query

To search for specific logs, 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 logs for the number of days that is specified through the instance's service plan.

If you are searching for Windows logs, you must use double slashes (//) in the search query even though the console will show directories with single slashes.

Example search for Windows logs
Example search for Windows logs

Complete the following steps:

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

When you run a query, notice that the name of the view changes to Unsaved View.

Query for logs that are generated by a host

To filter logs for a specific host on an IBM Log Analysis instance with platform logs, you need to enter the following query:

host:<HOSTNAME>

Where HOSTNAME is the name of a host providing platform logs. For example, to return IBM Cloud database logs specify the following query:

host:ibm-cloud-databases-prod

Query by log criticallity

Each log has a level field that defines the level of threat the log issue might have.

Valid values in ascending order of severity are shown in the following table.

Levels
Value Description
N/A Log entries with no level specified.
INFO An informational log entry providing information about the routine operations of the service.
REQUEST A log entry indicating a request to the service.
METADATA A log entry indicating a change to the service metadata.
DEBUG A log entry used to provide additional troubleshooting information.
WARN A log entry providing information about an issue that might potentially indicate a problem.
ERROR A log entry indicating a problem with the operation of the service.
CRIT A log entry indicating a critial issue with the operation of the service.

This is a list of possible values. The actual available values will vary depending on the service or host generating the logs.

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

level:<VALUE>

For example, to query for ERROR log entries, you can run the following query:

level:ERROR

Query by label

You can also query by labels specified in the log entries.

To see the available labels, open a log entry in the IBM Log Analysis UI. Available labels will be listed in the LABELS section.

For example, to filter to all the log entries for the ibm-cloud-databases-prod host with the postgresql label, run the following query:

host:ibm-cloud-databases-prod AND label.database:postgresql

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. 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 log 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 preferencesS. 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

The following are guidelines when defining a line templates:

  • 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 {{_host}} -- {{_label.database}} -- {{message}} to see these fields for each log entry 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.