Oracle Cloud Infrastructure Documentation

Create a Query-based Widget Using Traces

You can create a query-based widget using Application Performance Monitoring traces.

You can use the many features available in the query-based widget builder to create a widget that displays a Trace Query Language (TQL) expression. The query-based widget builder provides you with options and functionalities to visualize and monitor trace data. For example, you can display transactions that scored low on performance when used by many customers, thereby making these transactions worthy of performance improvement efforts.

To create a query-based widget that displays trace data:

  1. Go to the Dashboards page.
  2. Click Create dashboard to create a new dashboard or open an existing dashboard in edit mode.
  3. On the Widgets tab, click the Add widget group and widgets icon (Add widget group and widgets) and click Create query-based widget....
    The query-based widget builder is displayed.
  4. Optionally, click the Open/close filter panel icon (Open/close filter panel) to view the filters already added to the dashboard and make changes, if required.

    Note that when creating a query-based widget to add it to a brand new dashboard, a Compartment filter is automatically added and the compartment input for the new widget being created is linked to this newly added filter.

  5. In the upper-right corner, select a time period for which you want to display data in the widget.
  6. Select Traces in the Data source drop-down list.
    If an APM domain filter is not added to the dashboard, it's automatically added when Traces is selected.
  7. Edit the default query displayed in the Query field or enter a new query and click Run.

    Use TQL syntax to create queries and retrieve trace data from Application Performance Monitoring. For information on TQL, see Work with Queries.

    The trace data is displayed in a tabular format with the name of the service and other details. Below the table chart, another table with the raw data returned by the trace query is displayed and you can click Hide raw data to hide it.

  8. Use the following tabs on the right side to perform tasks such as adding a name for the widget and customizing the visualization of data in the widget:
    Note

    You can click JSON in the upper-right corner to specify or edit the details on the About, Visualization, and Settings tabs, in a JSON editor. The JSON editor provides you with greater flexibility and more options to visualize data in the widget, however, it's recommended that you use it only if you're familiar with editing widget JSON. For more information on the JSON editor, contact Oracle Support.
    • About: Enter a name for the widget, select the compartment in which you want the widget to reside, and add a description for the widget.

      Optionally, click Show advanced options to add free-form or defined tags to the widget. If you have the permissions required to create a widget, then you also have permissions to add free-form tags. To add a defined tag, you must have permissions to use the tag namespace. For information on:

    • Visualization: Select a chart type and customize the visualization by specifying or modifying additional options.

      If you select Table as the chart type, then you have the option of removing some of the columns or select the All columns check box to display all columns. Chart types that have X and Y axes, such as the Line chart have a combination of the following additional visualization options:

      • X axis: Select the data attribute you want projected on the X axis.
      • Y axis: Select the data attribute you want projected on the Y axis. Y axis supports numeric data attributes and only those are listed.
      • Series: Select the data attribute that you want to plot in separate series in the chart. This option is also available for a Pie chart.
      • Size: Select a data attribute to whose values you want to assign size. This option is only available for a Bubble chart.
      • Color by: Select the data attribute to whose values you want to assign distinct colors. Typically, the Color by option is used along with the Series option to assign distinct colors to the separate series. This option is also available for a Pie chart.
      • X axis title: Specify a title for the data attribute projected on the X axis.
      • Y axis title: Specify a title for the data attribute projected on the Y axis.
      • Legend: Specify the location of the legend in the widget. This option is also available for a Pie chart.
      • Correlated tooltips: Select this option to correlate the tooltips across all your query-based widgets in the dashboard.
      • Data cursor: Select this option to view the tooltip when you hover the mouse over the widget.
      • Stacked: Select this option if you want to stack the data attributes displayed in the chart, by color.
      • Use solid color: When you use an Area chart for visualization, the area that represents the presence of data is covered in solid color. This option is selected by default.

      For more information on the visualization options in a query-based widget builder, see About Visualization Options.

    • Settings: Review and edit widget inputs, if required.
  9. Click Save to save the widget in the widget library and add it to the dashboard.

Here's a scenario in which the top 5 transactions in the specified time period are displayed using a line chart. In the query-based widget builder:

  1. Ensure that the time period is selected in the upper-right corner.
  2. In the Data source drop-down list, select Traces.
  3. In the Query field, enter the following trace and click Run.
    show traces OperationName as Transaction, avg(traceDuration) as Duration where pageviews > 0 group by OperationName order by count(*) first 5 rows timeseries
  4. Specify the following on the Visualization tab:
    1. Select Line chart as the Chart type.
    2. Select timeseries.Duration in the Y axis drop-down list.
    3. Select timeseries.date in the X axis drop-down list.
    4. Select Transaction in the Series drop-down list.
    5. Select Transaction in the Color by drop-down list.

A line chart with the top 5 transactions is displayed.

Query-based Trace Widget