Save and Share Log Searches

After you create and execute a search query, you can save and share your log searches as a widget for further reuse.

If you’ve created the widget based on a fixed time range, then every time that you open the widget, it will show the results for the time range that you specified in the search. If you’ve created the widget for a relative time range (say the last 7 days), then every time that you open the widget, it will show the up-to-date results as per the time selector (Last 7 days).

Using saved searches, other users can also access the search query.

Save a Search and Add It to a Dashboard

After you've entered a search query and displayed the results in a chart, to save the search as a widget:

  1. Click Save.

  2. Enter the name and description of the widget.

    You can now add this widget to a custom dashboard. See Create Dashboards.

    You can view the number of saved searches in your Oracle Cloud Logging Analytics instance from the Configuration page.

    You can also save your search directly to a dashboard. After you've entered a search query and displayed the results in a chart, to save the search to a dashboard:

    1. Click Save.

    2. Click the Add to dashboard check box.

    3. In the Dashboard field, click the down arrow, and select the name of the dashboard to which you want to save the search. If you want to save the search to a new dashboard, then select New Dashboard and enter the name of the new dashboard.

      Click Save.

      You can now access the saved search from the specified dashboard.

  3. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Administration. The Administration Overview page opens.

  4. The administration resources are listed in the left hand navigation pane under Resources. Click Saved Searches.

    In the Saved Searches page, you can view the list of built-in and custom saved searches. The built-in saved searches are represented with gear icons and the custom ones are represented with human icons.

  5. Click the Action icon next to a saved search entry to display the following menu options:

    • Delete: Lets you delete a custom saved search. A built-in search can’t be deleted. In the case of a built-in search, the Delete option is grayed out (disabled).

    • View in Log Explorer: Lets you open the saved search in the Oracle Cloud Logging Analytics Explorer view.

    • Show Query: Displays the query used for the search. You can additionally copy the query to the clipboard.

Create a Saved Search from an Existing One

To customize a built-in or custom saved search, use the Save As option in the Log Explorer.

  1. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Log Explorer.

  2. In the Log Explorer, click Actions Actions menu menu > click Open.

  3. In the Open dialog box, select the saved search that you want to modify and click Open.

  4. Update the search criteria based on your requirement, click Actions Actions menu menu > click Save As.

  5. In the Save Search dialog box, enter a name for the updated search.

  6. Click Save.

The new search now appears in your list of saved searches.

Create a Schedule to Automatically Run a Saved Search Query

After creating a saved search, you can schedule to run the query in the saved search periodically and route the result of running the query to the Monitoring service.

The following steps are demonstrated with Monitoring service as the target for monitoring the scheduled task. The metrics emitted by Oracle Cloud Logging Analytics are stored by the Monitoring service.

  • To understand how queries are built in Monitoring service, see Building Metric Queries in Oracle Cloud Infrastructure Documentation.

  • Create IAM policy to access the Monitoring service and the resource compartment, create a dynamic group, and group access to metrics. For the policy details, see Building Metric Queries - Prerequisites in Oracle Cloud Infrastructure Documentation.

    In the work flow below, you are notified about the required policies in Step 13. Make note of the required policies and create them.

For the Scheduled Tasks API reference, see ScheduledTask Reference in Oracle Cloud Infrastructure API Documentation.

  1. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Administration. The Administration Overview page opens.

  2. Click Saved Searches from the list of available resources.

    The Saved Searches listing page will show all saved searches available. You can search and identify one that you want to use.

  3. Click the saved search name for which you want to create a schedule. The saved search details page opens.

    This displays the compartment name under Resource Scope where the saved search resource is located.

  4. Under Resources, click Scheduled Tasks.

    The scheduled tasks created for this saved search are listed for the selected compartment. You can select a different compartment to view scheduled tasks in it for this saved search.

  5. Click Schedule Task to create a schedule for running the query in the saved search.

    The Schedule Task dialog box opens. The query that will be scheduled to automatically run is displayed at the top of the dialog box.

  6. Enter a Task Name which can be used for identifying this scheduled task in the list.

    The Task Compartment is the compartment that you selected on the saved search details page.

  7. Select the Target Service where the results of running the query are posted, for example, Monitoring.

    The Monitoring service stores the metrics for the result of running the query on a schedule.

  8. Select Metric Compartment, the compartment where the metric will be created. A compartment is selected by Oracle Cloud Logging Analytics, by default.

  9. Select Metric Namespace, the metric namespace where you want to put the new metric. The scope of options available for selecting the namespace is defined by the selection of Metric Compartment in the previous step. If options are not available, then you can also enter a new value for the namespace.

  10. Optionally, select Resource Group, the group that the metric belongs to. A resource group is a custom string provided with a custom metric.

  11. Enter Metric Name, the name of the metric, used in the Monitoring service explorer to view the metrics. Only one metric can be specified.

    For easy identification in the metric explorer, it is recommended that you include the saved search name in your metric name, for example, <mysavedsearchname><metric_name>.

  12. Specify Interval, the aggregation window. You can optimize the schedule to run in the selected Minutes, Hours, Days, or Weeks. Further, when you select larger aggregations, for example Days, then you can specify the finer aggregation within the range, for example, time of the day when the query must be run.

  13. If the required IAM policies are not defined yet, then a notification is displayed that lists the policies to:

    • Create a dynamic group
    • Apply the policies to the dynamic group to allow the scheduled tasks to run

    Make note of the policies listed and create them.

  14. Click Schedule Task.

    The query is now scheduled to run at a regular interval, and the resulting metrics are emitted to the Monitoring service.

  15. In the Scheduled Task list, click Actions menu icon actions menu next to the scheduled task you created now, and select View in Metric Explorer to view the metrics in the Monitoring service.

