mPulse Query API Wrapper

The python scripts are wrapper for mPulse Query API.

Description

mPulse is the Real User Monitoring solution offered by Akamai. Along with the UI, the system exposes APIs to extract the reporting information. The purpose of this CLI is to make the use the API simple and easier to plug in to monitoring systems or even build systems like Jenkins.

To work with this CLI, you will need 2 pieces of information:

• API Token for the user: This is a unique value assigned to each registered user on mPulse system. You could think of this value as a combination of user/password for the mpulse API to authenticate.
  To get this value, navigate to your user-profile and look for the field API Token.

  

• API key for the Application: The API key uniquely identifies a specific application. This value is required to let mPulse system know that you are looking for the performance information for a specific setup within the mPulse system.

Working of the CLI

mPulse API requires a security token to authenticate the requests. This security token is based on the API token associated with each user. This CLI assumes that the user's API token is included in a plain-text ini like file. By default, the CLI assumes this file to be ~/.mpulse. The format of the file should be as follows:

[credential-section-name] 
apiToken=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
tenant=Customer

Note that the tenant section could be optional. This is only necessary if you have access to more than one mPulse setup.

Usage

To use the command, simply invoke the akamai-mpulse command with the right set of options.

usage: akamai-mpulse [-h] [--config CONFIG] [--section SECTION] [--api API]
                     [--timer {PageLoad,FirstLastByte,FirstByte,DNS,TCP,SSL,DomLoad,DomReady,ClientRoundTripTime,TimeToInteractive,FirstInputDelay,TimeToFirstInteraction,TimeToVisuallyReady,FirstPaint,FirstContentfulPaint,LongTasksTime}]
                     [--date-comparator {Last30Minutes,LastHour,Last3Hours,Last12Hours,Last24Hours,ThisWeek,ThisMonth,Last,Between}]
                     [--type {summary,histogram,sessions-per-page-load-time,metric-per-page-load-time,by-minute,geography,page-groups,browsers,bandwidth,ab-tests,timers-metrics,metrics-by-dimension,dimension-values}]
                     [--json] [--verbose] [--date DATE]
                     [--date_start DATE_START] [--date_end DATE_END]

CLI for mPulse Query API. For more information about the API, please refer to
https://developer.akamai.com/api/web_performance/mpulse_query/v2.html

optional arguments:
  -h, --help            show this help message and exit
  --config CONFIG       mPulse configuration file containing the user's API
                        key (default=~/.mpulse)
  --section SECTION     Section within the config file containing the
                        credentials (default=[mpulse])
  --api API             API key of the app
  --timer {PageLoad,FirstLastByte,FirstByte,DNS,TCP,SSL,DomLoad,DomReady,ClientRoundTripTime,TimeToInteractive,FirstInputDelay,TimeToFirstInteraction,TimeToVisuallyReady,FirstPaint,FirstContentfulPaint,LongTasksTime}
                        The timer to report (default=page load time)
  --date-comparator {Last30Minutes,LastHour,Last3Hours,Last12Hours,Last24Hours,ThisWeek,ThisMonth,Last,Between}
                        Choose the way mPulse is going to report the data
  --type {summary,histogram,sessions-per-page-load-time,metric-per-page-load-time,by-minute,geography,page-groups,browsers,bandwidth,ab-tests,timers-metrics,metrics-by-dimension,dimension-values}
                        Choose the type of report to execute (default=Summary)
  --json                Force JSON response
  --verbose             Enable verbose output
  --date DATE           Date when the report is required
  --date_start DATE_START
                        Start Date and Time for the report
  --date_end DATE_END   End Date and Time for the report

The only required parameter is the API key.

By default, the function will use the following defaults:

• configuration file: ~/.mpulse
• default section within this configuration file: mpulse
• under this configuration, it will look for 1 required and 1 optional parameter:
  • apiToken: This is the value pulled from the user's profile on the mPulse screen. This is a required parameter.
  • tenant: Parameter used to restrict the security token to specific customer tenant.

Optional Parameters

Apart from the parameters listed, any other parameter listed on the API page can be used. Here are a few examples:

• timer: (default PageLoad) This can be used to change the timer used for reported.
• timezone: (default UTC) Use this to change the timezone
• type: (default summary) This option switches the report.

See the usage options below for details.

Sample Usage

Get the summary for last hour

By default, the command fetches the PageLoad for the last 1 hour. akamai mpulse --api XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Get summary for last day, week or month

By adding the date-comparator with one of the following value, you should get the default metric (PageLoad) for the duration. See the date parameters for list of values.

Here's the command to get the data for last 12 hours.

akamai mpulse --api XXXXX-XXXXX-XXXXX-XXXXX-XXXXX --date-comparator=Last12Hours

Get different timer

By default, we get the summary for PageLoad. You can use the timer to get other metrics as described in timer parameters.

Here's the command to get the DomLoad metric.

akamai mpulse --api XXXXX-XXXXX-XXXXX-XXXXX-XXXXX --timer=DomLoad

Drill down (In-progress..)

You could drill down the data by using the dimension parameters and group the result by using the metrics by dimension parameters.

To filter the summary data for just the US geography, you can use this:

akamai mpulse --api XXXXX-XXXXX-XXXXX-XXXXX-XXXXX country=US

Using JQ

I normally like to filter the output with JQ. This will allow for quicker parsing and extraction of specific fields. For example, if you just require the value for the median every hour, you could use this command:

akamai mpulse --api XXXXX-XXXXX-XXXXX-XXXXX-XXXXX | jq '.median'

Hope this is useful and I'd love to hear feedback!