Creating and managing custom reports

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

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 dimensions built into Apigee.

There are two types of custom reports:

• Real-time reports (also called synchronous reports): When you specify the report parameters in the Apigee UI, real-time reports are displayed in the Apigee UI within a couple of minutes.
• Report jobs (also called asynchronous reports): For custom report jobs you request the report and retrieve the results at a later time.

See Real-time reports versus report jobs.

Availability of custom reports

If you are an Apigee Subscription customer, access to Apigee API Analytics and the custom report functionality is included in your subscription entitlements and automatically enabled for each of your Apigee environments.

If you are a Pay-as-you-go customer, you must enable Apigee API Analytics as a paid add-on to access analytics and generate custom reports. For more information on enabling the Apigee API Analytics add-on for your Intermediate or Comprehensive Apigee environments, see Manage the Apigee API Analytics add-on.

If you are unsure whether you are using a Subscription or Pay-as-you-go Apigee organization, contact your Apigee organization administrator.

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:

  

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

  

Setting metrics and dimensions

The metrics you choose for your custom report specify the data you are trying to measure. Common metrics include:

• Transactions per second
• Response time
• Policy errors

In addition to the standard metrics and dimensions, you can also create custom reports for custom data you collect using the DataCapture policy. See Collecting custom data with the DataCapture policy.

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

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 (which can also be the AppGroup Id) 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: Each column corresponds to a different dimension value.
• Line: Each line in the chart corresponds to a different dimension value, and the x-axis represents time.

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.

You can build complex filters using conditional syntax and operators such as eq, ne, gt, lt, and more.

Custom report examples

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

• type = Column
• metric = Average transactions per second
• dimension = API Proxy

The custom report contains a column chart with the "Average transactions per second" metric data grouped by the API proxy dimension:

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 = API Proxy

The custom report contains a separate chart for each metric:

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 = API Proxy
• dimension = Request verb

Real-time reports versus report jobs

Apigee Analytics lets you run a real-time report or a report job.

• For real-time reports, you request the report and it is displayed as soon as 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 real-time report might fail because of a time out.

  A real-time report can have a maximum time range of 92 days. If you select a time range greater than this, the report is run as a report job.

  See Run a custom report.

• For a report job, you request the report and retrieve the results at a later time. Some situations when a report job 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.
  Note: Report jobs have the following limits:

  • Maximum time range is 365 days.
  • 32 MB size limit on the results of a query.

  You can also run a report job using the API, as described in Using the asynchronous custom reports API. See View a report job.

Open the Custom Reports page

Note: There is a new version of the Apigee UI, which is integrated with the Google Cloud console. The new UI is called Apigee in Cloud console. The instructions in the first two tabs below explain how to use either Apigee in Cloud console or classic Apigee.

Apigee in Cloud console

To open the Custom Reports page:

1. Open the Apigee UI in Cloud console.
2. Select Analytics > Custom reports.

This displays the Custom Reports page, as shown below.

The Custom Reports page has two tabs:

• Reports: Displays real-time reports.
• Report Jobs: Displays report jobs.

See Real-time reports versus report jobs.

Both tabs display a list of the reports or report jobs that have already been created. To view a report or report job, click the name of the report. See Run a report for an example.

Reports

The Reports tab displays the following information about each report:

• Display Name: The name of the report.
• Dimensions: The dimensions included in the report.
• Metrics: The metrics and aggregation functions (such as sum) included in the report.
• Last Modified: The last time and date when the report was run.

Report Jobs

The Report Jobs tab displays the following information about each report job:

• Report Name: The name of the report.
• Start Time Range (UTC): The start time of the report job.
• End Time Range (UTC): The end time of the report job.
• Status: The status of the report job, which can be running, completed, or expired.
• Submitted: The date and time when the report job was submitted.

The Custom Reports page enables you to:

• View a custom report and report job.
• Create a custom report or report job.
• Run a report.
• Edit a custom report or report job.
• Delete a custom report or report job.

Note: Data delay interval
After API calls are made to proxies, it may take up to 10 minutes for the data to appear in dashboards, custom reports, and management API calls.

Classic Apigee

To open the Custom Reports page:

1. Sign in to Apigee UI.
2. Select Analyze > Custom Reports > Reports.

The custom reports page displays all custom reports that have been created for your organization, as shown in the following figure:

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

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.

  Note: If your custom report includes many rows in the Summary table at the bottom of the report, click Table to view the tabular information only. In the table view, use the Show up to drop-down to control the number of rows to display in the table. You can display up to 200 rows at a time.
• Analyze a metric by selecting the icon 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 as a CSV file. The file is named as follows: metric.csv. For example: Average_of_total_response_time.csv.
• Edit the custom report.

Note: Data delay interval
After API calls are made to proxies, it may take up to 10 minutes for the data to appear in dashboards, custom reports, and management API calls.

Create a custom report

This section explains how to create a custom report.

Note: Free and trial accounts cannot create custom report jobs. For more information, see Apigee pricing plans.

Apigee in Cloud console

In the Custom Reports page, you can create either a real-time report or a report job. To do so:

1. Open the Custom Reports page.
2. Click + Create.
3. • To create a real-time report, select Custom Report.
   • To create a report job, select Custom Report Job.
4. In the Basic section, enter the following information:
   • Report Name: Name of the report.
   • For a real-time report only, you can also enter an optional Description of the report.