More Actions for Scheduled Tasks

The scheduled task is listed in the Scheduled Task page. To view details of the scheduled task and perform more actions, click Actions menu icon actions menu next to the scheduled task you created now, and select View Details. In the details page, you can:

  • Edit the scheduled task using the Edit button.

  • Enable and Disable a scheduled task.

    Note

    This helps you to have fine-grain control over the running of the scheduled task at all times, to optimize the cost of using the Monitoring service.

  • Move the scheduled task to a different compartment.

  • Add tags which can be used for filtering in the Saved Search details page.

  • View the metrics generated by the scheduled task. You can specify the following customizations to view the metrics:

    • The time span for which the metric data must be displayed
    • The time interval at which the data must be collated for display. Make sure to specify a value that's higher than the interval at which the task is scheduled to run.
    • The statistical operation to perform on the data for displaying. You can select from Max, Min, Rate, Sum, Mean, Count, 50 Percentile, 90 Percentile, 95 Percentile, and 99 Percentile.
  • Click View in Metric Explorer to view the metrics generated by the scheduled task in the Monitoring service.

View All the Scheduled Tasks in a Compartment Using API

To view the scheduled tasks for a specific saved search, you can visit the saved search details page. However, if you want to list all the scheduled tasks in a specific compartment without reference to the saved searches for which the scheduled tasks were created for, then use the API to query for listing the scheduled tasks. See ListScheduledTasks.

Specify the following parameters in your GET command:

  • taskType=SAVED_SEARCH
  • compartmentId=<compartment_OCID>
  • limit=1000
  • sortOrder=DESC
  • sortBy=timeUpdated

To run the command, you will need:

  • Namespace: The Logging Analytics namespace that you specified while creating the scheduled tasks.
  • Compartment OCID: The OCID of the compartment that you want to query for the list of scheduled tasks created in it.

Create Alerts for Saved Searches

You can set up alarms for the saved searches by specifying the threshold, time range, and the notification. When the search criteria meets the threshold value over the specified time interval, an alert is generated and a notification is sent to the specified recipient.

To set up an alarm, you must first create a scheduled task for the saved search which can emit metrics to the Monitoring service. Managing alarms is part of the Monitoring service. Ensure that the required IAM policies are created when you create a scheduled task, which will be sufficient to use the alarm feature in the Monitoring service.

  1. Create a saved search by saving your query. See Save a Search and Add It to a Dashboard.

    Using this saved search, you will be able to run the query multiple times.

  2. Create a scheduled task for your saved search. See Create a Schedule to Automatically Run a Saved Search Query.

    You can schedule to run the saved search query at a convenient interval. This will emit the metrics of running the query to the Monitoring service. You can view the metrics in the Metrics Explorer in Monitoring service.

  3. Create an alarm for the metrics generated by the scheduled task, in the Monitoring service:

    1. Specify the metrics details.

    2. Define the trigger rule. Specify the threshold values and operator that must be used by the Monitoring service to determine when to trigger the alarm.

    3. Set up the notification mechanism to get notified when an alarm gets triggered. View the supported subscription protocols and select the method of notification. See Notifications overview in Oracle Cloud Infrastructure Documentation.

    For detailed steps to create an alarm in Monitoring service, see Managing Alarms in Oracle Cloud Infrastructure Documentation.

Use Oracle-Defined Saved Searches

Oracle Cloud Logging Analytics provides predefined saved searches for important use cases. You can know more about them through the Description column in the Saved Searches page.

Use the Oracle-defined saved searches in the following ways:

  • View the queried data in the Log Explorer.
  • The Oracle-defined saved search is available as a widget that you can add to the dashboard.
  • Create a duplicate of the Oracle-defined saved search to move it to a different compartment, to add tags, or to create a scheduled task for the underlying query. Use the scheduled task to generate alerts for you.

To duplicate an Oracle-defined save search:

  1. Open the navigation menu and click Observability & Management. Under Logging Analytics, click Administration. The Administration Overview page opens.

  2. Click Saved Searches from the list of available resources.

    The Saved Searches listing page will show all saved searches available. You can identify an Oracle-defined save search with the value Oracle-defined in the Creation Type column.

  3. Click Actions menu icon actions menu next to the saved search > click Duplicate.

    The Duplicate Search dialog box opens.

  4. Specify the following information for the duplicate saved search that you want to create:

    • Saved Search Compartment: The compartment in which the duplicate of the Oracle-defined save search must be stored.
    • Search Name: The name that the duplicate must be saved with.

    Click Submit.

Export the Search Results

If you want to store the search results offline, then Oracle Cloud Logging Analytics lets you export search results in Comma-separated Values (CSV) or JavaScript Object Notation (JSON) format.

To export search results:
  1. Search the logs to obtain your desired result.
  2. Click Export.
  3. For the file format, select Comma-Separated Values or JavaScript Object Notation.
  4. Enter a name for the file and click Export.
In the case of the Records and Histogram visualizations, the search result is exported based on the time, original log content, and all the selected display fields. In the case of Table visualization, the search result is exported based on the time and selected display fields. For any other visualization, the results of the query displayed in the selected visualization is exported.