Compartilhar via

Usar o OpenTelemetry com o Azure Functions

Este artigo mostra como configurar o seu aplicativo de funções para exportar dados de log e rastreamento em um formato OpenTelemetry. O Azure Functions gera dados de telemetria em suas execuções de função do processo de host do Functions e do processo de trabalho específico do idioma no qual o código de função é executado. Por padrão, esses dados de telemetria são enviados ao Application Insights usando o SDK do Application Insights. No entanto, você pode optar por exportar esses dados usando a semântica OpenTelemetry. Embora você ainda possa usar um formato OpenTelemetry para enviar seus dados para o Application Insights, agora você também pode exportar os mesmos dados para qualquer outro ponto de extremidade compatível com OpenTelemetry.

Você pode obter esses benefícios habilitando o OpenTelemetry em seu aplicativo de funções:

  • Correlaciona dados entre rastreamentos e logs que estão sendo gerados no host e no código do aplicativo.
  • Permite uma geração consistente baseada em padrões de dados de telemetria exportáveis.
  • Integra-se a outros provedores que podem consumir dados compatíveis com OpenTelemetry.

Tenha estas considerações em mente ao usar este artigo:

  • Experimente o tutorial OpenTelemetry, que foi projetado para ajudá-lo a começar rapidamente com o OpenTelemetry e o Azure Functions. Este artigo usa a CLI do Desenvolvedor do Azure (azd) para criar e implantar um aplicativo de funções que usa a integração do OpenTelemetry para rastreamento distribuído.

  • Como este artigo é direcionado à linguagem de desenvolvimento escolhida, lembre-se de escolher o idioma correto na parte superior do artigo.

  • O OpenTelemetry está habilitado no nível do aplicativo de funções, tanto na configuração do host (host.json) quanto no projeto de código. O Functions também fornece uma experiência otimizada para o cliente para exportar dados do OpenTelemetry do seu código de função em execução em um processo de trabalho específico do idioma.

Habilitar o OpenTelemetry no host do Functions

Quando você habilita a saída do OpenTelemetry no arquivo host.json do aplicativo de funções, seu host exporta a saída do OpenTelemetry independentemente da pilha de linguagens usada pelo aplicativo.

Para habilitar a saída OpenTelemetry do host do Functions, atualize o arquivo host.json em seu projeto de código para adicionar um elemento "telemetryMode": "OpenTelemetry" à coleção raiz. Com o OpenTelemetry habilitado, o seu arquivo host.json pode ter esta aparência:

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

Definir as configurações do aplicativo

Quando você habilita OpenTelemetry no arquivo host.json, as variáveis de ambiente do aplicativo determinam os endpoints para enviar dados, conforme as configurações do aplicativo suportadas pelo OpenTelemetry que estão disponíveis.

Crie configurações de aplicativo específicas em seu aplicativo de funções com base no destino de saída do OpenTelemetry. Quando você fornece configurações de conexão para o Application Insights e um exportador de protocolo OpenTelemetry (OTLP), os dados do OpenTelemetry são enviados para ambos os pontos de extremidade.

APPLICATIONINSIGHTS_CONNECTION_STRING: a cadeia de conexão de um workspace do Application Insights. Quando esta configuração existe, os dados do OpenTelemetry são enviados para o workspace. Use a mesma configuração para se conectar ao Application Insights sem OpenTelemetry habilitado. Se o aplicativo ainda não tiver essa configuração, talvez seja necessário Habilitar a integração do Application Insights.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: defina como true que o host do Functions permita que o processo de trabalho do Java transmita logs do OpenTelemetry diretamente, o que impede entradas duplicadas no nível do host.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: defina como true que o host do Functions permita que o processo de trabalho do Python transmita logs do OpenTelemetry diretamente, o que impede entradas duplicadas no nível do host.

Habilitar o OpenTelemetry em seu aplicativo

Depois de configurar o host do Functions para usar o OpenTelemetry, atualize o código do aplicativo para gerar dados OpenTelemetry. Quando você habilita o OpenTelemetry no host e no código do aplicativo, obtém uma melhor correlação entre rastreamentos e logs emitidos pelo processo de host do Functions e pelo processo de trabalho da linguagem.

Como você configura seu aplicativo para usar o OpenTelemetry depende do endpoint OpenTelemetry de destino:

Exemplos neste artigo pressupõem que seu aplicativo usa IHostApplicationBuilder, que está disponível na versão 2.x e posterior do Microsoft.Azure.Functions.Worker. Para obter mais informações, consulte a Versão 2.x no guia do modelo de trabalho isolado em C#.

  1. Execute estes comandos para instalar os assemblies necessários em seu aplicativo:

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

  2. No arquivo de projeto Program.cs, adicione esta instrução using:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Configure o OpenTelemetry com base em se a inicialização do projeto usa IHostBuilder ou IHostApplicationBuilder. Este último foi introduzido na v2.x da extensão do modelo de trabalho isolado do .NET.

    Em program.cs, adicione esta linha de código após ConfigureFunctionsWebApplication:

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

    Você pode exportar para ambos os pontos de extremidade OpenTelemetry do mesmo aplicativo.

  1. Adicione as bibliotecas necessárias ao seu aplicativo. A maneira como você adiciona bibliotecas depende se você implanta usando o Maven ou o Kotlin e se você também deseja enviar dados para o 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) Adicione este código para criar 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 estes pacotes npm em seu projeto:

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

  1. Crie um arquivo de código em seu projeto, copie e cole o seguinte código neste novo arquivo e salve o arquivo 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. Atualize o main campo no arquivo package.json para incluir o novo src/index.js arquivo. Por exemplo:

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

  1. Crie um arquivo de código em seu projeto, copie e cole o seguinte código neste novo arquivo e salve o arquivo 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. Atualize o campo main em seu arquivo package.json para incluir a saída deste novo arquivo src/index.ts, que pode ter esta aparência:

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

Importante

A saída do OpenTelemetry para o Application Insights da função de trabalho de idioma não tem suporte atualmente para aplicativos do PowerShell. Em vez disso, você pode querer usar um ponto de extremidade do exportador OTLP. Quando você configura o host para a saída do OpenTelemetry para o Application Insights, os logs gerados pelo processo de trabalho do PowerShell ainda são encaminhados, mas não há suporte para rastreamento distribuído no momento.

Estas instruções se aplicam apenas a um exportador OTLP:

  1. Adicione uma configuração de aplicativo nomeada OTEL_FUNCTIONS_WORKER_ENABLED com o valor de True.

  2. Crie uma Modules no nível do aplicativo na raiz do aplicativo e execute o seguinte comando:

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

    Esse comando instala o módulo necessário AzureFunctions.PowerShell.OpenTelemetry.SDK diretamente em seu aplicativo. Não é possível usar o arquivo requirements.psd1 para instalar automaticamente esta dependência porque as dependências gerenciadas não têm suporte no momento na versão prévia do plano de Consumo Flex.

  3. Adicione este código ao arquivo profile.ps1:

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

  1. Verifique se essas bibliotecas estão em seu arquivo requirements.txt, seja de descompactação ou adição por conta própria:

    azure-monitor-opentelemetry

  2. Adicione este código ao arquivo de ponto de entrada principal do function_app.py:

    Se você já tiver adicionado PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true às configurações do aplicativo, ignore esta etapa. Para habilitar manualmente a coleção do Application Insights sem instrumentação automática, adicione este código ao seu aplicativo:

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Examine a documentação de uso do Distro do Azure Monitor para obter opções sobre como configurar ainda mais o SDK.

Considerações sobre o OpenTelemetry

Ao exportar seus dados usando o OpenTelemetry, tenha essas considerações em mente.

  • O portal do Azure oferece suporte a rastreamentos Recent function invocation somente caso a telemetria seja enviada para o Azure Monitor.

  • Quando você configura o host para usar o OpenTelemetry, o portal do Azure não dá suporte ao streaming de log.

  • Se você definir telemetryMode como OpenTelemetry, a logging.applicationInsights configuração na seção de host.json não se aplicará.

  • Os intervalos personalizados incluem automaticamente todos os atributos de recurso e usam os exportadores configurados em seu aplicativo.

  • Quando seu aplicativo é executado fora do Azure, inclusive durante o desenvolvimento local, o detector de recursos define o atributo service.name como java-function-app por padrão.

  • Use esses sinalizadores de Máquina Virtual Java (JVM) para silenciar a telemetria ao executar localmente durante testes de unidade:

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • Não é necessário registrar o middleware manualmente; o trabalhador Java descobre automaticamente OpenTelemetryInvocationMiddleware.

Resolução de problemas

Ao exportar seus dados usando o OpenTelemetry, tenha em mente esses problemas e soluções comuns.

Filtragem de log

Para configurar corretamente a filtragem de logs em seu aplicativo de funções, você precisa entender a diferença entre o processo anfitrião e o processo de trabalho.

O processo de host é o runtime do Azure Functions que gerencia gatilhos, dimensionamento e emite telemetria no nível do sistema, como logs de inicialização, rastreamentos de solicitação e informações de integridade do runtime.

