Compartir a través de

Uso de OpenTelemetry con Azure Functions

En este artículo se muestra cómo configurar la aplicación de funciones para exportar datos de registro y seguimiento en un formato OpenTelemetry. Azure Functions genera datos de telemetría en las ejecuciones de funciones tanto del proceso de host de Functions como del proceso de trabajo específico del lenguaje en el que se ejecuta el código de función. De forma predeterminada, estos datos de telemetría se envían a Application Insights mediante el SDK de Application Insights. Sin embargo, puede optar por exportar estos datos mediante la semántica de OpenTelemetry. Aunque todavía puede usar un formato OpenTelemetry para enviar los datos a Application Insights, ahora también puede exportar los mismos datos a cualquier otro punto de conexión compatible con OpenTelemetry.

Puede obtener estas ventajas habilitando OpenTelemetry en la aplicación de funciones:

  • Correlaciona los datos entre rastros y registros que se generan tanto en el host como en el código de la aplicación.
  • Permite una generación coherente basada en estándares de datos de telemetría exportables.
  • Se integra con otros proveedores que pueden consumir datos compatibles con OpenTelemetry.

Tenga en cuenta estas consideraciones al usar este artículo:

  • Pruebe el tutorial de OpenTelemetry, que está diseñado para ayudarle a empezar a trabajar rápidamente con OpenTelemetry y Azure Functions. En este artículo se usa la CLI para desarrolladores de Azure (azd) para crear e implementar una aplicación de funciones que use la integración de OpenTelemetry para el seguimiento distribuido.

  • Dado que este artículo está dirigido al lenguaje de desarrollo que prefiera, recuerde elegir el idioma correcto en la parte superior del artículo.

  • OpenTelemetry está habilitado en el nivel de aplicación de funciones, tanto en la configuración del host (host.json) como en el proyecto de código. Functions también proporciona una experiencia optimizada para el cliente para exportar datos de OpenTelemetry desde el código de función que se ejecuta en un proceso de trabajo específico del lenguaje.

Habilitación de OpenTelemetry en el host de Functions

Al habilitar la salida de OpenTelemetry en el archivo host.json de la aplicación de funciones, el host exporta la salida de OpenTelemetry, independientemente del stack de lenguaje que utilice la aplicación.

Para habilitar la salida de OpenTelemetry desde el host de Functions, actualice el archivo host.json en el proyecto de código para agregar un elemento "telemetryMode": "OpenTelemetry" a la colección raíz. Con OpenTelemetry habilitado, el archivo host.json podría tener este aspecto:

{
    "version": "2.0",
    "telemetryMode": "OpenTelemetry",
    ...
}

Configuración de la aplicación

Al habilitar OpenTelemetry en el host.json archivo, las variables de entorno de la aplicación determinan los puntos de conexión para enviar datos en función de la configuración de la aplicación compatible con OpenTelemetry.

Cree una configuración de aplicación específica en la aplicación de funciones en función del destino de salida de OpenTelemetry. Cuando se proporciona la configuración de conexión para Application Insights y un exportador del protocolo OpenTelemetry (OTLP), los datos de OpenTelemetry se envían a ambos puntos de conexión.

APPLICATIONINSIGHTS_CONNECTION_STRING: la cadena de conexión de un área de trabajo de Application Insights. Cuando esta configuración existe, los datos de OpenTelemetry se envían a esa área de trabajo. Use la misma configuración para conectarse a Application Insights sin OpenTelemetry habilitado. Si la aplicación aún no tiene esta configuración, es posible que tenga que Habilitar la integración de Application Insights.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: establézcalo en true para que el host de Functions permita al proceso de trabajo de Java transmitir los registros de OpenTelemetry directamente, lo que evita entradas duplicadas de nivel de host.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: establézcalo en true para que el host de Functions permita al proceso de trabajo de Python transmitir los registros de OpenTelemetry directamente, lo que evita entradas duplicadas de nivel de host.

Habilitación de OpenTelemetry en la aplicación

Después de configurar el host de Functions para que use OpenTelemetry, actualice el código de la aplicación para generar datos de OpenTelemetry. Al habilitar OpenTelemetry tanto en el host como en el código de la aplicación, obtendrá una mejor correlación entre los seguimientos y los registros que emite el proceso host de Functions y el proceso de trabajo del lenguaje.

