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.

More Topics for Scheduled Tasks:

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

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

    The administration resources are listed in the left hand navigation pane under Resources. Click Detection rules.

    The Detection rules page opens. Click Create rule.

    The Create Detection Rule dialog box opens.

  2. Click Scheduled search detection rule.

  3. Specify a Rule name for the scheduled task.

  4. Specify the saved search for which you want to create a schedule. First, select the compartment where the saved search is saved.

    Next, from the menu, select the Saved Search.

    This displays the saved search details like the query and its description.

  5. 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.

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

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


    When specifying a new value for the namespace, select a name that does not start with oracle_ and oci_. They are reserved prefixes. See Publishing Custom Metrics.
  8. Optionally, select Resource Group, the group that the metric belongs to. A resource group is a custom string provided with a custom metric.

  9. 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>.

  10. 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.

  11. 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.

  12. Click Create Detection Rule.

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

  13. In the Scheduled search detection rules listing page, click the name of the scheduled search. In the scheduled search details page, and click View in Metric Explorer to view the metrics in the Monitoring service.

Allow Users to Perform All Operations on Scheduled Tasks

To create Scheduled Tasks, first set up right permissions by creating the following IAM policies:

  1. Create a dynamic group to allow Scheduled Tasks to post metrics to the monitoring service from specific compartment:

    ALL {resource.type='loganalyticsscheduledtask','<compartment ocid>'}

    Alternatively, to allow metrics to be posted from all compartments:

    ALL {resource.type='loganalyticsscheduledtask'}
  2. Create policies to allow the dynamic group to perform Scheduled Task operations in tenancy:

    allow group <group_name> to use loganalytics-scheduled-task in tenancy
    allow dynamic-group <dynamic_group_name> to use metrics in tenancy
    allow dynamic-group <dynamic_group_name> to read management-saved-search in tenancy
    allow dynamic-group <dynamic_group_name> to {LOG_ANALYTICS_QUERY_VIEW} in tenancy
    allow dynamic-group <dynamic_group_name> to {LOG_ANALYTICS_QUERYJOB_WORK_REQUEST_READ} in tenancy
    allow dynamic-group <dynamic_group_name> to READ loganalytics-log-group in tenancy
    allow dynamic-group <dynamic_group_name> to read compartments in tenancy

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.

Monitor Your Saved Search Scheduled Tasks

You can monitor the health of your saved search scheduled tasks through the metrics Scheduled Task Execution Status. In case of failed or skipped execution of a task due to infrastructure anomaly or if a dependent resource or configuration is modified, the metric provides details of failure to help you to rectify it.

For steps to access the Scheduled Task Execution Status metric, see Monitor Logging Analytics Using Service Metrics.

Each saved search scheduled task has its own interval as specified in its task schedule. A metric is emitted to your tenancy for every scheduled task execution. Hover the cursor on the data points on the chart to view more details about the task. Follow these steps when you want to filter the metric data based on one of the dimensions Status, DisplayName, or ResourceId:

  1. Click the Options menu on the top right corner of the Scheduled Task Execution Status metric, and select View Query in Metric Explorer.

    The metric is now displayed in the Metrics Explorer. Here, you can view the chart in finer detail.

  2. Click Edit Queries and select Dimension Name and Dimension Value for the metric. You can filter the metric data based on taskResult the result of running the scheduled task, Status of task execution, the DisplayName of the task, the queryExecTimeRange, or its ResourceId.


    To view charts and tabular data from Metrics Explorer by specifying a dimension name and a dimension value, avoid using fields that have parentheses or other special characters in the name. If the field selected for the Dimension Name has special characters, then create a virtual field by using eval command or rename the existing field by using the rename command such that the parentheses or special characters are removed. For example, if the field used for Dimension Name is Host Name (Server), then you can create a virtual field hostname with | eval hostname=“Host Name (Server)”.

    The dimension queryExecTimeRange is useful in determining the time taken to run your scheduled task query. The values available are < 5s, >= 5s and < 10s, >= 10s and < 30s, and > 30s. Typically, the queries that take more than 30 seconds to run are considered expensive in terms of execution time. See How to Make Your Queries Performant.

    The dimension taskResult can have values Succeeded, Failed, and Paused. The dimension Status provides further details of taskResult. For example, if the value of taskResult is Paused, then Status value may be Paused by User.

    Click Update Chart to refresh the chart visualization. The chart will now display only the data points for which you applied the filter.

    You can switch to the Data Table view for a tabular representation of the collected data points.

  3. Change the dimension name to view different perspectives in the chart.

