Partilhar via

Usar OpenTelemetry com o Azure Functions

Este artigo mostra como configurar seu aplicativo de função 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 a partir do processo de host do Functions e do processo de trabalho específico do idioma no qual seu código de função é executado. De forma predefinida, estes dados de telemetria são enviados para o Application Insights através do respetivo SDK. No entanto, pode optar por exportar estes dados usando a semântica do 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 ativando o OpenTelemetry em seu aplicativo de função:

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

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

  • Experimenta o tutorial do OpenTelemetry, que foi desenhado para te ajudar a começar rapidamente com o OpenTelemetry e o Azure Functions. Este artigo utiliza o Azure Developer CLI (azd) para criar e implementar uma aplicação de funções que utiliza integração com OpenTelemetry para rastreamento distribuído.

  • Como este artigo é direcionado para a linguagem de desenvolvimento de sua escolha, lembre-se de escolher a linguagem correta na parte superior do artigo.

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

Habilitar OpenTelemetry no host Functions

Quando ativar a saída OpenTelemetry no ficheiro host.json da aplicação de funcionalidades, o servidor exporta a saída OpenTelemetry independentemente da pilha de linguagem utilizada pela aplicação.

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

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

Definir configurações do aplicativo

Quando ativa o OpenTelemetry no ficheiro host.json, as variáveis de ambiente da aplicação determinam os pontos finais para o envio de dados, baseando-se nas definições de aplicação suportadas pelo OpenTelemetry que estão disponíveis.

Crie configurações específicas do aplicativo em seu aplicativo de função com base no destino de saída do OpenTelemetry . Quando fornece definições de ligação tanto para o Application Insights como para um exportador do protocolo OpenTelemetry (OTLP), os dados do OpenTelemetry são enviados para ambos os endpoints.

APPLICATIONINSIGHTS_CONNECTION_STRING: a cadeia de conexão para um espaço de trabalho do Application Insights. Quando essa configuração existe, os dados do OpenTelemetry são enviados para esse espaço de trabalho. Use a mesma definição para se ligar ao Application Insights sem o OpenTelemetry ativado. Se seu aplicativo ainda não tiver essa configuração, talvez seja necessário habilitar a integração do Application Insights.

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

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

Habilitar o OpenTelemetry em seu aplicativo

Depois de configurar o host de Funções para usar OpenTelemetry, atualize o código da sua aplicação para gerar dados do OpenTelemetry. Quando ativas o OpenTelemetry tanto no anfitrião como no código da tua aplicação, obtém-se melhor correlação entre os traços e registos que o processo anfitrião das Funções e o processo worker da tua linguagem emitem.

A forma como instrumenta a sua aplicação para usar OpenTelemetry depende do seu endpoint OpenTelemetry alvo:

Exemplos neste artigo assumem que a sua aplicação usa IHostApplicationBuilder, que está disponível na versão 2.x e versão posterior do Microsoft.Azure.Functions.Worker. Para obter mais informações, consulte Versão 2.x no guia de 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 seu arquivo de projeto Program.cs, adicione esta using instrução:

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Configure o OpenTelemetry com base se o início do seu projeto utiliza IHostBuilder ou IHostApplicationBuilder. Esta última foi introduzida na versão 2.x da extensão do modelo de trabalhador isolado .NET.

    No 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 Maven ou 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 spans 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 seu ficheiro de package.json para incluir o novo src/index.js ficheiro. 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 main campo no arquivo package.json para incluir a saída desse novo src/index.ts arquivo, que pode ter esta aparência:

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

Importante

A saída OpenTelemetry para o Application Insights do operador de idiomas não é suportada atualmente para aplicativos PowerShell. Em vez disso, você pode querer usar um ponto de extremidade de exportador OTLP. Quando configura o seu host para saída de OpenTelemetry nos Application Insights, os registos gerados pelo processo de trabalho PowerShell continuam a ser encaminhados, mas o rastreamento distribuído não é atualmente suportado.

Estas instruções aplicam-se 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 seu aplicativo e execute o seguinte comando:

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

    Este comando instala o módulo necessário AzureFunctions.PowerShell.OpenTelemetry.SDK diretamente na sua aplicação. Não é possível usar o requirements.psd1 arquivo para instalar automaticamente essa dependência porque as dependências gerenciadas não são suportadas atualmente na visualização do plano Flex Consumption.

  3. Adicione este código ao seu ficheiro profile.ps1:

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

  1. Certifique-se de que estas bibliotecas estão no seu requirements.txt ficheiro, seja para deixar de comentar ou adicionar a si próprio:

    azure-monitor-opentelemetry

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

    Se já adicionou PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true nas definições da aplicação, pode ignorar este passo. Para habilitar manualmente a coleta 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. Consulte a documentação de uso do Azure monitor Distro para obter opções sobre como configurar ainda mais o SDK.

