Recopilación y lectura de datos de OpenTelemetry en Azure Container Apps (versión preliminar)

Artículo
12/16/2024

Usando un agente de datos de OpenTelemetry con el entorno de Azure Container Apps, puede elegir enviar datos de observabilidad en un formato OpenTelemetry mediante:

Canalización de datos de un agente a un punto de conexión deseado. Entre las opciones de destino se incluyen Datadog, Application Insights de Azure Monitor y cualquier punto de conexión compatible con OpenTelemetry Protocol (OTLP).
Cambiar fácilmente los puntos de conexión de destino sin tener que volver a configurar cómo emiten los datos y sin tener que ejecutar manualmente un agente de OpenTelemetry.

En este artículo se muestra cómo configurar un agente de OpenTelemetry para la aplicación contenedora.

Configuración de un agente de OpenTelemetry

Los agentes de OpenTelemetry residen en el entorno de la aplicación contenedora. Puede configurar la configuración del agente a través de una plantilla de ARM o llamadas de Bicep al entorno, o a través de la CLI, o a través de Terraform (a través del Proveedor AzAP).

Cada tipo de punto de conexión (Azure Monitor Application Insights, DataDog y OTLP) tiene requisitos de configuración específicos.

Requisitos previos

La habilitación del agente de OpenTelemetry administrado en el entorno no significa automáticamente que el agente recopile datos. Los agentes solo envían datos en función de los valores de configuración e instrumentan el código correctamente.

Configure el código fuente

Prepare la aplicación para recopilar datos mediante la instalación del SDK de OpenTelemetry y siga las directrices de OpenTelemetry para instrumentar métricas, registros o seguimientos.

Inicializar puntos de conexión

Para poder enviar datos a un destino de recopilación, primero debe crear una instancia del servicio de destino. Por ejemplo, si desea enviar datos a Application Insights de Azure Monitor, debe crear una instancia de Application Insights con antelación.

El agente de OpenTelemetry administrado acepta los siguientes destinos:

Azure Monitor Application Insights
Datadog
Cualquier punto de conexión de OTLP (por ejemplo: New Relic o Honeycomb)

En la tabla siguiente se muestra el tipo de datos que puede enviar a cada destino:

Destino	Registros	Métricas	Traces
Azure App Insights	Sí	No	Sí
Datadog	No	Sí	Sí
Punto de conexión configurado del protocolo OpenTelemetry (OTLP)	Sí	Sí	Sí

Azure Monitor Application Insights

El único detalle de configuración necesario en Application Insights es la cadena de conexión. Una vez que tenga la cadena de conexión, puede configurar el agente a través de la plantilla de ARM de la aplicación de contenedor, con comandos de la CLI de Azure o Terraform.

La cadena de conexión contiene una clave de instrumentación, que es un identificador único que se usa para asociar la telemetría a un recurso específico de Application Insights. Las claves de instrumentación no son tokens de seguridad ni claves de seguridad y no se consideran secretos.

Si desea proteger el recurso de Application Insights contra el uso incorrecto, consulte Autenticación de Microsoft Entra para Application Insights.

Antes de implementar esta plantilla, reemplace los marcadores de posición rodeados por <> con sus valores.

{
  ...
  "properties": {
    "appInsightsConfiguration ": {  
      "connectionString": "<APP_INSIGHTS_CONNECTION_STRING>"
    }
    "openTelemetryConfiguration": {
      ...
      "tracesConfiguration":{
        "destinations": ["appInsights"]
      },
      "logsConfiguration": {
        "destinations": ["appInsights"]
      }
    }
  }
}

Antes de ejecutar el comando siguiente, reemplace los marcadores de posición rodeados por <> con sus valores.

az containerapp env telemetry app-insights set \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --connection-string <APP_INSIGHTS_CONNECTION_STRING> \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-logs true

Nota:

Debido a la sensibilidad de la cadena de conexión, no podrá ver los valores detallados de la cadena de conexión cuando regrese el comando. El sistema lo mostrará como null.

resource "azapi_update_resource" "app_insights_open_telemetry_integration" {
  name      = azurerm_container_app_environment.managed_environment.name
  parent_id = azurerm_resource_group.resource_group.id
  type      = "Microsoft.App/managedEnvironments@2023-11-02-preview"
  body = jsonencode({
    properties = {
      appInsightsConfiguration = {
        connectionString = azurerm_application_insights.applicationinsights.connection_string
      }
      appLogsConfiguration = {
        destination = "log-analytics"
        logAnalyticsConfiguration = {
          customerId = azurerm_log_analytics_workspace.workspace.workspace_id
          sharedKey  = azurerm_log_analytics_workspace.workspace.primary_shared_key
        }
      }
      openTelemetryConfiguration = {
        tracesConfiguration = {
          destinations = ["appInsights"]
        }
        logsConfiguration = {
          destinations = ["appInsights"]
        }
      }
    }
  })
}

