How to integrate Azure API Management with Azure Application Insights

You can easily integrate Azure Application Insights with Azure API Management. Azure Application Insights is an extensible service for web developers building and managing apps on multiple platforms. In this guide, you will:

  • Walk through every step of the Application Insights integration into API Management.
  • Learn strategies for reducing performance impact on your API Management service instance.

Prerequisites

You need an Azure API Management instance. Create one first.

Create an Application Insights instance

To use Application Insights, create an instance of the Application Insights service. To create an instance using the Azure portal, see Workspace-based Application Insights resources.

Create a connection between Application Insights and API Management

  1. Navigate to your Azure API Management service instance in the Azure portal.
  2. Select Application Insights from the menu on the left.
  3. Select + Add.
    Screenshot that shows where to add a new connection
  4. Select the Application Insights instance you created earlier and provide a short description.
  5. To enable availability monitoring of your API Management instance in Application Insights, select the Add availability monitor checkbox.
    • This setting regularly validates whether the API Management service endpoint is responding.
    • Results appear in the Availability pane of the Application Insights instance.
  6. Select Create.
  7. Check that the new Application Insights logger with an instrumentation key now appears in the list.
    Screenshot that shows where to view the newly created Application Insights logger with instrumentation key

Note

Behind the scenes, a Logger entity is created in your API Management instance, containing the instrumentation key of the Application Insights instance.

Enable Application Insights logging for your API

  1. Navigate to your Azure API Management service instance in the Azure portal.

  2. Select APIs from the menu on the left.

  3. Click on your API, in this case Demo Conference API. If configured, select a version.

  4. Go to the Settings tab from the top bar.

  5. Scroll down to the Diagnostics Logs section.
    App Insights logger

  6. Check the Enable box.

  7. Select your attached logger in the Destination dropdown.

  8. Input 100 as Sampling (%) and select the Always log errors checkbox.

  9. Leave the rest of the settings as is.

    Warning

    Overriding the default Number of payload bytes to log value 0 may significantly decrease the performance of your APIs.

  10. Select Save.

  11. Behind the scenes, a Diagnostic entity named applicationinsights is created at the API level.

Note

Requests are successful once API Management sends the entire response to the client.

Setting name Value type Description
Enable boolean Specifies whether logging of this API is enabled.
Destination Azure Application Insights logger Specifies Azure Application Insights logger to be used.
Sampling (%) decimal Values from 0 to 100 (percent).
Specifies the percentage of requests that will be logged to Application Insights. 0% sampling means zero requests logged, while 100% sampling means all requests logged.
Use this setting to reduce effect on performance when logging requests to Application Insights. See Performance implications and log sampling.
Always log errors boolean If this setting is selected, all failures will be logged to Application Insights, regardless of the Sampling setting.
Log client IP address If this setting is selected, the client IP address for API requests will be logged to Application Insights.
Verbosity Specifies the verbosity level. Only custom traces with higher severity level will be logged. Default: Information.
Correlation protocol Select protocol used to correlate telemetry sent by multiple components. Default: Legacy
For information, see Telemetry correlation in Application Insights.
Basic Options: Headers to log list Specifies the headers that will be logged to Application Insights for requests and responses. Default: no headers are logged.
Basic Options: Number of payload bytes to log integer Specifies how many first bytes of the body are logged to Application Insights for requests and responses. Default: 0.
Advanced Options: Frontend Request Specifies whether and how frontend requests will be logged to Application Insights. Frontend request is a request incoming to the Azure API Management service.
Advanced Options: Frontend Response Specifies whether and how frontend responses will be logged to Application Insights. Frontend response is a response outgoing from the Azure API Management service.
Advanced Options: Backend Request Specifies whether and how backend requests will be logged to Application Insights. Backend request is a request outgoing from the Azure API Management service.
Advanced Options: Backend Response Specifies whether and how backend responses will be logged to Application Insights. Backend response is a response incoming to the Azure API Management service.

Note

You can specify loggers on different levels:

  • Single API logger.
  • A logger for all APIs.

Specifying both:

  • if they are different loggers, both of them will be used (multiplexing logs).
  • if they are the same loggers with different settings, the single API logger (more granular level) will override the one for all APIs.

What data is added to Application Insights

Application Insights receives:

Telemetry item Description
Request For every incoming request:
  • frontend request
  • frontend response
Dependency For every request forwarded to a backend service:
  • backend request
  • backend response
Exception For every failed request:
  • Failed because of a closed client connection
  • Triggered an on-error section of the API policies
  • Has a response HTTP status code matching 4xx or 5xx
Trace If you configure a trace policy.
The severity setting in the trace policy must be equal to or greater than the verbosity setting in the Application Insights logging.

Emit custom metrics

You can emit custom metrics by configuring the emit-metric policy.

To make Application Insights pre-aggregated metrics available in API Management, you'll need to manually enable custom metrics in the service.

  1. Use the emit-metric policy with the Create or Update API.
  2. Add "metrics":true to the payload, along with any other properties.

Note

See Application Insights limits for information about the maximum size and number of metrics and events per Application Insights instance.

Performance implications and log sampling

Warning

Logging all events may have serious performance implications, depending on incoming requests rate.

Based on internal load tests, enabling the logging feature caused a 40%-50% reduction in throughput when request rate exceeded 1,000 requests per second. Application Insights is designed to assess application performances using statistical analysis. It's not:

  • Intended to be an audit system.
  • Suited for logging each individual request for high-volume APIs.

You can manipulate the number of logged requests by adjusting the Sampling setting. A value of 100% means all requests are logged, while 0% reflects no logging.

Sampling helps to reduce telemetry volume, effectively preventing significant performance degradation while still carrying the benefits of logging.

To improve performance issues, skip:

  • Request and responses headers.
  • Body logging.

Video

Next steps