Create and manage custom reports

Custom reports enable you to drill-down into specific API metrics and view the exact data that you want to see. You can create a custom report by using any of the metrics and dimension built into Edge. In addition, you can attach the StatisticsCollector policy to your API proxies to collect custom metrics, such as user or product ID, price, REST action, target version, target URL, and message length.

Watch a video to learn how to create custom reports using the classic Edge UI.

Watch a video to learn how to create custom reports using the New Edge experience UI.

About custom reports

When building a custom report, you'll select the data you want to see (metrics), group the data in meaningful ways (dimensions), and optionally limit the data returned based on specific characteristics (filters) of the data.

You can also set the chart type displayed in the custom report as a column or line chart. The following images show chart examples for the transactions per second metric grouped by the API proxy dimension:

  • Column - each API proxy is represented by a different column:

    Custom column chart

  • Line - each API is represented be a different line:

    Custom line chart

Setting metrics and dimensions

The metrics you choose for your custom report specify the data that you are trying to measure. The metrics data is displayed on the y-axis of the chart shown in the custom report. Common metrics include:
  • transactions per second
  • response time
  • policy errors

Some metrics let you set an aggregation function to run against the metric. For example, you can use the following aggregation functions with the response time metric:

  • avg: Returns the average response time.
  • min: Returns the minimum response time.
  • max: Returns the maximum response time.
  • sum: Returns the sum of all response time.

Not all metrics support all aggregation functions. The documentation on metrics contains a table that specifies the metric name and the function (sum, avg, min, max) supported by the metric.

The dimension specifies how to group the metrics data. For example, you want to create a custom report showing the response time metric. You can use dimensions to group the metrics data by API product, API proxy, or developer email to obtain:

  • The response time per API product
  • The response time per API proxy
  • The response time per developer email

The way the dimension is displayed in the chart of the custom report depends on the chart type:

  • Column: The dimensions are dispalyed along the x-axis of the chart, where each column corresponds to a different value of the dimension.
  • Line: Each line in the chart corresponds to a different value of the dimension, and the x-axis represents time.

Creating custom metrics and dimensions

Add the StatisticsCollector policy to your API proxies to collect custom analytics data, such as user or product ID, price, REST action, target version, target URL, and message length. The data can come from flow variables predefined by Apigee, request headers, query params, or custom variables that you define. Once the data has been collected, you can then create a custom report to view that data.

The way you dispay the custom anayltics data in a custom report depends on its data type:

  • For data of type string, reference the statistical data as a dimension in a custom report.
  • For numerical data types (integer/float/long/double), reference the statistical data in a custom report as either a dimension or a metric.

See the StatisticsCollector policy for examples of collecting custom analytics data.

Setting filters

A filter lets you limit the metrics data displayed in the custom report by setting specific characteristics on the metrics data to return. For example, you can create a filter so that you see metrics data only for a response time greater than a specific value or only for an API proxy with a specific name.

Filters use a conditionl syntax that lets you build complex filters using operators such as eq, ne, gt, lt, and more.

Custom report examples

In the simplest type of custom report, you specify a single metic and a single dimension. For example, you define a custom report with the following settings:

  • type = Column
  • metric = Average Transactions per Second
  • dimension = Proxy

The custom report contains a column chart with the Average Transactions per Second metric displayed along the y-axis, and the data grouped by the API proxy dimension along the x-axis:

Custom report tps

You can add multiple metrics to a custom report. For example, you define a custom report with two metrics:

  • type = Column
  • metric = Average Transactions per Second
  • metric = Policy Errors
  • dimension = Proxy

The custom report contains a separate chart for each metric, where each metric is displayed on the y-axis of a chart. The x-axis is the same for both charts to show each API proxy as a column:

Custom report two metrics

You can add multiple dimensions to a custom report. For example, you define a custom report with the following settings that includes two metrics and two dimensions:

  • type = Column
  • metric = Average Transactions per Second
  • metric = Policy Errors
  • dimension = Proxy
  • dimension = Developer ID

