Cómo integrar Azure API Management con Aplicación de Azure Insights

SE APLICA A: Todos los niveles de API Management

Puede integrar fácilmente Aplicación de Azure Insights con Azure API Management. Aplicación de Azure Insights es un servicio extensible para desarrolladores web que compilan y administran aplicaciones en varias plataformas. En esta guía, hará lo siguiente:

Recorra cada paso de la integración de Application Insights en API Management.
Aprender estrategias para reducir el impacto en el rendimiento de la instancia del servicio API Management.

Note

En un área de trabajo de API Management, un propietario del área de trabajo puede integrar Application Insights de forma independiente y habilitar el registro de Application Insights para las API del área de trabajo. La guía general para integrar un área de trabajo con Application Insights es similar a la guía de una instancia de API Management; sin embargo, la configuración solo tiene como ámbito el área de trabajo. Actualmente, debe integrar Application Insights en su área de trabajo configurando una cadena de conexión (recomendado) o una clave de instrumentación.

Warning

Al usar nuestra puerta de enlace autohospedada, no garantizamos que toda la telemetría se inserte en Aplicación de Azure Insights, ya que se basa en el almacenamiento en búfer en memoria de Application Insights.

Prerequisites

Cree una instancia de Azure API Management.
Cree una instancia del servicio Application Insights. Para crear una instancia utilizando el portal de Azure, consulta recursos de Application Insights basados en el espacio de trabajo.

Note

El recurso de Application Insights puede estar en una suscripción distinta o incluso en un inquilino distinto de los del recurso de API Management.
Si tiene previsto configurar las credenciales de identidad administradas para usarlas con Application Insights, complete los pasos siguientes:
1. Habilite una identidad administrada por el usuario o asignada por el sistema para API Management.
  - Si habilita una identidad administrada asignada por el usuario, tome nota del id. de cliente de la identidad.
2. Asigne la identidad al rol Publicador de métricas de supervisión, cuyo ámbito es el recurso de Application Insights. Puede usar Azure Portal u otras herramientas de Azure para asignar el rol.

Información general sobre el escenario

Los siguientes pasos ofrecen una visión general de este escenario.

Cree una conexión entre Application Insights y API Management.

Puede crear una conexión entre Application Insights y API Management mediante Azure Portal, la API REST o las herramientas de Azure relacionadas. API Management configura un recurso de registrador para la conexión.

Important

Actualmente, en el portal, API Management solo admite conexiones a Application Insights mediante una clave de instrumentación de Application Insights. Para mejorar la seguridad, utiliza una cadena de conexión de Application Insights con una identidad gestionada por API Management. Para configurar la cadena de conexión con las credenciales de identidad administradas, use la API de REST o las herramientas relacionadas, como se muestra en una sección posterior de este artículo. Para más información, consulte Cadenas de conexión en Application Insights.

Note

Si tu recurso de Application Insights está en otro tenant, crea el registrador utilizando la API REST o herramientas relacionadas, como se muestra en una sección posterior de este artículo.
Habilite el registro de Application Insights para su API o sus APIs.

En este artículo, habilitará el registro de Application Insights para la API mediante Azure Portal. API Management configura un recurso de diagnóstico para la API.

Crea una conexión usando el portal de Azure

Siga estos pasos para usar Azure Portal para crear una conexión entre Application Insights y API Management.

Note

Siempre que sea posible, Microsoft recomienda usar la cadena de conexión con credenciales de identidad administrada para mejorar la seguridad. Para configurar estas credenciales, use la API de REST o herramientas relacionadas como se muestra en una sección posterior de este artículo.

Ve a tu instancia de servicio Azure API Management en el portal de Azure.
En Supervisión en el menú de la barra lateral, seleccione Application Insights.
Seleccione +Agregar.
Seleccione la instancia de Application Insights que ha creado antes y proporcione una descripción breve.
Para habilitar la supervisión de la disponibilidad de su instancia de API Management en Application Insights, seleccione la casilla Add availability monitor (Agregar supervisión de la disponibilidad).
- Esta configuración comprueba regularmente si el punto final del gateway de gestión de API responde.
- Los resultados aparecerán en el panel Disponibilidad de la instancia de Application Insights.
Selecciona Crear.
Compruebe que el nuevo registrador de Application Insights aparece ahora en la lista.

Note

En segundo plano, se crea la entidad registradora en la instancia de API Management que contiene la clave de instrumentación de la instancia de Application Insights.

Tip