La instrumentación de la aplicación para usar OpenTelemetry depende del punto de conexión de OpenTelemetry de destino:

En los ejemplos de este artículo se supone que la aplicación usa IHostApplicationBuilder, que está disponible en la versión 2.x y posterior de Microsoft.Azure.Functions.Worker. Para obtener más información, vea Versión 2.x en la guía del modelo de trabajo aislado de C#.

  1. Ejecute estos comandos para instalar los ensamblados necesarios en la aplicación:

    dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting 
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

  2. En el archivo de proyecto de Program.cs, agregue esta instrucción using:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Configura OpenTelemetry según si el inicio de tu proyecto utiliza IHostBuilder o IHostApplicationBuilder. Este último se introdujo en la versión 2.x de la extensión de modelo de trabajo aislado de .NET.

    En program.cs, agregue esta línea de código después ConfigureFunctionsWebApplicationde :

    builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

    Puede exportar a ambos puntos de conexión de OpenTelemetry desde la misma aplicación.

  1. Agregue las bibliotecas necesarias a la aplicación. La forma de agregar bibliotecas depende de si implementa mediante Maven o Kotlin y si también desea enviar datos a Application Insights.

    <dependency>
  <groupId>com.microsoft.azure.functions</groupId>
  <artifactId>azure-functions-java-opentelemetry</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
  <version>1.2.0</version>
</dependency>

  2. (Opcional) Agregue este código para crear intervalos personalizados:

    import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.context.Scope;

Span span = FunctionsOpenTelemetry.startSpan(
        "com.contoso.PaymentFunction",  // tracer name
        "validateCharge",               // span name
        null,                           // parent = current context
        SpanKind.INTERNAL);

try (Scope ignored = span.makeCurrent()) {
    // business logic here
} finally {
    span.end();
}

  1. Instale estos paquetes de npm en el proyecto:

    npm install @opentelemetry/api 
npm install @opentelemetry/auto-instrumentations-node 
npm install @azure/monitor-opentelemetry-exporter 
npm install @azure/functions-opentelemetry-instrumentation

  1. Cree un archivo de código en el proyecto, copie y pegue el código siguiente en este nuevo archivo y guarde el archivo como src/index.js:

    const { AzureFunctionsInstrumentation } = require('@azure/functions-opentelemetry-instrumentation');