The following are the various values of status dimension reported through this metric for specific taskResult values:

taskResult value Status value Description Recommended Fix



The execution of the task is normal



The scheduled task execution is successful but posting the metrics to monitoring service was truncated due to the metric data limits.

Ensure that the metrics remain in the specified limits. See OCI CLI Command Reference - Monitoring Service Metric Data.


When the scheduled task execution is successful but the query returned no results. So there is no metric data posted to monitoring service.

Check your saved search query.

Also, this status may not imply an error. It only suggests that the event for which the query is written has not occurred. For example, if the query is to count the number of Errors in the logs in the last 5 minutes, and if the logs that arrived in the last 5 minutes don't have errors, then SucceededNoDataFound is displayed.



The execution of the task failed due to infrastructure anomaly or recoverable failure.

Contact Oracle Support with the Status information.



The saved search query string or scope filters are not valid.

Check if the saved search was edited after the scheduled task was created, and fix it.


The saved search is deleted or the IAM policy that provides READ permission for the saved search has changed.

Ensure that the IAM policy is restored.


The saved search query is not valid for generating metric.

Check if the saved search was edited after the scheduled task was created, and fix it.


If the scheduled task is for purging log data and the purge compartment is deleted or if the IAM policy for purge has changed after the scheduled task was created, then this status is displayed.

Check if the purge compartment is deleted and restore it.

Ensure that the IAM policy is restored.


Any of the following two reasons can trigger the status:

  • The metric details specified for the scheduled task are incomplete or invalid.
  • The metric result set is invalid, that is, the metric column is not numeric or the dimension value is not cardinal.

If the metric details are incomplete or invalid, then update the metric details in the scheduled task definition.

If the metric column is not numeric or the dimension value is not cardinal, then update the saved search to produce valid metric and dimension.


When the value of taskResult is Paused, this value of the Status is not an indication of the execution of the scheduled task. It is an indication of the user action through the console or API, which paused the scheduled task.

Identify the user action which paused the execution of the scheduled task and run the scheduled task.

Important Factors for Creating Scheduled Tasks