The chart initially shows the metrics grouped by Proxy, the first dimension specified when you created the custom report:

Custom report two dimensions

You can then use the Proxy dropdown, corresponding to the first dimension, to select an individual proxy. The updated chart now shows the metrics for the selected proxy by Developer ID:

Custom report two dimensions drill down

As you add more and more dimensions to the custom report, the UI adjusts to let you drill down into the report by each dimension.

Viewing all custom reports

View a list of all custom reports by selecting Analytics > Reports from the main menu. The custom reports page displays all custom reports that have been created for your organization, as shown in the following figure:

Custom reports dashboard

As highlighted in the figure, the custom reports page enables you to:

  • View a list of all custom reports.
  • Add a custom report.
  • Run a custom report by clicking its name in the list. The report is run using the data collected over the last hour by default and the data is displayed in the custom report dashboard. See Exploring the custom reports dashboard.
  • Search the list of custom reports by entering all or part of a relevant string in the search box; all displayed fields are searched for the string.
  • Manage custom roles to manage access to a custom report.
  • Delete a custom report.

Exploring the custom report dashboard

The custom report dashboard displays the results of your custom report for a specific time range, including the column or line chart of the specified metric:

Custom reports dashboard

The custom report dashboard enables you to:

  • View custom report data for selected time range.
  • Select the Environment for which you want to view custom report data.
  • Select a specific dimension to filter the custom report data. This area is only enabled when you specify multiple dimensions to the report.
  • Select the Chart or Table view.

  • Analyze a specific metric by selecting Analyze in the table row of the associated metric. View anomalies, and compare it to a previous period or to other metrics.
  • Run the custom report by clicking and setting the time range.
  • Download the custom report.
  • Edit the custom report.

Explore the metric analysis dashboard

If you select the Analyze button in a summary table row, the following charts appear (the top chart only appears if you configured the report to use multiple metrics):

Analyze metric

These charts display the following information:

  • Compare to Metric: If you configured the report to use multiple metrics, compare the metrics to each other.
  • Compare to Previous Period: View the metric for the previous time period. For example, if you chose to view the custom report for the last 24 hours, then this chart show the data for the previous 24 hour period.
  • Analyze Anomalies: Displays any outlying data points in the report data. This chart displays two values:

    • The moving average of the metric displayed as a line. For a given point on the line, the value of the moving average is calculated as the average of: the metric value at that point in time and the values of the metric for the two previous data points.
    • The blue area of the chart defines the average max and average min values of the metric. The average max is 1.2 * (moving average), and average min is 0.8 * (moving average).

    If the moving average is out of the range of the average max or average min, it is considered a possible anomaly and drawn as a red dot on the chart.

Adding a custom report

By adding custom reports, you can create a set of charts that provide insight into every aspect of your API program.

After you add the custom report, you must run it synchronously or asynchronously.

To add a custom report:

  1. Select Analytics > Reports.
  2. Click + Custom Report.
  3. In the Basic section, enter the following information:
    Field Description
    Report Name Name of the report.
    Report Description Description of the report.
    Chart Type Select the style of chart to use to present your custom analytics data.
    • Column: X-axis represents groups designated by dimensions.
    • Line: X-axis represents time.
  4. In the Metrics section:
    1. Select the metric that you want to analyze.
    2. Select an Aggregate Function to display the Sum, Average, Min, or Max values.
    3. Click + Metric to add additional metrics.
  5. In the Dimensions section, click + Dimension and select a dimension, such as "Proxy", to constrain the data set used to generate the reports. You can add additional dimensions to further constrain the data.
    Dimension
  6. In the Filters section, further narrow the data displayed by adding filters to your report definition. For example, you could add a filter that excludes data for the weather API proxy or developer jane@example.com.
    1. Click + Filter Condition and select the entity you want to filter on, and construct an expression with the Operator and Value to include or exclude data in the report.
    2. Click checkmark icon to save the filter.
    3. Click + Filter Condition to add additional filters, and select an AND or OR connector.
  7. Click Save.

The report is run using the data collected over the last hour by default and the data is displayed in the custom report dashboard. See Exploring the custom reports dashboard.