Datadog

La configuración del agente de Datadog requiere un valor para site y key desde la instancia de Datadog. Recopile estos valores de la instancia de Datadog según esta tabla:

Propiedad del agente de Datadog	Propiedad de configuración de Container Apps
`DD_SITE`	`site`
`DD_API_KEY`	`key`

Una vez que tenga estos detalles de configuración, puede configurar el agente a través de la plantilla de ARM de la aplicación contenedora o con comandos de la CLI de Azure.

Evite especificar el valor de un secreto, como la clave de API de Datadog, directamente en un entorno de producción. En su lugar, use una referencia a un secreto almacenado en Azure Key Vault.

Debe habilitar el almacén de claves para la implementación de plantillas. Para ello, cree el almacén de claves con la propiedad enabledForTemplateDeployment habilitada o ejecute el siguiente comando de la CLI de Azure, reemplazando el <KEY_VAULT_NAME> por su valor:

az keyvault update --name <KEY_VAULT_NAME> --enabled-for-template-deployment true

Para más información, vea:

Cree un archivo de parámetros para recuperar la clave de API de Datadog desde una instancia de Azure Key Vault.

Antes de implementar los siguientes archivos, reemplace los marcadores de posición rodeados por los <> valores.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "datadogapikey": {
      "reference": {
        "keyVault": {
          "id": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT_NAME>"
        },
        "secretName": "<KEY_VAULT_SECRET_NAME>"
      }
    }
  }
}

Ahora puede hacer referencia al parámetro datadogapikey en la plantilla de ARM.

{
  ...
  "parameters": {
    "datadogapikey": {
      "type": "securestring"
    }
  },
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "destinationsConfiguration":{
        ...
        "dataDogConfiguration":{
          "site": "<YOUR_DATADOG_SUBDOMAIN>.datadoghq.com",
          "key": "<YOUR_DATADOG_KEY>"
        }
      },
      "tracesConfiguration":{
        "destinations": ["dataDog"]
      },
      "metricsConfiguration": {
        "destinations": ["dataDog"]
      }
    }
  }
}

Para implementar el recurso, ejecute el siguiente comando de la CLI de Azure, reemplazando los marcadores de posición rodeados por <> los valores.

az deployment group create \
  --resource-group <RESOURCE_GROUP> \
  --template-file <ARM_TEMPLATE_FILE> \
  --parameters <PARAMETER_FILE>

Antes de ejecutar el comando siguiente, reemplace los marcadores de posición rodeados por <> con sus valores.

az containerapp env telemetry data-dog set \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --site  "<DATADOG_SUBDOMAIN>.datadoghq.com" \
  --key <DATADOG_KEY> \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-metrics true

Nota:

Debido a la sensibilidad de la clave, no podrá ver los valores detallados de la clave cuando regrese el comando. El sistema lo mostrará como null.

resource "azapi_update_resource" "app_insights_open_telemetry_integration" {
  name      = azurerm_container_app_environment.managed_environment.name
  parent_id = azurerm_resource_group.resource_group.id
  type      = "Microsoft.App/managedEnvironments@2023-11-02-preview"
  body = jsonencode({
    properties = {
      openTelemetryConfiguration = {
        destinationsConfiguration = {
          dataDogConfiguration = {
            site = "<YOUR_DATADOG_SUBDOMAIN>.datadoghq.com"
            key = "<YOUR_DATADOG_KEY>"
          }
        }
        tracesConfiguration = {
          destinations = ["dataDog"]
        }
        metricsConfiguration = {
          destinations = ["dataDog"]
        }
      }
    }
  })
}

Punto de conexión de OTLP

Un punto de conexión del protocolo OpenTelemetry (OTLP) es un destino de datos de telemetría que consume datos de OpenTelemetry. En la configuración de la aplicación, puede agregar varios puntos de conexión de OTLP. En el ejemplo siguiente se agregan dos puntos de conexión y se envían los siguientes datos a estos puntos de conexión.

Nombre del extremo	Datos enviados al punto de conexión
`oltp1`	Métricas o seguimientos
`oltp2`	Registros o seguimientos

Aunque puede configurar tantos puntos de conexión configurados por OTLP como desee, cada punto de conexión debe tener un nombre distinto.