Si necesita actualizar la clave de instrumentación configurada en el registrador de Application Insights, seleccione la fila del registrador en la lista (no el nombre del registrador). Escriba la clave de instrumentación y seleccione Guardar.

Crea una conexión utilizando la API REST, Bicep o plantilla ARM

Siga estos pasos para usar la plantilla API de REST, Bicep o ARM para crear un registrador de Application Insights para su instancia de API Management. Puedes configurar un registrador que use una cadena de conexión con credenciales de identidad gestionada (recomendado), o un registrador que solo use una cadena de conexión.

Registrador con cadena de conexión y credenciales de identidad administrada (recomendado)

Consulte los requisitos previos para usar una identidad administrada de API Management.

La cadena de conexión aparece en la sección de Información general del recurso de Application Insights.

Cadena de conexión con identidad administrada asignada por el sistema

Use la API de REST Registrador: crear o actualizar de API Management con el siguiente cuerpo de solicitud.

{
  "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"
    }
  }
}

Incluya un fragmento de código similar al ejemplo siguiente en el archivo de Bicep.

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  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'
    }
  }
}

Incluya un fragmento de código JSON similar al ejemplo siguiente en la plantilla de Azure Resource Manager.

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "SystemAssigned"
    }
  }
}

Cadena de conexión con identidad administrada asignada por el usuario

Use la API de REST Registrador: crear o actualizar de API Management con el siguiente cuerpo de solicitud.

{
  "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":"<client-ID>"
    }
  }
}

Incluya un fragmento de código similar al ejemplo siguiente en el archivo de Bicep.

resource aiLoggerWithUserAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  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: '<client-ID>'
    }
  }
}

Incluya un fragmento de código JSON similar al ejemplo siguiente en la plantilla de Azure Resource Manager.

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
      "identityClientId": "<client-ID>"
    }
  }
}

Registrador con credenciales de cadena de conexión solo

La cadena de conexión aparece en la sección de Información general del recurso de Application Insights.

Use la API de REST Registrador: crear o actualizar de API Management con el siguiente cuerpo de solicitud.

Si va a configurar el registrador para un área de trabajo, use la API REST Workspace Logger - Create or Update .

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

Incluya un fragmento de código similar al ejemplo siguiente en el archivo de Bicep.

Si va a configurar el logger para un área de trabajo, cree un recurso Microsoft.ApiManagement/service.workspace/loggers@2023-09-01-preview en su lugar.

resource aiLoggerWithSystemAssignedIdentity 'Microsoft.ApiManagement/service/loggers@2022-08-01' = {
  name: 'ContosoLogger1'
  parent: '<API-management-instance-name>'
  properties: {
    loggerType: 'applicationInsights'
    description: 'Application Insights logger with connection string'
    credentials: {
      connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...'
    }
  }
}

Incluya un fragmento de código JSON similar al ejemplo siguiente en la plantilla de Azure Resource Manager.

Si estás configurando el logger para un área de trabajo, crea un recurso Microsoft.ApiManagement/service.workspace/loggers y establece apiVersion en 2023-09-01-preview en su lugar.

{
  "type": "Microsoft.ApiManagement/service/loggers",
  "apiVersion": "2022-08-01",
  "name": "ContosoLogger1",
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "resourceId": "<application-insights-resource-ID>",
    "credentials": {
      "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
    },
  }
}

Habilitación del registro Application Insights para la API

Siga estos pasos para habilitar el registro de Application Insights para una API. También puede habilitar el registro de Application Insights para todas las API.

Ve a tu instancia de servicio Azure API Management en el portal de Azure.
Seleccione APIs>APIs en el menú de la barra lateral.
Seleccione una API, como Swagger Petstore. Si está configurado, seleccione una versión.

Tip

Para habilitar el registro para todas las API, seleccione Todas las API.
Seleccione la pestaña Configuración de la barra superior.
Desplácese hacia abajo hasta la sección Registros de diagnóstico y active la casilla Habilitar .
Seleccione el registrador adjunto en el menú desplegable Destino.
Introduce 100 como Muestreo (%) y selecciona la casilla Siempre registrar errores .
Deje el resto de los valores sin modificar. Para más información sobre la configuración, consulte Referencia de configuración de registros de diagnóstico.

Warning

Modificar el valor predeterminado de Número de bytes de carga útil que se van a registrar0 podría reducir significativamente el rendimiento de sus API.
Haga clic en Guardar.
En segundo plano, se crea una entidad Diagnostic (Diagnóstico) con el nombre applicationinsights en el nivel de API.

Note

