Cómo integrar Azure API Management con Azure Application Insights

  • Artículo

SE APLICA A: todos los niveles de API Management

Puede integrar fácilmente Azure Application Insights con Azure API Management. Azure Application 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.

Prerrequisitos

Información general del escenario

Estos son los pasos de alto nivel para este escenario.

  1. Primero, 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 de REST o las herramientas de Azure relacionadas. API Management configura un recurso de registrador para la conexión.

    Nota:

    Si el recurso de Application Insights está en un inquilino diferente, tendrá que crear el registrador mediante la API de REST.

    Importante

    Actualmente, en el portal, API Management solo admite conexiones a Application Insights mediante una clave de instrumentación de Application Insights. Para usar una cadena de conexión de Application Insights o una identidad administrada de API Management, use la API de REST, Bicep o una plantilla de ARM para crear el registrador. Obtenga más información sobre la cadena de conexión de Application Insights.

  2. En segundo lugar, habilitará el registro de Application Insights para la API.

    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.

Creación de una conexión mediante Azure Portal

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

  1. Vaya a la instancia del servicio Azure API Management en Azure Portal.

  2. Seleccione Application Insights en el menú de la izquierda.

  3. Seleccione +Agregar.
    Captura de pantalla en la que se muestra dónde agregar una conexión nueva

  4. Seleccione la instancia de Application Insights que ha creado antes y proporcione una descripción breve.

  5. 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 valida periódicamente si el punto de conexión de puerta de enlace de API Management está respondiendo.
    • Los resultados aparecerán en el panel Disponibilidad de la instancia de Application Insights.

  6. Seleccione Crear.

  7. Compruebe que el nuevo registrador de Application Insights aparece ahora en la lista.

    Captura de pantalla en la que se muestra dónde ver el registrador de Application Insights recién creado.

Nota

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.

Sugerencia

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.

Creación de una conexión mediante la API de REST, Bicep o la plantilla de ARM

Siga estos pasos para usar la API de REST, Bicep o la plantilla de ARM para crear una conexión entre Application Insights y API Management. Puede configurar un registrador que use una cadena de conexión, una identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario.

Registrador con credenciales de cadena de conexión

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

Use la API de REST de API Management con el siguiente cuerpo de solicitud.

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

Registrador con credenciales de identidad administrada asignadas por el sistema

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

Use la API de REST de API Management con el siguiente cuerpo de solicitud.

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

Registrador con credenciales de identidad administrada asignadas por el usuario

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

Use la API de REST de API Management con el siguiente cuerpo de solicitud.

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

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.

  1. Vaya a la instancia del servicio Azure API Management en Azure Portal.

  2. Seleccione API del menú de la izquierda.

  3. Haga clic en la API, en este caso, Demo Conference API. Si está configurado, seleccione una versión.

    Sugerencia

    Para habilitar el registro para todas las API, seleccione Todas las API.

  4. Vaya a la pestaña Configuración de la barra superior.

  5. Desplácese hacia abajo hasta la sección Diagnostics Logs (Registros de diagnóstico).
    Registrador de App Insights

  6. Marque la casilla Habilitar.

  7. Seleccione el registrador adjunto en el menú desplegable Destino.

  8. Escriba 100 como Sampling (%) [Muestreo (%)] y seleccione la casilla Always log errors (Registrar errores siempre).

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

    Advertencia

    Reemplazar el valor predeterminado 0 en el campo Number of payload bytes to log (Número de bytes de carga que se van a registrar) puede disminuir considerablemente el rendimiento de las API.

  10. Seleccione Guardar.

  11. En segundo plano, se crea una entidad Diagnostic (Diagnóstico) con el nombre applicationinsights en el nivel de API.

Nota

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

Puede especificar registradores en distintos niveles:

  • Registrador de una API.
  • Registrador para todas las API.

Especificación de los dos:

  • 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 ambos registradores para recibir telemetría (multiplexación), póngase en contacto con el soporte técnico de Microsoft. Tenga en cuenta que no se admite la multiplexación si usa el mismo registrador (destino de Application Insights) en el nivel "Todas las API" y en el nivel de una sola API. 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 Descripción
Solicitar Para cada solicitud entrante:
  • solicitud de front-end
  • respuesta de front-end
Dependencia Para cada solicitud reenviada a un servicio de back-end:
  • solicitud de back-end
  • respuesta de back-end
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
Seguimiento 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.

Nota

Consulte los límites de Application Insights para más información sobre el tamaño máximo y el número de métricas y eventos por instancia de Application Insights.

Emisión de métricas personalizadas

Puede emitir métricas personalizadas a Application Insights desde la instancia de API Management. API Management emite métricas personalizadas mediante la directiva emit-metric.

Nota

Las métricas personalizadas son una característica en vista previa (GB) de Azure Monitor y están sujetas a limitaciones.

Para emitir métricas personalizadas, realice los siguientes pasos de configuración.

  1. Habilite Métricas personalizadas (versión preliminar) con dimensiones personalizadas en su instancia de Application Insights.

    1. Navegue a la instancia de Application Insights en el portal.
    2. En el menú de la izquierda, seleccione Usos y costos estimados.
    3. Seleccione Métricas personalizadas (versión preliminar)>Con dimensiones.
    4. Seleccione Aceptar.

  2. Agregue la propiedad "metrics": true a la entidad de diagnóstico applicationInsights configurada en API Management. Actualmente, debe agregar esta propiedad mediante la API de REST Diagnóstico: Crear o actualizar de API Management. Por ejemplo:

    PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
        "metrics": true
        [...]
    }
}

  3. Asegúrese de que el registrador de Application Insights esté configurado en el ámbito en el que desea emitir métricas personalizadas (ya sea todas las API 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.

  4. Configure la directiva emit-metric en un ámbito en el que el registro de Application Insights esté configurado (ya sea todas las API 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).

Estos límites tienen las siguientes implicaciones para configurar métricas personalizadas en API Management:

  • Puede configurar un máximo de 10 dimensiones personalizadas por directiva emit-metric.

  • El número de series temporales activas generadas por la directiva emit-metric en un período de 12 horas es el producto del número de valores únicos de cada dimensión configurada durante el período. 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 emit-metric contribuiría a 1000 (10 x 10 x 10) series temporales activas.

  • Si configura la directiva emit-metric 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.

Consecuencias en el rendimiento y muestreo de registros

Advertencia

Registrar todos los eventos puede tener graves consecuencias en el rendimiento, según la tasa de solicitudes de entrada.

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 se ha creado para:

  • 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 respuesta y solicitud.
  • Registro del cuerpo.

Vídeo

Solución de problemas

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

  • Investigue si existe un recurso de ámbito de Private Link de Azure Monitor (AMPLS) vinculado 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 solo privado 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.

Pasos siguientes