{
  "properties": {
    "appInsightsConfiguration": {},
    "openTelemetryConfiguration": {
      "destinationsConfiguration":{
        "otlpConfigurations": [
          {
            "name": "otlp1",
            "endpoint": "ENDPOINT_URL_1",
            "insecure": false,
            "headers": "api-key-1=key"
          },
          {
            "name": "otlp2",
            "endpoint": "ENDPOINT_URL_2",
            "insecure": true
          }
        ]
      },
      "logsConfiguration": { 
        "destinations": ["otlp2"]
      },
      "tracesConfiguration":{
        "destinations": ["otlp1", "otlp2"]
      },
      "metricsConfiguration": {
        "destinations": ["otlp1"]
      }
    }
  }
}

az containerapp env telemetry otlp add \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --otlp-name "otlp1" \
  --endpoint "ENDPOINT_URL_1" \
  --insecure false \
  --headers "api-key-1=key" \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-metrics true
az containerapp env telemetry otlp add \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --otlp-name "otlp2" \
  --endpoint "ENDPOINT_URL_2" \
  --insecure true \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-logs true

Nota:

Debido a la sensibilidad del valor de los encabezados, no podrá ver los valores detallados del valor de los encabezados cuando regrese el comando. El sistema los mostrará como null.

resource "azapi_update_resource" "app_insights_open_telemetry_integration" {
  name      = azurerm_container_app_environment.managed_environment.name
  parent_id = azurerm_resource_group.resource_group.id
  type      = "Microsoft.App/managedEnvironments@2023-11-02-preview"
  body = jsonencode({
    properties = {
      openTelemetryConfiguration = {
        destinationsConfiguration = {
          otlpConfigurations = [
            {
              name = "otlp1"
              endpoint = "ENDPOINT_URL_1"
              insecure = false
              headers = "api-key-1=key"
            },
            {
              name = "otlp2"
              endpoint = "ENDPOINT_URL_2"
              insecure = true
            }
          ]
        }
        logsConfiguration = { 
          destinations = [
            "otlp2"
          ]
        },
        tracesConfiguration = {
          destinations = [
            "otlp1",
            "otlp2"
          ]
        },
        metricsConfiguration = {
          destinations = [
            "otlp1"
          ]
        }
      }
    }
  })
}

Nombre	Descripción
`resource-group`	Nombre del grupo de recursos. Puede configurar el grupo predeterminado mediante `az configure --defaults group=<NAME>`.
`name`	Nombre del entorno de Container Apps.
`otlp-name`	Un nombre que selecciona para identificar el punto de conexión configurado por OTLP.
`endpoint`	Dirección URL del destino que recibe los datos recopilados.
`insecure`	El valor predeterminado es true. Define si se habilita la seguridad de transporte de cliente para la conexión gRPC del exportador. Si es false, se requiere el parámetro `headers`.
`headers`	Valores separados por espacios, en formato "key=value", que proporciona información necesaria para la seguridad de los puntos de conexión de OTLP. Ejemplo: `"api-key=key other-config-value=value"`.

Configurar destinos de datos

Para configurar un agente, use la matriz destinations para definir qué agentes envía la aplicación los datos. Las claves válidas son appInsights, dataDog o el nombre del punto de conexión de OTLP personalizado. Puede controlar cómo se comporta un agente en función del tipo de datos y las opciones relacionadas con el punto de conexión.

Por tipo de datos

Opción	Ejemplo
Seleccione un tipo de datos.	Puede configurar registros, métricas o seguimientos individualmente.
Habilite o deshabilite cualquier tipo de datos.	Puede optar por enviar solo seguimientos y ningún otro dato.
Envíe un tipo de datos a varios puntos de conexión.	Puede enviar registros tanto a DataDog como a un punto de conexión configurado por OTLP.
Enviar diferentes tipos de datos a diferentes ubicaciones.	Puede enviar seguimientos a un punto de conexión de OTLP y métricas a DataDog.
Deshabilitar el envío de todos los tipos de datos.	Puede optar por no enviar ningún dato a través del agente de OpenTelemetry.

Por punto de conexión

Solo puede configurar un punto de conexión de Application Insights y Datadog cada vez.
Aunque puede definir más de un punto de conexión configurado por OTLP, cada uno debe tener un nombre distinto.

En la plantilla de ARM de ejemplo siguiente se muestra cómo usar un punto de conexión de OTLP denominado customDashboard. Envía:

seguimientos a App Insights y customDashboard
registros a App Insights y customDashboard
métricas a DataDog y customDashboard

{
  ...
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "tracesConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "logsConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "metricsConfiguration": {
        "destinations": [
          "dataDog",
          "customDashboard"
        ]
      }
    }
  }
}

Ejemplo de configuración de OpenTelemetry

En la plantilla de ARM de ejemplo siguiente, se muestra cómo configurar la aplicación contenedora para recopilar datos de telemetría mediante Azure Monitor Application Insights, Datadog y con un agente de OTLP personalizado denominado customDashboard.

