Nav

Analytics Event API

API Manager gathers powerful analytics data for each API that is managed using the platform. This data is displayed visually in your API’s dashboard, but many scenarios require access to the raw data so that it can be analyzed or transformed. To meet this need, the Analytics Reporting API makes it easy to create a report that queries the desired data and exposes it via an API endpoint. You can also create reports that span more than one API, or create different reports for the same API.

Creating a Report

The following steps show you how to create a report.

  1. As an Organization Administrator, you have access to the Analytics Dashboards for your organization. Go to http://anypoint.mulesoft.com/analytics to access your Analytics Dashboards. You can also click Analytics in the drop-down menu in the top-right of the window.

    analytics-access

  2. On the top menu, click Manage Reports.

  3. On the Manage Reports page, click New to create a new report.

  4. On the Create Report page, select your desired data source, range, format, and fields. A URL generates for the configured report, which represents the endpoint that can be called. Anypoint Analytics displays the starting date that data is available for the Data Source.

    anev_create_report_2

  5. Click Save Report to save the report and make it available at the specified endpoint. You are redirected to the Manage Reports page.

Running a Report in the Browser

The following steps show you how to run a report from the Manage Reports page in the dashboard. Anypoint Analytics lists the starting point for when data is available for the API, including a warning message if no data is available for the API.

  1. On the Manage Reports page, click Run for the specified report.

    anev_running_report

  2. After the report has finished running, the resulting file is saved in the data format that was selected when the report was created. For example, ShippingAPI Usage.csv. This file contains all of the raw analytics data for the parameters you specified in the report.

Calling a Report Programmatically

The following steps show you how to call the report’s API endpoint and programmatically retrieve the analytics data.

These instructions use curl for OS X or Linux. If you’re using Windows, you can use PowerShell to accomplish the same tasks.

Get the Organization ID

To use the curl commands listed below, you need your organization ID.

To get your organization ID:

  1. Log into Anypoint Platform.

  2. Click Access Management.

  3. In the Organization display, click your organization’s name:

    analytics-org-name

  4. In the address bar above the Organization Info window, copy the organization ID value from the address bar.

    analytics-orgid.png

    In this example, the organization ID is: 42424242-4242-4242-4242-424242424242

Use curl to View Report Information