Las solicitudes se completan correctamente una vez que API Management envía toda la respuesta al cliente.

Registradores para una sola API o todas las API

Puedes especificar los registradores en diferentes niveles:

Registrador de una API.
Registrador para todas las API.

Si especificas ambos:

De manera predeterminada, el registrador de API único (nivel más granular) anula el de todas las API.
Si los registradores configurados en los dos niveles son diferentes y necesita que ambos registradores reciban telemetría (multiplexación), póngase en contacto con el soporte técnico de Microsoft. No se soporta multiplexación si usas el mismo logger (destino de Application Insights) a nivel de "Todas las APIs" y a nivel de API única. Para que la multiplexación funcione correctamente, debe configurar diferentes registradores en el nivel "Todas las API" y en el nivel de API individual y solicitar asistencia del soporte técnico de Microsoft para habilitar la multiplexación para el servicio.

Qué datos se agregan a Application Insights

Application Insights recibe:

Elemento de telemetría	Description
Request	Para cada solicitud entrante: solicitud de front-end respuesta de front-end
Dependency	Telemetría automática de dependencias externas desde la ejecución de políticas soportadas, incluyendo solicitudes reenviadas a un servicio backend.
Exception	Para cada solicitud con error: No se pudo procesar debido a una conexión cliente cerrada Se ha desencadenado una sección on-error (al producirse un error) de las directivas de la API Tiene un código de estado HTTP de respuesta que coincide con 4xx o 5xx
Trace	Si configura una directiva de seguimiento. El valor `severity` de la directiva `trace` debe ser igual o mayor que el valor `verbosity` del registro de Application Insights.

Telemetría de dependencias externas para políticas soportadas

Después de configurar y habilitar el registro de Application Insights, la Gestión de API recopila automáticamente la telemetría externa de dependencias para las siguientes políticas. No se requiere ninguna política adicional ni configuración de telemetría:

authentication-managed-identity
authentication-token
azure-openai-semantic-cache-lookup
cosmosdb-request-handler
forward-request
get-authorization-context
http-data-source
invoke-dapr-binding
llm-content-safety
llm-semantic-cache-lookup
send-request
send-one-way-request
send-service-bus-message
sql-data-source
validate-jwt

Application Insights registra estas llamadas externas como operaciones secundarias correlacionadas. Por ejemplo, puedes ver reintentos, obtención de metadatos de OpenID Connect por parte de validate-jwt, un envío a Service Bus o reenvío al backend como operaciones relacionadas. Para verificar la telemetría en el portal de Azure, abre los detalles de las transacciones de extremo a extremo en tu recurso Application Insights y revisa las operaciones relacionadas para una solicitud.

Actualmente, el seguimiento de dependencias solo se soporta para las políticas de la lista anterior.

Note

Para información sobre el tamaño máximo y número de métricas y eventos por instancia de Application Insights, consulte Límites de Application Insights.

Emisión de métricas personalizadas

Puede emitir métricas personalizadas a Application Insights desde la instancia de API Management. La Gestión de APIs emite métricas personalizadas utilizando políticas como emit-metric y llm-emit-token-metric. La sección siguiente usa la directiva emit-metric como ejemplo.

Note

Las métricas personalizadas son una función de vista previa de Azure Monitor y están sujetas a limitaciones.

Para emitir métricas personalizadas, complete los siguientes pasos de configuración:

Habilite Métricas personalizadas (versión preliminar) con dimensiones personalizadas en su instancia de Application Insights.
1. Ve a tu instancia de Application Insights en el portal.
2. En Configurar en el menú de la barra lateral, seleccione Uso y costos estimados.
3. Seleccione Métricas personalizadas (versión preliminar)>Con dimensiones.
4. Selecciona Aceptar.

Añade la "metrics": true propiedad a la applicationInsights entidad de diagnóstico que configures en la Gestión de API. Actualmente, debes añadir esta propiedad mediante la API REST de Diagnóstico de API Management: crear o actualizar. Por ejemplo:

PUT https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<API-management-service-name>/loggers/<application-insights-logger-name>",
        "metrics": true
        [...]
    }
  }
}

Asegúrate de que el registrador de Insights de Aplicaciones esté configurado en el ámbito donde quieres emitir métricas personalizadas (ya sea todas las APIs o una sola API). Para más información, consulte Habilitación del registro de Application Insights para la API, anteriormente en este artículo.
Configura la emit-metric política en un ámbito donde el registro de Application Insights esté configurado (ya sea todas las APIs o una sola API) y esté habilitado para métricas personalizadas. Para obtener detalles de la directiva, consulte la referencia de la directiva emit-metric.

