The Diagnostic Tools API

Once you extend your web content onto the Akamai edge network and apply various Akamai features to accelerate and manipulate content, you need to be able to troubleshoot any problems your own users may encounter. The Diagnostic Tools API allows you to diagnose many common problems Akamai customers experience when delivering content to their end users. It offers a programmatic alternative to many of the features available in the Luna Control Center, under the ResolveDiagnostic Tools menu.

This major new API release supersedes the original version 1. Version 2 includes the following features:

  • The new API now allows you to access data asynchronously to avoid long-running requests that often time out. See Asynchronous Requests for more information.

  • It allows you to run many familiar networking tools such as dig, mtr, and curl, or get logs either from locations on the Akamai edge network, or from specific Akamai IP addresses.

  • A new error statistics feature allows you to research how edge servers communicate both with user client requests, and with your origin server.

  • You are also able to aggregate error statistics for each CP Code, the main system you use to organize categories of web content.

  • This API version allows you to diagnose problems with any Global Traffic Management properties (subdomains) you administer.

  • In addition to running tests on specific edge server locations or IP addresses, you can send individual end users diagnostic links to trace what happens to their requests.

See Diagnostic Utilities for more information on available tools. See the Resources section for a complete listing of API operations.

Who Should Use This API

Use this API to implement your own problem-resolution dashboard for Akamai-provisioned content, or to integrate it with other similar debugging tools. Use the end-user operations to implement interfaces to solicit feedback from your own users. In addition to helping solve any problems your end user experience, consider also leveraging these batch tools to design more proactive interfaces to monitor performance.

Getting Started

Before using this API for the first time:

  • Review Get Started for information on various tools Akamai provides.

  • Review Authorize your Client to create your OPEN API access credentials and authorizations. As detailed in the API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • Some of the diagnostic tools this API makes available require certain features to be available under your product and contract. For example, you need Global Traffic Management enabled to run the corresponding diagnostic tools, otherwise you get a 403 error. Make sure the identity under which you provision the API has access to all the features for which you want diagnostic data.

Diagnostic Utilities

Many of the utilities this API makes available to you effectively extend the range of standard networking tools so that you can run them from arbitrary locations within the Akamai network, rather than from your local network. The API makes these diagnostic utilities available:

  • Akamai Server Locations: This basic enabling utility lists available Akamai ghost server locations. You may need this information to run other utilities from a set of edge server locations.

  • Akamai CDN Status: This basic enabling utility confirms whether a specified IP address belongs to an Akamai edge server. You may need this information to run other utilities from a set of edge IP addresses.

  • Dig, by edge IP or location: This uses the dig command to provide Domain Name Server (DNS) details for the location of the edge server and hostname or domain name, allowing you to diagnose issues with domain name resolution.

  • Mtr, by edge IP or location: This uses the mtr command to provide information about the route, number of hops, and time that Internet traffic packets take between the edge server and a remote host or destination. The results can show you where network delays are being introduced in the path.

  • Curl, by edge IP or location: This uses the curl command to provide a specified URL’s raw HTML. Making an HTTP request from an edge server lets you gather information about the HTTP response.

  • Log Lines, by edge IP or location: This uses the grep command to retrieve and parse log records within the last 48 hours from either an edge server location or an IP address.

  • Geolocation: This provides the geographic and network location of any IP address.

  • End User Diagnostic Links: This tool generates a link to obtain client and Domain Name Server (DNS) IP information for a specific user. The results provide a URL to send to the end user. When the user visits the URL, the API captures user and mapping information that you may need to troubleshoot a problem.

  • Global Traffic Management: This tool provides a mapping of subdomain properties to domain names, and corresponding edge IP addresses.

  • Error Statistics: This provides details on errors that occur when delivering web content. It’s based on real-time traffic data, both for client-to-edge and edge-to-origin traffic.

  • Error Translations: This uses the error string from an error page’s reference number to fetch a summary and log information for the error.

  • URL Debugging: This provides DNS Information, HTTP response, response headers, and logs for a URL or ARL (Akamaized URL).

  • URL Translations: This provides basic information about a specified hostname or domain name, such as typecode, origin server, CP code, serial number, and TTL for an Akamaized URL (ARL).

Asynchronous Requests

In many cases, diagnostic data can’t be pre-cached, and Akamai edge servers need to dynamically assemble it for you. This introduces significant latencies when doing ordinary GET requests on the reporting data. Requests can run minutes long, and can time out. To address this problem, version 2 of the Diagnostic Tools API introduces a new way to access the data asynchronously. Instead of getting the data directly, you launch a request to fetch it later, and poll the status of that request. When the data is ready, a 303 response provides a link to the data in the same format as you would ordinarily get directly.

These steps form the basis for the asynchronous API workflow:

  1. For each relevant direct GET operation, choose instead the corresponding launch POST operation.

  2. The POST’s response body object features a requestId that you can store to run a follow-up check on the request’s status. Otherwise store the API hypermedia link to check it directly.

  3. Also store the retryAfter interval from the POST’s response body object. This represents the estimated number of seconds for when the data will be ready for you.

  4. Wait for the duration of the retryAfter interval, then either use the requestId to run the relevant check operation, or simply GET the link.

  5. If the response yields a 200 code, it means the process is still running, and the data is not yet ready. Store the revised value of the Retry-After header, or the response object’s retryAfter member, then run the check operation again.

  6. Once the response yields a 303 code, it means the request has completed, and your data is now ready. Use the requestId to run the operation where you get the data asynchronously, or simply run GET on the 303 response’s Location API hypermedia link. The API makes the requested data available at that link for at least 24 hours.

The API provides the following set of asynchronous operations as an alternative to accessing directly, but with latency:

POST async request GET request status GET data, without latency… …instead of this direct GET, with latency
Launch a CDN Status Request Check a CDN Status Request Get CDN Status Asynchronously Get CDN Status
Launch an Error Translation Request Check an Error Translation Request Translate an Error Asynchronously Translate an Error
Launch a URL Debug Request Check a URL Debug Request Debug a URL Asynchronously Debug a URL
Launch an Error Stats Request Check an Error Stats Request Get Error Statistics Asynchronously Get Error Statistics
Launch a CP Code Error Stats Request Check an Error Stats Request Get Error Statistics Asynchronously Get CP Code Error Stats

Last modified: 5/4/2017