Make note of the following factors for creating scheduled tasks:

  • Requirements for Composing Queries:

    When you compose queries to create Scheduled Tasks, ensure to comply with the following requirements:

    • Refrain from performing wild card search on the field Original Log Content in your scheduled task query. For more information on wild card searches, see Use Keywords, Phrases, and Wildcards.

    • Maximum number of fields supported for the by clause is 3.

    • Maximum number of fields supported for timestats command is 3.

    • The command regex must not be used on large fields like Message to avoid making the queries expensive for processing.

    • The commands which are not supported in the queries for scheduled tasks are addfields, cluster, clustercompare, clusterdetails, clustersplit, compare, createview, delta, eventstats, fieldsummary, highlightgroups, geostats, linkdetails, map, nlp and timecompare.

    • Maximum number of supported aggregate functions in a scheduled task query is 1.

    • timestats command cannot be followed by eval, extract, jsonextract, xmlextract and lookup.

  • Late Arrival of Logs:

    If the scheduled tasks run before the arrival of the logs, then the scheduled tasks may not return the results as expected. To avoid missing such logs in the scheduled tasks due to their late arrival, the query must account for it by using an adjustment to the time range.

    For example, if the scheduled task runs every 5 minutes to check for the number of authentication errors and if there is a 3 minute delay between the time the logs are generated and the time they reach Oracle Logging Analytics, then the scheduled task will not detect the logs. Consider that the scheduled task runs every 5 minutes at say, 01:00, 01:05, 01:10, and so on. If the log record L1 that gets generated at 01:04 reaches Oracle Logging Analytics at 01:07. L1 is not detected in the scheduled task that executed at 1:05 because the log did not arrive at Oracle Logging Analytics at this time. During the next execution at 01:10, the query looks for logs with timestamps between 01:05 and 01:10. In this cycle too, L1 is not detected because it has a timestamp of 01:04. The following query may not see all the logs records if the logs arrive late:

    Label = 'Authentication Error' | stats count as logrecords by 'Log Source'

    To determine the delay in the logs arrival into Oracle Logging Analytics, calculate the difference between the timestamp mentioned in the log record and the Log Processor Posting Time. The following example query can be used to check if there is a delay:

    Label = 'Authentication Error' and 'Log Processor Posting Time (OMC INT)' != null | fields 'Agent Collection Time (OMC INT)', 'Data Services Load Time', 'Process Time', 'Log Processor Posting Time (OMC INT)'

    The following query uses the dateRelative function to adjust for the 3 minute delay in a task that runs at 5 minute interval:

    Label = 'Authentication Error' and Time between dateRelative(8minute, minute) and dateRelative(3minute, minute) | stats count as logrecords by 'Log Source'
  • Other Factors:

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

    • Note the limits information for publishing the metrics data to the Monitoring service. The limits correspond to the metrics for one scheduled task. See PostMetricData API in Oracle Cloud Infrastructure Documentation.

      When your saved search can generate more than 50 unique by field values, partial results are posted due to the limits imposed by the Monitoring service. In such cases, to view the top or bottom 50 results, use the sort command.

Example Queries for Scheduled Tasks

Example Queries for Viewing Metrics

  • Consider an example where you want to know the number of authentication errors in a scheduled run every 5 minutes:

    Label = 'Authentication Error' | stats count as 'Number of Authentication Errors'

    When Summary Table visualization is selected in the Log Explorer, the following output is displayed:

    Log Explorer output for the query

    Whenever the scheduled task executes a metric such as the above, the same will get posted to the Monitoring service.

    From the Metrics Explorer the above posted metric can be viewed as below:

    Metric output for the scheduled task

    Click Show Data Table to view the metric in the tabular format:

    Tabular format of the metric output for the scheduled task

  • If you want to know the break down of authentication errors in each Host:

    Label = 'Authentication Error' | stats count as 'Number of Authentication Errors' by 'Host IP Address (Client)'

    Use the Summary Visualization to preview what a metric output for your query would look like.

    Output of the query in summary visualization

    From Metric Explorer page, the same metric by Host IP chart looks like this:

    Output of the metric by Host IP

    To view the number per Host IP, specify the Metric Dimension name as Host_IP_Address_Client and uncheck the check box Aggregate Metric Streams:

    Dialog box to select the metric dimension name

How to Make Your Queries Performant

Some of the queries lead to high execution times or in some cases timeout and eventually lead to delayed executions of their own tasks. In such cases, it is recommended to create Extended Fields (EFD) or Labels and use them in the filters in your scheduled queries to make the queries less expensive.

For example, if you want to post the number of connection timeouts in your database alert logs every 5 minutes, the following query is one of ways to execute it:

'Log Source' = 'Database Alert Logs' and 'TNS-12535' | stats count as 'Number of Timeouts'

The above query searches for the string TNS-12535 in Original Log Content. However, this is not the most efficient way to search for the timeouts, especially when the task is scheduled to run every 5 minutes scanning through millions of records.

Instead, use the field to which such error ID is extracted and compose the query as shown below:

'Log Source' = 'Database Alert Logs' and 'Error ID' = 'TNS-12535' | stats count as 'Number of Timeouts'

Alternatively, you can filter using the label:

'Log Source' = 'Database Alert Logs' and Label = Timeout | stats count as 'Number of Timeouts'

Oracle-defined log sources have many EFDs and Labels defined in them. For custom logs, it is recommended that you define your own labels and EFDs and use them in the scheduled queries instead of searching in Original Log Content. See Create a Label and Use Extended Fields in Sources.