Este ejemplo funciona con el archivo de parámetros que se usa para recuperar la clave de Datadog API de una instancia de Azure Key Vault.

Antes de implementar esta plantilla, reemplace los marcadores de posición rodeados por <> con sus valores.

{
  "location": "eastus",
  "properties": {
    "appInsightsConfiguration": {
      "connectionString": "<APP_INSIGHTS_CONNECTION_STRING>"
    },
    "openTelemetryConfiguration": {
      "destinationsConfiguration": {
        "dataDogConfiguration": {
          "site": "datadoghq.com",
          "key": "parameters('datadogapikey')]"
        },
        "otlpConfigurations": [
          {
            "name": "customDashboard",
            "endpoint": "<OTLP_ENDPOINT_URL>",
            "insecure": true
          }
        ]
      },
      "tracesConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "logsConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "metricsConfiguration": {
        "destinations": [
          "dataDog",
          "customDashboard"
        ]
      }
    }
  }
}

Para obtener más información, consulte Microsoft.App/managedEnvironments.

Variables de entorno

El agente de OpenTelemetry inserta automáticamente un conjunto de variables de entorno en la aplicación en tiempo de ejecución.

Las dos primeras variables de entorno siguen la configuración estándar del exportador de OpenTelemetry y se usan en kits de desarrollo de software estándar de OTLP. Si establece explícitamente la variable de entorno en la especificación de la aplicación contenedora, el valor sobrescribe el valor insertado automáticamente.

Obtenga información sobre la configuración del exportador de OTLP, consulte Configuración del exportador de OTLP.

Nombre	Descripción
`OTEL_EXPORTER_OTLP_ENDPOINT`	Dirección URL del punto de conexión base para cualquier tipo de señal, con un número de puerto especificado opcionalmente. Esta configuración es útil cuando se envía más de una señal al mismo punto de conexión y se desea que una variable de entorno controle el punto de conexión. Ejemplo: `http://otel.service.k8se-apps:4317/`
`OTEL_EXPORTER_OTLP_PROTOCOL`	Especifica el protocolo de transporte OTLP usado para todos los datos de telemetría. El agente administrado solo admite `grpc`. Valor: `grpc`.

Las otras tres variables de entorno son específicas de Azure Container Apps y siempre se insertan. Estas variables contienen las direcciones URL del punto de conexión del agente para cada tipo de datos específico (registros, métricas, seguimientos).

Estas variables solo son necesarias si usa el agente OpenTelemetry administrado y otro agente de OpenTelemetry. El uso de estas variables proporciona control sobre cómo enrutar los datos entre los distintos agentes de OpenTelemetry.

Nombre	Descripción	Ejemplo
`CONTAINERAPP_OTEL_TRACING_GRPC_ENDPOINT`	Dirección URL del punto de conexión solo para los datos de seguimiento.	`http://otel.service.k8se-apps:43178/v1/traces/`
`CONTAINERAPP_OTEL_LOGGING_GRPC_ENDPOINT`	Dirección URL del punto de conexión solo para los datos de registro.	`http://otel.service.k8se-apps:43178/v1/logs/`
`CONTAINERAPP_OTEL_METRIC_GRPC_ENDPOINT`	Dirección URL del punto de conexión solo para los datos de métricas.	`http://otel.service.k8se-apps:43178/v1/metrics/`

Costos del agente de OpenTelemetry

Se le factura por el proceso informático subyacente del agente.

Consulte el servicio de destino para conocer sus términos y estructura de facturación. Por ejemplo, si envía datos a Application Insights de Azure Monitor y Datadog, es responsable de los cargos aplicados por ambos servicios.

Limitaciones conocidas

Los agentes de OpenTelemetry están en versión preliminar.
Los datos del sistema, como los registros del sistema o las métricas estándar de Container Apps, no están disponibles para enviarse al agente de OpenTelemetry.
El punto de conexión de Application Insights no acepta métricas.
El punto de conexión de Datadog no acepta registros.

Pasos siguientes

Más información sobre la supervisión y el estado

Compartir vía

Recopilación y lectura de datos de OpenTelemetry en Azure Container Apps (versión preliminar)

Configuración de un agente de OpenTelemetry

Requisitos previos

Configure el código fuente

Inicializar puntos de conexión

Azure Monitor Application Insights

Datadog

Punto de conexión de OTLP

Configurar destinos de datos

Por tipo de datos

Por punto de conexión

Ejemplo de configuración de OpenTelemetry

Variables de entorno

Costos del agente de OpenTelemetry

Limitaciones conocidas

Pasos siguientes

Comentarios

Recursos adicionales