Compartir vía

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.

Nota:

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.

Advertencia

Al usar nuestra puerta de enlace autohospedada, no garantizamos que toda la telemetría se envíe a Azure Application Insights, ya que depende del almacenamiento en búfer en memoria de Application Insights.

Requisitos previos

Información general del escenario

Estos son los pasos de alto nivel para este escenario.

  1. En primer lugar, 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.

    Importante

    Actualmente, en el portal, API Management solo admite conexiones a Application Insights mediante una clave de instrumentación de Application Insights. Para una mayor seguridad, recomendamos usar una cadena de conexión de Application Insights con una identidad administrada 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. Obtenga más información sobre la cadena de conexión de Application Insights.

    Nota:

    Si su recurso de Application Insights se encuentra en un inquilino diferente, deberá crear el registrador usando la API de REST o herramientas relacionadas como se muestra en una sección posterior de este artículo.

  2. En segundo lugar, habilite el registro de Application Insights para sus 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.

Nota:

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.

  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 plantilla API de REST, Bicep o ARM para crear un registrador de Application Insights para su instancia de API Management. Puede configurar un registrador que use una cadena de conexión con credenciales de identidad administradas (recomendado), o un registrador que solo use una cadena de conexión.

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

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":"<ClientID>"
    }
  }
}

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 de REST Registrador de área de trabajo: crear o actualizar.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "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.

  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 usando directivas como emit-metric y azure-openai-emit-token-metric. La sección siguiente usa la directiva emit-metric como ejemplo.

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 una directiva de API Management como emit-metric o azure-openai-emit-token-metric:

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

  • El número de series temporales activas generadas por la directiva 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 contribuiría a 1000 (10 x 10 x 10) series temporales activas.

  • 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

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.

Contenido relacionado