O processo de trabalho é específico da linguagem, executa seu código de função e produz logs de aplicativo e telemetria de forma independente.

Importante

Os filtros definidos em host.json se aplicam somente aos logs gerados pelo processo de host. Você deve usar as configurações do OpenTelemetry específicas da linguagem para filtrar logs do processo de trabalho.

Exemplo: Filtrar logs do host para todos os provedores no host.json

Use essa abordagem para definir um nível de log global em todos os provedores gerenciados pelo host:

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

Exemplo: filtrar logs somente para o provedor de logger do OpenTelemetry

Use essa abordagem para direcionar apenas o provedor do logger do OpenTelemetry, deixando outros provedores (como console ou registro em arquivos) não afetados:

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

Registro em log do console

O host do Functions captura automaticamente qualquer coisa gravada em stdout ou stderr e a encaminha para o pipeline de telemetria. Se você também usar um ConsoleExporter ou gravar diretamente no console em seu código, logs duplicados poderão ocorrer em seus dados de telemetria.

Observação

Para evitar entradas de telemetria duplicadas, não adicione ConsoleExporter ou escreva no console no código de produção.

autenticação do Microsoft Entra

Ao usar a autenticação do Microsoft Entra com o OpenTelemetry, você deve configurar a autenticação separadamente para o processo de host e o processo de trabalho.

Para configurar a autenticação para o processo de host, consulte Exigir autenticação do Microsoft Entra.

Para configurar a autenticação para o processo de trabalho, consulte Habilitar a autenticação do Microsoft Entra.

Suporte a atributos de recurso

O suporte a atributos de recurso no Azure Monitor está atualmente em versão prévia. Para habilitar esse recurso, defina a variável de OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS ambiente como true. Essa configuração ingere atributos de recurso na tabela de métricas personalizadas.

Telemetria de solicitação duplicada

O processo anfitrião emite automaticamente a telemetria de solicitação. Se o processo de trabalho também for instrumentado com bibliotecas de acompanhamento de solicitações (por exemplo, AspNetCoreInstrumentation no .NET), a mesma solicitação será relatada duas vezes.

Observação

Como a Distribuição do Azure Monitor normalmente inclui AspNetCoreInstrumentation no .NET e instrumentação semelhante em outras linguagens, evite usar a distribuição do Azure Monitor no processo de trabalho para evitar a telemetria duplicada.

Escopos de registro não estão incluídos

Por padrão, o processo de trabalho não inclui escopos em seus logs. Para habilitar escopos, você deve definir essa configuração explicitamente no trabalhador. O exemplo a seguir mostra como habilitar escopos no .NET Isolado:

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

Telemetria de solicitação ausente

Gatilhos como HTTP, Barramento de Serviço e Hubs de Eventos dependem da propagação de contexto para rastreamento distribuído. Com a amostragem baseada no pai como o comportamento padrão, a telemetria de solicitação não é gerada quando a solicitação ou mensagem de entrada não é amostrada.

OperationId duplicado

No Azure Functions, o OperationId usado para correlacionar a telemetria vem diretamente do traceparent valor na solicitação ou mensagem de entrada. Se várias chamadas reutilizarem o mesmo traceparent valor, todas elas obterão o mesmo OperationId.

Configurar o OpenTelemetry com variáveis de ambiente

Você pode configurar o comportamento opentelemetry usando suas variáveis de ambiente padrão. Essas variáveis fornecem uma maneira consistente de controlar o comportamento em diferentes idiomas e runtimes. Você pode ajustar estratégias de amostragem, configurações do exportador e atributos de recurso. Para obter mais informações sobre variáveis de ambiente com suporte, consulte a documentação do OpenTelemetry.

Usar o diagnóstico para solucionar problemas de monitoramento

O diagnóstico do Azure Functions no portal do Azure é um recurso útil para detectar e diagnosticar possíveis problemas relacionados ao monitoramento.

Para acessar o diagnóstico em seu aplicativo:

  1. No portal do Azure, acesse o recurso do aplicativo de funções.

  2. No painel esquerdo, selecione Diagnosticar e resolver problemas e pesquisar o fluxo de trabalho Application Insights de telemetria ausente ou OpenTelemetry.

  3. Selecione esse fluxo de trabalho, escolha o método de ingestão e selecione Avançar.

  4. Examine as diretrizes e as recomendações fornecidas pela solução de problemas.

Próximas etapas

Saiba mais sobre o OpenTelemetry e o monitoramento do Azure Functions:

  • Last updated on