Использование OpenTelemetry с Функции Azure

• Ознакомьтесь с руководством по OpenTelemetry, который поможет вам быстро приступить к работе с OpenTelemetry и Функции Azure. В этой статье используется интерфейс командной строки разработчика Azure (azd) для создания и развертывания приложения-функции, использующего интеграцию OpenTelemetry для распределенной трассировки.

• В настоящее время OpenTelemetry не поддерживается для приложений внутрипроцессного процесса C#.

Примеры в этой статье предполагают, что приложение использует IHostApplicationBuilder, доступное в версии 2.x и более поздней версии Microsoft.Azure. Functions.Worker. Дополнительные сведения см. в руководстве по изолированной рабочей модели C# версии 2.x .

1. Выполните следующие команды, чтобы установить необходимые сборки в приложении:

   • Аналитика приложений
   • Экспортер OTLP

   Замечание

   Начиная с версии 3.0, пакет Microsoft.ApplicationInsights.WorkerService использует Azure Monitor Exporter. Этот пакет можно использовать для поддержания существующего поведения конфигурации Application Insights во время внутреннего использования конвейера Azure Monitor, включая экспортер OpenTelemetry. Пакет Microsoft.ApplicationInsights.WorkerService (версии 3.0 или более поздней версии) можно использовать вместо пакета Azure.Monitor.OpenTelemetry.Exporter, который показан в следующем примере.

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

2. Добавьте в файл проекта Program.cs следующую using инструкцию:

   • Аналитика приложений
   • Экспортер OTLP

   using Azure.Monitor.OpenTelemetry.Exporter; 
   

3. Настройте OpenTelemetry в зависимости от того, какой запуск проекта используется: IHostBuilder или IHostApplicationBuilder. Последний был представлен в версии 2.x расширения изолированной рабочей модели .NET.

   • IHostApplicationBuilder
   • IHostBuilder

   В program.cs добавьте эту строку кода после ConfigureFunctionsWebApplication:

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

   Вы можете экспортировать данные на оба конечных пункта OpenTelemetry из одного приложения.

1. Добавьте необходимые библиотеки в приложение. Способ добавления библиотек зависит от того, развертываете ли вы с помощью Maven или Kotlin и хотите также отправлять данные в Application Insights.

   • Maven
   • Kotlin

   <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. (Необязательно) Добавьте этот код для создания пользовательских диапазонов:

   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. Установите эти пакеты npm в проекте:

   • Аналитика приложений
   • Экспортер OTLP

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

2. Создайте файл кода в проекте, скопируйте и вставьте следующий код в этот новый файл и сохраните его следующим образом src/index.js:

   • Аналитика приложений
   • Экспортер OTLP

   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()],
   });
   

3. Обновите поле main в файле package.json, чтобы включить новый файл src/index.js. Рассмотрим пример.

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

2. Создайте файл кода в проекте, скопируйте и вставьте следующий код в этот новый файл и сохраните его следующим образом src/index.ts:

   • Аналитика приложений
   • Экспортер OTLP

   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()],
   });
   

3. Обновите поле main в вашем файле package.json, чтобы включить данные вывода нового файла src/index.ts, которые могут выглядеть примерно так:

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

Эти инструкции применяются только для экспортера OTLP:

1. Добавьте параметр приложения с именем OTEL_FUNCTIONS_WORKER_ENABLED со значением True.

2. Создайте папку уровня приложения Modules и выполните следующую команду:

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

   Эта команда устанавливает необходимый AzureFunctions.PowerShell.OpenTelemetry.SDK модуль непосредственно в приложении. requirements.psd1 Невозможно использовать файл для автоматической установки этой зависимости, поскольку в предварительной версии плана Flex Consumption не поддерживаются управляемые зависимости.

3. Добавьте этот код в файл profile.ps1:

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

1. Убедитесь, что эти библиотеки присутствуют в файле requirements.txt, путем снятия комментариев или добавления их вручную.

   • Аналитика приложений
   • Экспортер OTLP

   azure-monitor-opentelemetry
   