To view report information programatically:

  1. Open a new terminal window and execute the following command:

    TOKEN=$(curl -s https://anypoint.mulesoft.com/accounts/login -d "username=<YOUR-USERNAME>&password=<YOUR-PASSWORD>" | jq -r .access_token)

    The value of $TOKEN is taken from running the curl command line. This requires getting the access_token JSON property of this response.

    The authorization header has the form: Authorization: Bearer {$TOKEN.access_token}

    The use of the jq command is one possible solution for obtaining the access token value. Download and install this application or one with the same functionality before using the curl command.

  2. This command sends a request to the authentication servers of the Anypoint Platform and, if the request is successful, returns an access token that’s stored in the $TOKEN variable. The value of this variable is displayed below:

    
                 
              
    1
    2
    3
    4
    5
    
    {
     "access_token": "54545454-5454-5454-5454-545454545454",
     "token_type": "Bearer",
     "redirectUrl": "/accounts/#/cs/profile/home"
     }
  3. Once the access token has been received, it must be appended to the Authorization header in the request to the Analytics Reporting API endpoint for your report. To make a request to this endpoint, copy it from the Manage Reports page in the Analytics dashboard. Using the $TOKEN variable from the previous step, include it in the next request as shown below (replace <ORGANIZATION_ID> with your organization ID):

    curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com/analytics/1.0/<ORGANIZATION_ID>/events?format=csv&startDate=2016-01-01&endDate=2016-12-31&fields=Application%20Name.Client%20IP.Resource%20Path > output.csv"
  4. If the request is successful, the response includes a CSV file (as requested) that downloads as a file with the specified name (output.csv) in the directory where the curl request was made.

An example shell script combining the two curl commands and which displays values in the command prompt window is:


          
       
1
2
3
TOKEN=$(curl -s https://anypoint.mulesoft.com/accounts/login -d "username=myusername&password=mypassword" | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com/analytics/1.0/42424242-4242-4242-4242-424242424242/events?format=csv&startDate=2016-01-01&endDate=2016-11-10&fields=Application%20Name.Client%20IP.Resource%20Path"
echo;echo

Example output for this command is:


          
       
1
2
3
4
"Application Name","Client IP","Resource Path",Timestamp,"API ID","API Version ID","API Name","API Version Name"
"Las Vegas T-Shirt serviceLas Vegas T-Shirt serviceLas Vegas",83.178.96.0,/,2016-10-03T04:27:02.072Z,61460,63811,"test api contracts",1
"Las Vegas T-Shirt serviceLas Vegas T-Shirt serviceLas Vegas",83.178.96.0,/,2016-10-03T05:03:38.774Z,61460,63811,"test api contracts",1
  ...

Command Options

The following options can be added to the curl command:

Option Description

apiIds

Comma-delimited list of API IDs to include in a query. Omit or specify all or * to include all APIs.

Type: string
Required: no
Example: appIds=42,54

apiVersionIds

Comma-delimited list of API version IDs to include in query. Omit or specify all or * to include all API versions. Ignored if no value was specified for API IDs.

Type: string
Required: no
Example: apiVersionIds=42,54

countOnly

When this field is present and set to true, only the number of events that a given query returns is returned. This is particularly helpful when paginating a response. The format of the response depends upon the format field.

Type: boolean
Required: no
Example: countOnly=true

duration

The duration over which the report should return data. Consists of an integer number denoting quantity and a single-letter suffix denoting units.

Suffix is one of:

  • d: Days

  • h: Hours

  • m: Minutes

  • s: Seconds

To cover a duration of one week, specify 7d as the duration. To cover half a minute, specify 30s.

Type: string
Required: no
Example: duration=45m

fields

Fields to include in the report. Required for CSV output and optional for JSON output. If omitted for JSON output, the default is all fields. The list of fields can be comma- or period-delimited. Use %20 for spaces. You can use any value in Data Fields for Reports. Timestamp, API Name, API ID, API Version, API Version ID are always included.

Type: string
Required: no
Example: fields=Hardware%20Platform.Client%20IP.Resource%20Path

format

Determines the serialization format of the returned data. Either csv or json.

Type: string
Required: yes
Example: format=csv

maxResults

Maximum number of events to return. Default value is 10000. Specify -1 to return all results.

Type: integer
Required: no
Example: maxResults=3

startDate

Starting date and time, as described by the ISO Date Time Parser.

Type: date
Required: no
Example: startDate=2016-01-01T08:15:30-05:00

endDate

Ending date and time, as described by the ISO Date Time Parser.

Type: date
Required: no
Example: endDate=2016-11-10

pathPrefix

Filter results by event resource path, used when reporting against a particular REST resource root.

Type: string
Required: no
Example: pathPrefix=/products/electronics

Data Fields for Reports

Your report can query data for one, many, or all of the available data fields. These fields are explained in the table below.

Data Field Name Description

Application

Client ID associated with the incoming API request.

Application Name

Name of the application making the API request (only available when a client ID is passed with the request).

Browser

Browser type associated with the incoming API request.

City

The city from which the API request originated (inferred by the IP address of the client).

Client IP

IP address of the client making the API request.

Continent

The continent from which the API request originated (inferred by the IP address of the client).

Country

The country from which the API request originated (inferred by the IP address of the client).

Hardware Platform

The hardware type of the client making the request (such as Mobile, Tablet, Desktop, etc.).

Message ID

Message ID value.

OS Family

The client OS type: Mac OS X, iOS, Windows, Linux.

OS Major Version

Operating system major version.

OS Minor Version

Operating system minor version.

OS Version

Operating system version.

Postal Code

The postal code from which the API request originated (inferred by the IP address of the client).

Request Outcome

Indicates whether a request was successful or resulted in a policy violation.

Request Size

The size (in bytes) of the incoming client request.

Resource Path

The path of the client request.

Response Size

The size in bytes of the API response.

If the Content-Length header is present, the Response Size is set to that value. If the Content-Length header is not present and the payload is a String, Analytics calculates the length of the String and reports that value. If the Content-Length header is not present and the payload is not a String, Analytics reports the response size as -1. For example, if the output returned is a DataWeave stream and the Content-Length header is not present, Analytics doesn’t report a response size because the value is not a String. However if your application performs a String conversion, the response size is listed.

Response Time

The processing time of the API request.

Status Code

The HTTP status code of the response.

Timezone

The time zone from which the API request originated (inferred by the IP address of the client).

User Agent Name

The complete user agent string for the incoming client request.

User Agent Version

The version of the user agent string for the incoming client request.

Verb

The REST verb associated with the API client request (GET, POST, PATCH, etc.).

Violated Policy Name

The name of the policy violated by the API request (if any).