5. The following sections depend on whether you are creating a real-time report of a report job:
   • For real-time reports only:

     After Chart Type, select the style of chart to present your data:

     • Column: X-axis represents groups designated by dimensions.
     • Line: X-axis represents time.

   • For report jobs only:
     • Report Details: In the Environment field, select the environment in which you want to run the report. Note that for real-time reports, you can select the environment in the report page, after the report has run.
     • Report Date Range: Select the Start time and End time for the report.

       Note: The maximum date range for a report job is 365 days. For reports requiring date ranges precise to the second, use the Custom Reports API to create the report job. The API accepts date range inputs that include seconds.

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

   Note: In addition to the standard metrics and dimensions, you can also select metrics or dimensions corresponding to custom data collected with the DataCapture policy.

7. In the Dimensions field, 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.

8. In the Filter section, you can 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 [e-mail].

   First, click Add a Filter to open the New Filter section.

   1. Select the name of the entity you want to filter on, which can be a metric or a dimension.
   2. Select an operator such as = or !=, and a Value.
   3. Enter a value for the metric or dimension.
   4. Click Done to add the filter.
9. Click Save to save the report.

Classic Apigee

To add a custom report:

1. Open the Custom Reports page.
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. Click the icon for Metrics.
   2. Select the metric that you want to analyze.
   3. Select an Aggregate function to display the Sum, Average, Min, or Max values.
   4. Click Save.
   5. Click the icon to add additional metrics.

   Note: In addition to the standard metrics and dimensions, you can also select metrics or dimensions corresponding to custom data collected with the DataCapture policy.

5. In the Dimensions section, click 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.

6. In the Filter 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 [e-mail].

   1. Click and select the Name of the entity you want to filter on, an Operator such as = or !=, and a Value.
   2. Click Add to save the filter.
   3. Click to add additional filters, and select an AND or OR connector.
7. Click Save to save the report.

Run a report

Apigee in Cloud console

To run a real-time report:

1. Open the Custom Reports page.
2. In the Reports tab, select the report to run.

When the report is ready, it is displayed as shown below.

The report displays a chart of the data and a summary table.

Note: The report only displays one dimension at a time. If the report has multiple dimensions, you can select the dimension to display in the Dimension field.

In the report page, you can select the following options for the report:

• Environment: The environment in which to run the report.
• A time period for the report.
  Note: The maximum time range for a custom report is 92 days. To create a report with a longer time range, you must submit it as a report job.
• Dimension: A dimension for the report. Only one dimension can be displayed at a time.
• Value: A specific value for the dimension, or All to display all values.

You can also choose the following options at the top of the report page:

• Edit: Edit the details of the report.
• Export: Download the data for the report in a CSV file.
• Submit Job: Submit the report as a report job. When you click Submit Job, a dialog opens giving you the options that are described in Create a custom report. After you have entered the options, click Create to create the report job.

Note: Custom ranges cannot exceed 92 days for real-time custom reports and 365 days for report jobs.

See View a report job for more information about report jobs.

Classic Apigee

To run a custom report for a specific time range:

1. Access the Custom Reports page.
2. Select the report to run. By default, the report displays data for the previous hour.

   Note: If the report takes longer than 60 seconds to run, it will be converted automatically into a real-time report.

3. To run the report for a different time range:

   1. Click in the time range area at the top of the report to open the Custom Report Time Selection pop up.
   2. Select either:
      • A predefined time range, such as Last Hour, Yesterday, or Last 7 Days.

      • A Custom Range by selecting a From/To date and time, or use the calendar to select start and end dates. Click UTC to use Universal Time Coordinated (UTC).

        Note: Custom ranges cannot exceed 92 days for synchronous custom reports and 365 days for report jobs.
   3. To run the report, select one of the following:

      • Apply to run the report. The results will be displayed in the custom report dashboard after the report completes.

      • Submit Job to run the report as a report job. The following dialog appears:

        

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

View a report job

Apigee in Cloud console

To view a report job, select the Report Jobs tab at the top of the Custom Reports page.

The Report Jobs tab is displayed, as shown below:

The Report Jobs page enables you to:

• View all report jobs that have been submitted in the last 7 days.

  Note: Report jobs results are deleted after 7 days.

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

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

To view the custom report, make sure its Status is completed. Then click the report name to view the report.

Note:

You cannot view a report job that:

• Is still running.
• Exceeds the maximum view size of 2MB.

Classic Apigee

To view report jobs, select one of the following:

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

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

The Report Jobs page enables you to:

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

  Note: Report job results are deleted after 7 days.

• Select the environment for which you want to display 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 and a icon appear. Select the to view the report.

  Note:

  You cannot view a report job that:

  • Is still running.
  • Exceeds the maximum view size of 2MB.
  • Contains no data (0 MB).

• Download the custom report.

Edit a custom report

Apigee in Cloud console

To edit a custom report:

1. Open the Custom Reports page.
2. Click the three-dot menu under Actions.
3. Select Edit. This opens the Edit custom report dialog, where you can edit the options for the report. The options are described in Create a custom report.
4. Click Update to save your changes.

Classic Apigee

To edit a custom report:

1. Open the Custom Reports page.
2. Move the mouse over the name of the report that you want to edit. The edit and delete icons appear on the right side of the page.
3. Click the edit icon.
4. Edit the custom report details.
5. Click Save.

You are returned to the custom report results.

Delete a custom report

Apigee in Cloud console

1. Open the Custom Reports page.
2. Click the three-dot menu under Actions.
3. Click Delete to delete the report.

Classic Apigee

To delete a custom report:

1. Open the Custom Reports page.
2. Move the mouse over the name of the report that you want to edit. The edit and delete icons appear on the right side of the page.
3. Click the delete icon to delete the report.