2. Добавьте этот код в function_app.py файл основной точки входа:

   • Аналитика приложений
   • Экспортер OTLP

   Если вы уже добавили PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true в параметры приложения, этот шаг можно пропустить. Чтобы вручную включить коллекцию Application Insights без автоматического инструментирования, добавьте этот код в приложение:

   from azure.monitor.opentelemetry import configure_azure_monitor 
   configure_azure_monitor() 
   

3. Ознакомьтесь с документацией по использованию Azure Monitor Distro, чтобы узнать варианты дальнейшей настройки SDK.

Для приложений Go для любого назначения OpenTelemetry используется та же рабочая настройка. Промежуточное ПО экспортирует данные телеметрии рабочего процесса, используя параметры OTLP. Конечная точка OTLP может быть конечной точкой поставщика или сборщиком OpenTelemetry, который пересылает данные телеметрии в другое место назначения, например Azure Monitor.

1. Убедитесь, что проект использует версию рабочего пакета SDK Go, включающую ПО промежуточного слоя OpenTelemetry:

   go get github.com/azure/azure-functions-golang-worker@latest
   go mod tidy
   

2. В файле main.go импортируйте промежуточное ПО OpenTelemetry и зарегистрируйте его, прежде чем регистрировать функции:

   package main
   
   import (
       "fmt"
       "log/slog"
       "net/http"
   
       "github.com/azure/azure-functions-golang-worker/middleware/otelfunc"
       "github.com/azure/azure-functions-golang-worker/sdk"
       "github.com/azure/azure-functions-golang-worker/worker"
   )
   
   func hello(w http.ResponseWriter, r *http.Request) {
       slog.InfoContext(r.Context(), "processing request", "path", r.URL.Path)
       fmt.Fprintln(w, "hello")
   }
   
   func main() {
       app := sdk.FunctionApp()
       app.Use(otelfunc.Middleware())
   
       app.HTTP("hello", hello,
           sdk.WithMethods("GET"),
           sdk.WithAuth("anonymous"),
       )
       worker.Start(app)
   }
   

Промежуточное ПО без аргументов использует стандартные параметры приложения OTEL_EXPORTER_OTLP_*, которые вы настроили ранее в этой статье. Он создает интервалы трассировки вызовов, сопоставляет записи slog, создаваемые во время вызова, с контекстом вызова и сбрасывает телеметрические данные после каждого вызова.

Чтобы создать настраиваемые дочерние диапазоны, используйте стандартные API OpenTelemetry Go с контекстом вызова. Для триггеров HTTP используйте r.Context() в качестве родительского контекста. Для других типов триггеров используйте параметр context.Context, передаваемый вашему обработчику.

• Пользовательские диапазоны автоматически включают все атрибуты ресурсов и используют экспортеры, настроенные в приложении.

• Когда приложение выполняется вне Azure, в том числе во время локальной разработки, детектор ресурсов по умолчанию задает атрибут service.name на java-function-app.

• Используйте эти флаги Java виртуальной машины (JVM), чтобы подавить телеметрию при локальном запуске во время модульных тестов.

  • -Dotel.traces.exporter=none
  • -Dotel.metrics.exporter=none
  • -Dotel.logs.exporter=none

• Вам не нужно вручную регистрировать промежуточное ПО; Java рабочие автоматического обнаружения OpenTelemetryInvocationMiddleware.

• Используйте методы с учетом контекста из стандартного log/slog пакета, например slog.InfoContext и slog.ErrorContextдля сопоставления структурированных журналов с текущим вызовом и трассировкой.

• Промежуточный слой OpenTelemetry для воркера Go подключается опционально. Приложения, которые не импортируют и не регистрируют middleware/otelfunc, не включают пакеты OpenTelemetry в скомпилированный двоичный файл.

• Чтобы временно отключить промежуточное ПО воркера Go без повторного развертывания приложения, установите для AZURE_FUNCTIONS_WORKER_OPENTELEMETRY_DISABLED значение true.

• Для расширенной настройки можно в коде настроить пользовательские провайдеры OpenTelemetry, экспортеры, атрибуты ресурсов и пропагаторы перед регистрацией промежуточного ПО.