Running a custom report

Edge Analytics lets you run a report synchronously or asynchronously.

  • For a synchronous report, you run the report request and the request is blocked until the analytics server provides a response. However, because a report might need to process a large amount of data (for example, 100's of GB), a synchronous report might fail because of a time out.

    A synchronous report can have a maximum time range of 14 days. If you select a time range of 15 days or greater, then the report is always run asynchronusly.

  • For an asynchronous report (Beta), you run the report request and retrieve the results at a later time. Some situations when asynchronous query processing might be a good alternative include:

    • Analyzing and creating reports that span large time intervals.
    • Analyzing data with a variety of grouping dimensions and other constraints that add complexity to the query
    • Managing queries when you find that data volumes have increased significantly for some users or organizations.

    An asynchronous report can have a maximum time range of 6 months.

    This document describes how to intiate an asynchronous report by using the UI. You can also use the API, as described in Using the asynchronous custom reports API.

To run a custom report for a specific time range:

  1. Select Analyze > Report from the left navigation bar to open the Custom Reports page
  2. Select the report to run to open the Custom Report Time Selection pop up. Time Range
  3. In the Range dropdown, select either:
    • A predefined time range, such as Last Hour or Last 7 Days.
    • Custom Range. For a Custom Range, select a start date, duration, and time unit (if applicable) in the drop-down, or use the calendar to select start and end dates.

      Select Single Date to restrict the date selection in the calendar to a single date.

  4. To run the report, select one of the following in the Run Report dropdown:
    • Run Report to run the report synchronously. The results will be displayed in the custom report dashboard after the report completes. If the report takes longer than 60 seconds to run, it will be converted automatically into an asynchronous report.

    • Submit Job (Beta) to run the report asynchronously as a background job. The following dialog appears:

      Asynch submit

      Click View Status in the dialog to view the status of the custom report job.

(Beta) Viewing asynchronous custom report jobs

To view asynchronous custom report jobs, select one of the following:

  • Click View Status in the Report Submitted as Background Job dialog.
  • Select Analyze > Report Jobs from the left navigation bar.

The Report Jobs page is displayed, as shown in the following figure:

Report jobs

The Report Jobs page enables you to:

  • View all asynchronous custom report job results that have been submitted in the last 7 days.

  • Select the environment for which you want to display custom report jobs.

  • To view the custom report, make sure its Status is completed. Then move the mouse over the row corresponding to the report. An View report and a Download report icon appear. Selcet the View report to view the report.

  • Download the custom report by clicking Download report.

    The full report is downloaded as a ZIP file named OfflineQueryResult-xxx.zip which contains the CSV files.

  • Search the list of custom reports by entering all or part of a relevant string in the search box; all displayed fields are searched for the string.

Downloading a synchronous custom report

To download a synchronous custom report as a CSV (comma-separated value) format:

  • In the custom report dashboard:
    • Click Combined CSV to download the full report. The file is named as follows: customreportname.csv, where customreportname is the custom report name converted to all lower-case, with spaces replaced by underscores. For example: proxyerrorstargeterrors.csv.
    • Click CSV associated with a specific dimension. The file is named as follows: dimension.csv, where dimension is the dimension name with spaces replaced by underscores. For example: sum_of_proxy_errors.csv.

Editing a custom report

To edit a custom report:

  1. View all custom reports.
  2. Click the name of the report that you want to edit.
    The custom report is run against data collected for the last hour and the results are displayed.
  3. Click Edit on the custom reports dashboard.
  4. Edit the custom report details.
  5. Click Save.
You are returned to the custom report results.

Deleting a custom report

To delete a custom report:

  1. View all custom reports.
  2. Click Delete in the Actions column for the custom report you want to delete.
  3. Click Delete to confirm the delete operation.

Managing custom roles for a custom report

From the custom reports page you can view and edit custom roles that are defined for a custom report by clicking Roles in the Actions column for the custom report.

Click Edit to edit the custom role settings.

For information about assigning custom roles to a user, see Assigning roles.