Límites de métricas personalizadas

Azure Monitor impone límites de uso para métricas personalizadas que pueden afectar la capacidad de emitir métricas de API Management. Por ejemplo, Azure Monitor establece actualmente un límite de 10 claves de dimensión por métrica y un límite de 50 000 series temporales activas totales por región en una suscripción (dentro de un período de 12 horas). En API Management, se usan 5 de estas dimensiones para las dimensiones predeterminadas, incluidas las siguientes:

Region
Id. de servicio
Nombre del servicio
Tipo de servicio

Estos límites tienen las siguientes implicaciones para configurar métricas personalizadas en una directiva de API Management como emit-metric o azure-openai-emit-token-metric:

Puede configurar un máximo de 5 dimensiones personalizadas por directiva.
El número de series temporales activas generadas por la política es el producto del número de valores únicos de cada dimensión configurada por espacio de nombres. Por ejemplo, si se configuraron tres dimensiones personalizadas en la directiva y cada dimensión tenía 10 valores posibles en el período, la directiva contribuiría a 1000 (10 x 10 x 10) series temporales activas.
La gestión de API limita cada dimensión a 100 valores únicos y cada espacio de nombres de métricas a 1.000 series temporales activas. Cuando se alcanza cualquiera de los límites, no se registran nuevos valores dimensionales o series temporales, y los datos métricos correspondientes se descartan silenciosamente.
Si configura la directiva en varias instancias de API Management que se encuentran en la misma región de una suscripción, todas las instancias pueden contribuir al límite regional de series temporales activas.

Obtenga más información sobre las limitaciones y consideraciones de diseño para las métricas personalizadas en Azure Monitor.

Consecuencias en el rendimiento y muestreo de registros

Warning

El registro de todos los eventos puede tener graves implicaciones de rendimiento, en función de la tasa de solicitudes entrantes.

En función de las pruebas de carga internas, habilitar la característica de registro ha provocado una reducción del 40 % al 50 % en el rendimiento cuando la tasa de solicitudes superaba las 1000 solicitudes por segundo. Application Insights se ha diseñado para evaluar el rendimiento de las aplicaciones mediante análisis estadísticos. No lo es:

Ser un sistema de auditoría.
Registrar cada solicitud individual para API de gran volumen.

Puede manipular el número de solicitudes que se registran si ajusta el valor Muestreo. Un valor del 100 % significa que se registran todas las solicitudes, mientras que un 0 % indica que no se registra nada.

Muestreo ayuda a reducir el volumen de telemetría, lo que evita de manera eficaz una degradación significativa en el rendimiento, a la vez que brinda las ventajas del registro.

Para mejorar los problemas de rendimiento, omita lo siguiente:

Encabezados de solicitud y respuesta
Registro del cuerpo

Troubleshooting

Solucionar el problema del flujo de datos de telemetría de API Management a Application Insights:

Investigue si existe un recurso vinculado de ámbito de Private Link (AMPLS) de Azure Monitor dentro de la red virtual donde está conectado el recurso de API Management. Los recursos de AMPLS tienen un ámbito global entre suscripciones y son responsables de administrar la consulta de datos y la ingesta de todos los recursos de Azure Monitor. Es posible que AMPLS se haya configurado con un modo de acceso Private-Only específicamente para la ingesta de datos. En tales casos, incluya el recurso de Application Insights y su recurso de Log Analytics asociado en AMPLS. Una vez realizada esta adición, los datos de API Management se ingerirán correctamente en el recurso de Application Insights, resolviendo el problema de transmisión de datos de telemetría.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-09-17

Cómo integrar Azure API Management con Aplicación de Azure Insights

Prerequisites

Información general sobre el escenario

Crea una conexión usando el portal de Azure

Crea una conexión utilizando la API REST, Bicep o plantilla ARM

Registrador con cadena de conexión y credenciales de identidad administrada (recomendado)

Cadena de conexión con identidad administrada asignada por el sistema

Cadena de conexión con identidad administrada asignada por el usuario

Registrador con credenciales de cadena de conexión solo

Habilitación del registro Application Insights para la API

Registradores para una sola API o todas las API

Qué datos se agregan a Application Insights

Telemetría de dependencias externas para políticas soportadas

Emisión de métricas personalizadas

Límites de métricas personalizadas

Consecuencias en el rendimiento y muestreo de registros

Troubleshooting

Contenido relacionado

Comentarios

Recursos adicionales