How to integrate Azure API Management with Azure Application Insights

  • Article

APPLIES TO: All API Management tiers

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 Application Insights integration into API Management.
  • Learn strategies for reducing performance impact on your API Management service instance.

Warning

When using our self-hosted gateway, we do not guarantee all telemetry will be pushed to Azure Application Insights given it relies on Application Insights' in-memory buffering.

Prerequisites

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

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

    Note

    The Application Insights resource can be in a different subscription or even a different tenant than the API Management resource.

  • If you plan to configure managed identity credentials to use with Application Insights, complete the following steps:

    1. Enable a system-assigned or user-assigned managed identity for API Management.

      • If you enable a user-assigned managed identity, take note of the identity's Client ID.

    2. Assign the identity the Monitoring Metrics Publisher role, scoped to the Application Insights resource. To assign the role, use the Azure portal or other Azure tools.

Scenario overview

The following are high level steps for this scenario.

  1. First, create a connection between Application Insights and API Management

    You can create a connection between Application Insights and your API Management using the Azure portal, the REST API, or related Azure tools. API Management configures a logger resource for the connection.

    Important

    Currently, in the portal, API Management only supports connections to Application Insights using an Application Insights instrumentation key. For enhanced security, we recommend using an Application Insights connection string with an API Management managed identity. To configure connection string with managed identity credentials, use the REST API or related tools as shown in a later section of this article. Learn more about Application Insights connection strings.

    Note

    If your Application Insights resource is in a different tenant, then you must create the logger using the REST API or related tools as shown in a later section of this article.

  2. Second, enable Application Insights logging for your API or APIs.

    In this article, you enable Application Insights logging for your API using the Azure portal. API Management configures a diagnostic resource for the API.

Create a connection using the Azure portal

Follow these steps to use the Azure portal to create a connection between Application Insights and API Management.

Note

Where possible, Microsoft recommends using connection string with managed identity credentials for enhanced security. To configure these credentials, use the REST API or related tools as shown in a later section of this article.

  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 gateway 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 now appears in the list.

    Screenshot that shows where to view the newly created Application Insights logger.

Note

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

Tip

If you need to update the instrumentation key configured in the Application Insights logger, select the logger's row in the list (not the name of the logger). Enter the instrumentation key, and select Save.

Create a connection using the REST API, Bicep, or ARM template

Follow these steps to use the REST API, Bicep, or ARM template to create an Application Insights logger for your API Management instance. You can configure a logger that uses connection string with managed identity credentials (recommended), or a logger that uses only a connection string.

See the prerequisites for using an API Management managed identity.

The Application Insights connection string appears in the Overview section of your Application Insights resource.

Connection string with system-assigned managed identity

Use the API Management Logger - Create or Update REST API with the following request body.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

Connection string with user-assigned managed identity

Use the API Management Logger - Create or Update REST API with the following request body.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Logger with connection string credentials only

The Application Insights connection string appears in the Overview section of your Application Insights resource.

Use the API Management Logger - Create or Update REST API with the following request body.

If you are configuring the logger for a workspace, use the Workspace Logger - Create or Update REST API.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Enable Application Insights logging for your API

Use the following steps to enable Application Insights logging for an API. You can also enable Application Insights logging for all APIs.

  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.

    Tip

    To enable logging for all APIs, select All APIs.

  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. For details about the settings, see Diagnostic logs settings reference.

    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.

Loggers for a single API or all APIs

You can specify loggers on different levels:

  • Single API logger
  • A logger for all APIs

Specifying both:

  • By default, the single API logger (more granular level) overrides the one for all APIs.
  • If the loggers configured at the two levels are different, and you need both loggers to receive telemetry (multiplexing), please contact Microsoft Support. Please note that multiplexing is not supported if you're using the same logger (Application Insights destination) at the "All APIs" level and the single API level. For multiplexing to work correctly, you must configure different loggers at the "All APIs" and individual API level and request assistance from Microsoft support to enable multiplexing for your service.

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.

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.

Troubleshooting

Addressing the issue of telemetry data flow from API Management to Application Insights:

  • Investigate whether a linked Azure Monitor Private Link Scope (AMPLS) resource exists within the VNet where the API Management resource is connected. AMPLS resources have a global scope across subscriptions and are responsible for managing data query and ingestion for all Azure Monitor resources. It's possible that the AMPLS has been configured with a Private-Only access mode specifically for data ingestion. In such instances, include the Application Insights resource and its associated Log Analytics resource in the AMPLS. Once this addition is made, the API Management data will be successfully ingested into the Application Insights resource, resolving the telemetry data transmission issue.

Related content