Considerações para OpenTelemetry

Ao exportar os seus dados usando OpenTelemetry, tenha estas considerações em mente.

  • O Portal do Azure suporta Recent function invocation rastreamentos apenas se a telemetria for enviada para o Azure Monitor.

  • Quando configuras o host para usar OpenTelemetry, o portal Azure não suporta streaming de logs.

  • Se definires telemetryMode para OpenTelemetry, a configuração na logging.applicationInsights secção de host.json não se aplica.

  • As extensões personalizadas incluem automaticamente todos os atributos de recursos e usam os exportadores configurados em seu aplicativo.

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

  • Use estes sinalizadores Java Virtual Machine (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 precisas de registar manualmente o middleware; o trabalhador Java descobre automaticamente OpenTelemetryInvocationMiddleware.

Solução de problemas

Ao exportar os seus dados usando OpenTelemetry, tenha em mente estas questões e soluções comuns.

Filtragem de logs

Para configurar corretamente o filtro de logs na sua aplicação de funções, é necessário compreender a diferença entre o processo anfitrião e o processo de trabalho.

O processo de host é o tempo de execução 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 tempo de execução.

O processo de trabalho é específico da linguagem, executa o código da função e produz independentemente registos e telemetria de aplicações.

Importante

Os filtros definidos em host.json se aplicam somente aos logs gerados pelo processo do host. Deve usar definições específicas da linguagem no OpenTelemetry para filtrar logs do processo de trabalho.

Exemplo: filtrar os registos do host para todos os fornecedores no host.json

Use esta 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 OpenTelemetry

Use esta abordagem para direcionar apenas o provedor de logger OpenTelemetry enquanto deixa outros provedores (como console ou log de arquivos) inalterados:

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

Registo da consola

O host do sistema Functions captura automaticamente tudo o que é escrito em stdout ou stderr e 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 duplicadas de telemetria, não adicione o ConsoleExporter nem escreva na consola em código de produção.

Autenticação do Microsoft Entra

Quando utiliza autenticação Microsoft Entra com OpenTelemetry, deve configurar a autenticação separadamente tanto para o processo anfitrião como para o processo trabalhador.

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 recursos

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

Telemetria de solicitação duplicada

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

Observação

Como a Distro do Azure Monitor normalmente inclui AspNetCoreInstrumentation no .NET e instrumentação semelhante em outros idiomas, evite usar a distro do Azure Monitor no processo de trabalho para evitar telemetria duplicada.

Escopos de registro nã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 Isolated:

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

Telemetria de solicitação ausente

Gatilhos como HTTP, Service Bus e Hubs de Eventos dependem da propagação de contexto para rastreamento distribuído. Com amostragem hierárquica como comportamento predefinido, a telemetria de requisição não é gerada quando a requisição ou mensagem de entrada não é amostrada.

ID de operação duplicado

No Azure Functions, o OperationId valor usado para correlacionar telemetria vem diretamente do traceparent valor no pedido ou mensagem recebida. Se várias chamadas reutilizarem o mesmo traceparent valor, todas recebem o mesmo OperationId.

Configurar OpenTelemetry com variáveis de ambiente

Pode configurar o comportamento do OpenTelemetry usando as suas variáveis padrão de ambiente. Estas variáveis fornecem uma forma consistente de controlar o comportamento entre diferentes linguagens e runtimes. Pode ajustar estratégias de amostragem, definições do exportador e atributos de recursos. Para obter mais informações sobre variáveis de ambiente suportadas, consulte a documentação do OpenTelemetry .

Usar diagnósticos para solucionar problemas de monitoramento

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

Para acessar o diagnóstico em seu aplicativo:

  1. No portal Azure, vai ao recurso da tua aplicação de funções.

  2. No painel esquerdo, selecione Diagnosticar e resolver problemas e procure o fluxo de trabalho Function App sem telemetria, Application Insights ou OpenTelemetry.

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

  4. Reveja as diretrizes e quaisquer recomendações fornecidas pela ferramenta de resolução de problemas.

Próximos passos

Saiba mais sobre OpenTelemetry e monitorização de Azure Functions:

  • Last updated on