const { AzureMonitorLogExporter, AzureMonitorTraceExporter } = require('@azure/monitor-opentelemetry-exporter');
const { getNodeAutoInstrumentations, getResourceDetectors } = require('@opentelemetry/auto-instrumentations-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { detectResourcesSync } = require('@opentelemetry/resources');
const { LoggerProvider, SimpleLogRecordProcessor } = require('@opentelemetry/sdk-logs');
const { NodeTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-node');

const resource = detectResourcesSync({ detectors: getResourceDetectors() });

const tracerProvider = new NodeTracerProvider({ resource });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new AzureMonitorTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new AzureMonitorLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

  2. Actualice el main campo del archivo package.json para incluir el nuevo src/index.js archivo. Por ejemplo:

    "main": "src/{index.js,functions/*.js}"

  1. Cree un archivo de código en el proyecto, copie y pegue el código siguiente en este nuevo archivo y guarde el archivo como src/index.ts:

    import { AzureFunctionsInstrumentation } from '@azure/functions-opentelemetry-instrumentation';
import { AzureMonitorLogExporter, AzureMonitorTraceExporter } from '@azure/monitor-opentelemetry-exporter';
import { getNodeAutoInstrumentations, getResourceDetectors } from '@opentelemetry/auto-instrumentations-node';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { detectResourcesSync } from '@opentelemetry/resources';
import { LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { NodeTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';

const resource = detectResourcesSync({ detectors: getResourceDetectors() });

const tracerProvider = new NodeTracerProvider({ resource });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new AzureMonitorTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new AzureMonitorLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

  2. Actualice el campo main del archivo package.json para incluir la salida de este nuevo archivo de src/index.ts, que podría tener este aspecto:

    "main": "dist/src/{index.js,functions/*.js}"

Importante

La salida de OpenTelemetry a Application Insights desde el trabajo de lenguaje no se admite actualmente para las aplicaciones de PowerShell. Es posible que quiera usar un punto de conexión de exportador de OTLP. Al configurar el host para la salida de OpenTelemetry en Application Insights, los registros generados por el proceso de trabajo de PowerShell siguen reenviados, pero el seguimiento distribuido no se admite en este momento.

Estas instrucciones solo se aplican a un exportador de OTLP:

  1. Agregue una configuración de aplicación denominada OTEL_FUNCTIONS_WORKER_ENABLED con el valor de True.

  2. Cree una carpeta a Modulesnivel de aplicación en la raíz de su aplicación y ejecute el siguiente comando:

    Save-Module -Name AzureFunctions.PowerShell.OpenTelemetry.SDK

    Este comando instala el módulo necesario AzureFunctions.PowerShell.OpenTelemetry.SDK directamente en la aplicación. No puede usar el archivo requirements.psd1 para instalar automáticamente esta dependencia porque las dependencias administradas no se admiten actualmente en la versión preliminar del plan de consumo flexible.

  3. Agregue este código al archivo profile.ps1:

    Import-Module AzureFunctions.PowerShell.OpenTelemetry.SDK -Force -ErrorAction Stop 
Initialize-FunctionsOpenTelemetry

  1. Asegúrese de que estas bibliotecas están en su archivo requirements.txt, ya sea quitando la marca de comentario o agregándolas por su cuenta:

    azure-monitor-opentelemetry

  2. Agregue este código al archivo de punto de entrada principal de function_app.py :

    Si ya ha agregado PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true en la configuración de la aplicación, puede omitir este paso. Para habilitar manualmente la recopilación de Application Insights sin instrumentación automática, agregue este código a la aplicación:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Revise la documentación sobre el uso de distribución de Azure Monitor para ver las opciones sobre cómo configurar aún más el SDK.

Consideraciones para OpenTelemetry

Al exportar los datos mediante OpenTelemetry, tenga en cuenta estas consideraciones.

  • El portal de Azure únicamente admite seguimientos de Recent function invocation si la telemetría se envía a Azure Monitor.

  • Al configurar el host para que use OpenTelemetry, Azure Portal no admite el streaming de registros.

  • Si establece telemetryMode a OpenTelemetry, la configuración en la sección logging.applicationInsights de host.json no se aplica.

  • Los intervalos personalizados incluyen automáticamente todos los atributos de recursos y usan los exportadores configurados en la aplicación.

  • Cuando la aplicación se ejecuta fuera de Azure, incluido durante el desarrollo local, el detector de recursos establece el service.name atributo en java-function-app de forma predeterminada.

  • Use estas marcas de máquina virtual Java (JVM) para silenciar la telemetría cuando se ejecuta localmente durante las pruebas unitarias:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • No es necesario registrar manualmente el middleware; el trabajador de Java descubre automáticamente OpenTelemetryInvocationMiddleware.

Solución de problemas

Al exportar los datos mediante OpenTelemetry, tenga en cuenta estos problemas y soluciones comunes.

Filtrado de registros

Para configurar correctamente la filtración de registros en su aplicación de funciones, necesita comprender la diferencia entre el proceso de host y el de trabajo.

El proceso anfitrión es el componente de ejecución de Azure Functions que administra desencadenadores, escalamiento y emite telemetría a nivel de sistema, como los registros de inicialización, las tareas de seguimiento de solicitudes y la información sobre el estado del tiempo de ejecución.

El proceso de trabajo es específico del lenguaje, ejecuta el código de la función y genera registros de aplicaciones y telemetría de forma independiente.

Importante

Los filtros definidos en host.json solo se aplican a los registros generados por el proceso host. Se deben usar configuraciones de OpenTelemetry específicas para el lenguaje para filtrar los registros del proceso de trabajo.

Ejemplo: Filtrar registros del anfitrión para todos los proveedores en host.json

Use este enfoque para establecer un nivel de registro global en todos los proveedores administrados por el host:

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry",
  "logging": {
    "logLevel": {
      "default": "Warning"
    }
  }
}

Ejemplo: Filtrar registros solo para el proveedor del registrador OpenTelemetry

Utilice este enfoque para establecer como destino solo el proveedor del registrador OpenTelemetry mientras deja otros proveedores (como la consola o el registro en archivo) sin verse afectados.

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry",
  "logging": {
    "OpenTelemetry": {
      "logLevel": {
        "default": "Warning"
      }
    }
  }
}

Registro de consola

El host de Functions captura automáticamente todo lo escrito en stdout o stderr y lo reenvía a la canalización de telemetría. Si también utiliza ConsoleExporter o escribe directamente en la consola dentro de su código, pueden producirse registros duplicados en sus datos de telemetría.

Nota:

Para evitar entradas duplicadas de telemetría, no incluya ConsoleExporter ni realice escrituras en la consola dentro del código de producción.

Autenticación de Microsoft Entra

Al usar la autenticación de Microsoft Entra con OpenTelemetry, debe configurar la autenticación por separado para el proceso de host y el proceso de trabajo.

Para configurar la autenticación para el proceso de host, consulte Requerir autenticación de Microsoft Entra.

Para configurar la autenticación para el proceso de trabajo, consulte Habilitación de la autenticación de Microsoft Entra.

Soporte de atributos de recursos

La compatibilidad con atributos de recursos en Azure Monitor se encuentra actualmente en versión preliminar. Para habilitar esta función, establezca la variable de entorno OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS en true. Esta configuración ingiere atributos de recursos en la tabla de métricas personalizadas.

Telemetría de solicitudes duplicadas

El proceso de host emite automáticamente la telemetría de solicitudes. Si el proceso de trabajo también se instrumenta con bibliotecas de seguimiento de solicitudes (por ejemplo, AspNetCoreInstrumentation en .NET), se notifica dos veces la misma solicitud.

Nota:

Dado que la distribución de Azure Monitor suele incluir AspNetCoreInstrumentation en .NET e instrumentación similar en otros lenguajes, evite usar la distribución de Azure Monitor en el proceso de trabajo para evitar la telemetría duplicada.

Ámbitos de registro que no están incluidos

De manera predeterminada, el proceso de trabajo no incluye ámbitos en sus registros. Para habilitar ámbitos, configure este ajuste explícitamente en el trabajo. En el ejemplo siguiente se muestra cómo habilitar ámbitos en .NET Aislado:

builder.Logging.AddOpenTelemetry(b => b.IncludeScopes = true);

Falta telemetría de solicitud

Los desencadenadores como HTTP, Service Bus y Event Hubs dependen de la propagación del contexto para el seguimiento distribuido. Con el muestreo basado en elementos primarios como comportamiento predeterminado, la telemetría de solicitudes no se genera cuando no se muestrea la solicitud entrante o el mensaje.

OperationId duplicado

En Azure Functions, el OperationId usado para correlacionar la telemetría procede directamente del valor de la solicitud o mensaje traceparent entrantes. Si varias llamadas reutilizan el mismo traceparent valor, todos obtienen el mismo OperationId.

Configuración de OpenTelemetry con variables de entorno

Puede configurar el comportamiento de OpenTelemetry mediante sus variables de entorno estándar. Estas variables proporcionan una manera coherente de controlar el comportamiento en distintos lenguajes y entornos de ejecución. Puede ajustar las estrategias de muestreo, la configuración del exportador y los atributos de recursos. Para obtener más información sobre las variables de entorno admitidas, consulte la documentación de OpenTelemetry.

Uso de diagnósticos para solucionar problemas de supervisión

Diagnósticos de Azure Functions en Azure Portal es un recurso útil para detectar y diagnosticar posibles problemas relacionados con la supervisión.

Para acceder a los diagnósticos en la aplicación:

  1. En Azure Portal, vaya al recurso de la aplicación de funciones.

  2. En el panel izquierdo, seleccione Diagnosticar y resolver problemas y busque el flujo de trabajo Function App que falta telemetría de Application Insights o OpenTelemetry.

  3. Seleccione este flujo de trabajo, elija el método de ingesta y seleccione Siguiente.

  4. Revise las directrices y las recomendaciones proporcionadas por el solucionador de problemas.

Pasos siguientes

Obtenga más información sobre OpenTelemetry y la supervisión de Azure Functions:

  • Last updated on