Oracle Cloud Infrastructure Documentation

Configure a Background Query

You can create a query, run it in the background and see the query results at a later time in Trace Explorer.

Creating a query and running it in the background is useful when you have a query that may take some time to get executed. The query status and results can be retrieved at a later time.

To run a background query:
  1. Navigate to the Trace Explorer page.
  2. Ensure that the appropriate compartment and APM domain are selected.
  3. Click the dropdown menu located next to Run and select Run query in background.

    Figure 5-1 Run query in background

    Run query in background
    The Run in background window is displayed with the following options:
  4. Click Submit once completed.

View Background Queries

After creating a background query, select View background queries to view the list of queries that were initialized earlier and their results.

You can see information about the background queries such as Instances, Status, Total rows, Schedule and Expires.

Note

After the expiration time is reached, the query results saved from a background query are no longer accessible. The query name and text of the background query are preserved as an expired query.
Use the Actions icon (Actions icon) to perform the following:
  • Edit details: Edit a background query details. For example, if you need to extend the expiration date of the background queries, update the Expires field. The default Expires value is 30 days.
  • Fetch query results: See a background query result.

    Option not available for Aggregated Query.

  • New query from attributes: Refine the results of a background query by making changes to the existing query. For example, if you want the results to return less rows, you can add a where clause with an attribute.

    Also, query result data can be used as the source for other queries (similar to nested queries). This tool can help construct those queries.

  • Re-run query: Re-run a background query. It means that the existing query result data gets deleted and the new query gets created using the same name.
  • Delete: Delete a background query.

Single Run

You can create a single query to run in the background and get the query results saved as a background query.

Use Single run if you have a query that may take some time to get executed and require to run it only once (you don't need to run it multiple times).

In the Single run tab, do the following:

  1. Query Name: Enter a name for the query.
  2. Description: Optionally, enter a description for the query.
  3. Query: Create a new query or edit the existing one.
  4. Time range: Select the required time range.
  5. Maximum run duration in minutes: Enter the maximum run duration in minutes.
  6. Maximum rows per run: Enter the maximum rows per run.
  7. Expiration time amount: Enter the expiration time amount.
  8. Expiration time type: Enter the expiration time type.
  9. Click Submit.

Repeat Run

You can create a repeat query to run in the background using a custom schedule and get the query results saved as a background query.

Use Repeat run if you have a query that may take some time to get executed, and require to run it multiple times at a specific interval. Use it to update the query result at a known interval. For example, a summary of last week data updated every Monday morning.

The query results get replaced after every run.

In the Repeat run tab, do the following:

  1. Query Name: Enter a name for the query.
  2. Description: Optionally, enter a description for the query.
  3. Query: Create a new query or edit the existing one.
  4. Under Configuration, set the following:
    • First run time: Select the required time for the first run.
    • Maximum run duration in minutes: Enter the maximum run duration in minutes.
    • Maximum rows per run: Enter the maximum rows per run
  5. Under Scheduling, select one of the following:
    • Repeating interval
      1. Repeat every: Select the repeat time amount and specify the Repeat type for it.
      2. Query period relative to scheduled run time: Select the query period relative to scheduled run time and specify the Repeat type for it.
    • Cron scheduling
      1. Cron expression:

        Enter the values to create a cronjob expression based on a string of five fields separated by a blank space with the following syntax:

        S1 S2 S3 S4 S5
        For example, the below shows a cronjob that runs at 23:10 on the 15th day of any month.
        10 23 15 * *
      2. Query period relative to scheduled run time: Specify when the query starts.
  6. Click Submit.

Aggregated Query

You can create an aggregated query to run in the background using a repeat query and get the cumulative query results saved as a background query.

Use Aggregated query if you have a repeat query that may take some time to get executed, and require to continually query the cumulative results. The query results get added to the previous result after every run.

Use Aggregated query to create custom entities based on aggregation of spans or traces. This is useful in cases where the ingest volume is very high and you need to present a summary/aggregation of millions of spans in a dashboard.

  1. Query Name: Enter a name for the query.
  2. Description: Optionally, enter a description for the query.
  3. Query: Create a new query or edit the existing one.
  4. Under Configuration, set the following:
    • First run time: Select the required time for the first run.
    • Maximum run duration in minutes: Enter the maximum run duration in minutes.
    • Maximum rows per run: Enter the maximum rows per run.
  5. Under Aggregation, set the following:
    1. Repeat every: Select the repeat time amount and specify the Repeat type for it.
    2. Days to retain data: Enter the number of days to retain data.
  6. Click Submit.

Example:

The following background aggregate query can be created first and used to summarize data per user:
show traces userName, time_bucket_start(60) as timeBucket, 
sum(ApdexScore) as apdex, sum(PageViews) as pageViews, 
count(*) as "count", 
sum(PageResponseTime) as totalResponseTime, percentile(PageResponseTime,90) as P90, 
count_distinct(sessionId) as sessions, sum(ErrorCount) as errorCount 
where pageViews > 0 and userName is not omitted 
group by userName, time_bucket_start(60)
After, you can use the following aggregate query to chart average number of sessions per user over time:
show from query result User avg(sessions) 
timeseries time range using attribute timeBucket