Diagnostics in Azure API Management

Overview

Diagnostics enable you to capture request and response details for APIs managed by Azure API Management (APIM). Use diagnostics to troubleshoot, monitor performance, and gain insights into traffic patterns.

Enable Diagnostics

Diagnostics are configured per API, operation, or globally at the service level. You can direct logs to Azure Monitor, Application Insights, or a custom logger.

{
  "properties": {
    "diagnostics": [
      {
        "enabled": true,
        "loggerId": "appInsightsLogger",
        "sampling": {
          "samplingType": "Fixed",
          "percentage": 100
        },
        "alwaysLog": "allErrors",
        "frontend": {
          "request": {
            "body": { "bytes": 2048 }
          },
          "response": {
            "body": { "bytes": 2048 }
          }
        },
        "backend": {
          "request": {
            "body": { "bytes": 2048 }
          },
          "response": {
            "body": { "bytes": 2048 }
          }
        }
      }
    ]
  }
}
        Copy

Create a Logger

Before enabling diagnostics, create a logger that points to your destination.

az apim logger create --resource-group MyResourceGroup \
    --service-name MyAPIMService \
    --logger-id appInsightsLogger \
    --application-insights /subscriptions/xxxx/resourceGroups/xxxx/providers/microsoft.insights/components/MyAppInsights \
    --description "App Insights logger for diagnostics"
        Copy

Policy Example: Log Request/Response

Add the <log-to-eventhub> or <log-to-applicationinsights> policy within the <inbound> and <outbound> sections.

<policies>
  <inbound>
    <base/>
    <log-to-applicationinsights 
        logger-id="appInsightsLogger"
        sampling-rate="100"/>
  </inbound>
  <backend>
    <base/>
  </backend>
  <outbound>
    <base/>
    <log-to-applicationinsights 
        logger-id="appInsightsLogger"
        sampling-rate="100"/>
  </outbound>
</policies>
        Copy

Diagnostic Settings Summary

Best Practices

• Enable diagnostics only for the environments where troubleshooting is required (e.g., dev or staging).
• Use sampling to control data volume and cost.
• Mask sensitive data in request/response bodies using policy expressions before logging.
• Integrate with Azure Monitor alerts for error thresholds.