Contact Free trial Login

Reviewing Analytics Event API

API Manager gathers analytics data for each API that you manage. You can generate this data in reports and charts, using the Analytics Event API. You can create reports for a specific environment or for multiple APIs, and you can create different reports for the same API.

If your organization’s API use exceeds 20,000 requests per 10 minutes, using this API causes throttling. Consider the alternative of configuring the API gateway to send events directly to monitoring systems.

Requirements and Restrictions

The Event API is designed to create ad-hoc reports. It is not intended as a data export tool. Before you start using the API to create reports, consider the following requirements and restrictions:

  • Do not allow calls to overlap time intervals.

  • Retrieve all the data that you need in a single request, but note that data retrieval is limited to 20,000 events.

  • Do not repeat the same request for every API that you have.

  • Although the Analytics Event API enforces a limit of 10 requests per minute, best practice is 1 request per minute.

    Request rates higher than 10 request per minutes are throttled.

  • The analytics data for events is retained for one month, with a data availability delay of up to 10 minutes.

  • Do not use the Analytics Event API for data synchronization.

    If you need to synchronize data for events with an external system, see Analytics Event Forwarding.

Create a Report

The following task illustrates how to create a report to find API events by using an example to find events that were rejected because of policy violations, such as rate limiting or IP blacklisting:

  1. Navigate to API Manager > Analytics > Manage Reports and click New.

  2. In Create Report, select a data source, range, and format.

  3. In Fields, select Violated Policy Name.

  4. Save the report.

    A URL for viewing the report is displayed.

  5. Click the URL to view the generated report.

Run a Report in the Browser

The Analytics Event API displays a starting time from which requested data is available. If no data is available, a warning message appears.

To run a report in a browser, navigate to the Manage Reports page and click Run for your desired report:

anev_running_report2

After the report runs, a CSV or JSON file is generated, containing the analytics data you requested.

View Report Information Using curl

You get the value of $TOKEN by running the curl command in this procedure. The command gets 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-line JSON processor is one possible solution for obtaining the access token value. Download and install this application or one with the same functionality for this procedure.

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)

    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:

    {
     "access_token": "54545454-5454-5454-5454-545454545454",
     "token_type": "Bearer",
     "redirectUrl": "/accounts/#/cs/profile/home"
     }
  2. Append the access token to the Authorization header in the request of the Analytics Reporting API endpoint for your report:

    1. Copy the endpoint from the Manage Reports page in the Analytics dashboard.

    2. Include the $TOKEN variable from the previous step in the next request, as shown in the following example that retrieves analytics for organizations without environments:

      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
  3. If the request is successful, an output.csv file is generated in the directory from which you initiated the curl request.

    This next example queries the Analytics Events API for organizations with environments:

curl -H "Authorization: Bearer $TOKEN" "https://anypoint.mulesoft.com:443/analytics/1.0/<ORGANIZATION_ID>/environments/<ENVIRONMENT_ID>/events?format=csv&apiIds=<API_ID>&duration=30d" > output.csv

In this example, analytics data is retrieved for the past 30 days from the API with the API ID <API_ID>. The results are generated in a CSV format.

+ The following example combines two curl commands and displays values in the command prompt window:

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

The following output is generated with this command:

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

Create a Report for Specific Environments

For organizations that have enabled environments, API events queried using the approach described in the topic belongs exclusively to the "Unclassified" environment.

To request events for APIs in a specific environment:

  1. Select the environment in the Environment selector and create the report that you want to run.

    Reports are stored based on the environment. Therefore, different reports exist in different environments.

  2. Copy from the UI the report URL generated from creating the report.

    Note that in addition to the organization ID, the URL also includes /environment/{Environment ID}. Anypoint Platform assigns a unique ID to an organization and an environment when they are created. For example, an API ID in the QA environment differs from its ID in the Production environment.

  3. To access events for a specific environment, append the environment ID to the report URL.

Command Options Reference

You can add the following options to curl commands:

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

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. 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 20000.+

Type: integer
Required: no
Example: maxResults=3

startDate

Starting date and time, as described by http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser()[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 http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeParser().

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

Report Data Fields Reference

Your report can query data for one or more of the available data fields:

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. See note below.

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

In your query, if the Content-Length header is:

  • Present: Response Size is set to that value.

  • Not present and the payload is a String: Analytics calculates the length of the String and reports that value.

  • 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, the Analytics Event API does not report a response size because the value is not a String. However if your application performs a String conversion, the response size is listed.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub