Contact Us 1-800-596-4880
  1. Homepage
  2. API Manager (2.x)
  3. View Mule API Analytics

  4. Review Mule API Analytics Event API

Reviewing Mule API Analytics Event API

API Manager gathers analytics data for each Mule 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.

Requirements and Restrictions

The Analytics Events API provides a one-month retention policy and a data availability delay of up to 10 minutes. It also enforces a usage limit of 10 requests per minute, with a maximum of 20,000 events per request. Request rates higher than 10 requests per minute are throttled.

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

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

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

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

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

Create a Report

You can create a report to find API events, such as policy violations due to rate limiting or IP blacklisting. If the analytics services or Anypoint Platform are temporarily unavailable, Anypoint Platform may submit multiple data points to avoid any telemetry data loss. This might cause the report that you generate to contain duplicate entries.

To create a report:

  1. Navigate to API Manager > Mule 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 Mule API 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 Report Data Fields Reference. 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: Mule API Analytics calculates the length of the String and reports that value.

  • Not present and the payload is not a String: Mule API 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.

Restricting Client IP Data

If you don’t want to forward client IP data, set anypoint.platform.analytics_include_client_ip=false in the wrapper.conf file of your Mule runtime. To set properties, refer to Configuring Properties.

If you choose not to forward client IP data, geolocalized data such as City, Continent, Postal Code, Country, and Timezone is also not available.

See Also