다음을 통해 공유

Azure Functions와 함께 OpenTelemetry 사용

이 문서에서는 로그 및 추적 데이터를 OpenTelemetry 형식으로 내보내도록 함수 앱을 구성하는 방법을 보여 줍니다. Azure Functions는 Functions 호스트 프로세스와 Functions 코드가 실행되는 언어별 작업자 프로세스 모두에서 Functions 실행에 대한 원격 분석 데이터를 생성합니다. 기본적으로 이 원격 분석 데이터는 Application Insights SDK를 사용하여 Application Insights로 전송됩니다. 그러나 OpenTelemetry 의미 체계를 사용하여 이 데이터를 내보내도록 선택할 수 있습니다. 여전히 OpenTelemetry 형식을 사용하여 데이터를 Application Insights로 보낼 수 있지만 이제 동일한 데이터를 다른 OpenTelemetry 호환 엔드포인트로 내보낼 수도 있습니다.

함수 앱에서 OpenTelemetry를 사용하도록 설정하면 다음과 같은 이점을 가져올 수 있습니다.

  • 호스트 및 애플리케이션 코드에서 생성되는 추적 및 로그의 데이터 상관 관계를 지정합니다.
  • 일관된 표준 기반의 내보내기 가능한 원격 분석 데이터를 생성할 수 있습니다.
  • OpenTelemetry 규격 데이터를 사용할 수 있는 다른 공급자와 통합됩니다.

이 문서를 사용할 때는 다음 사항을 염두에 두어야 합니다.

  • OpenTelemetry 및 Azure Functions를 빠르게 시작할 수 있도록 설계된 OpenTelemetry 자습서를 사용해 보세요. 이 문서에서는 Azure 개발자 CLI(azd)를 사용하여 분산 추적에 OpenTelemetry 통합을 사용하는 함수 앱을 만들고 배포합니다.

  • 이 문서는 사용자가 선택한 개발 언어를 대상으로 하므로 문서 상단에서 올바른 언어를 선택해야 합니다.

  • OpenTelemetry는 호스트 구성(host.json)과 코드 프로젝트 모두에서 함수 앱 수준에서 사용하도록 설정됩니다. 또한 Functions는 언어별 작업자 프로세스에서 실행되는 Functions 코드에서 OpenTelemetry 데이터를 내보내기 위한 클라이언트 최적화 환경을 제공합니다.

Functions 호스트에서 OpenTelemetry 사용

함수 앱의 host.json 파일에서 OpenTelemetry 출력을 사용하도록 설정하면 호스트는 앱에서 사용하는 언어 스택에 관계없이 OpenTelemetry 출력을 내보냅니다.

Functions 호스트에서 OpenTelemetry 출력을 사용하도록 설정하려면 코드 프로젝트에서 host.json 파일을 업데이트하여 루트 컬렉션에 "telemetryMode": "OpenTelemetry" 요소를 추가합니다. OpenTelemetry가 사용하도록 설정되면 host.json 파일은 다음과 같을 수 있습니다.

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

애플리케이션 설정 구성

파일에서 host.json OpenTelemetry를 사용하도록 설정하면 앱의 환경 변수는 사용 가능한 OpenTelemetry 지원 애플리케이션 설정을 기반으로 데이터를 보내기 위한 엔드포인트를 결정합니다.

OpenTelemetry 출력 대상을 기반으로 함수 앱에서 특정 애플리케이션 설정을 만듭니다. Application Insights와 OTLP(OpenTelemetry 프로토콜) 내보내기 모두에 대한 연결 설정을 제공하면 OpenTelemetry 데이터가 두 엔드포인트로 전송됩니다.

APPLICATIONINSIGHTS_CONNECTION_STRING: Application Insights 작업 영역에 대한 연결 문자열입니다. 이 설정이 있으면 OpenTelemetry 데이터가 해당 작업 영역으로 전송됩니다. OpenTelemetry를 사용하지 않고 Application Insights에 연결하려면 동일한 설정을 사용합니다. 앱에 아직 이 설정이 없으면 Application Insights 통합을 사용하도록 설정해야 할 수도 있습니다.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: Functions 호스트에서 true Java 작업자 프로세스가 OpenTelemetry 로그를 직접 스트리밍할 수 있도록 설정하여 중복된 호스트 수준 항목을 방지합니다.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: Functions 호스트에서 true Python 작업자 프로세스가 OpenTelemetry 로그를 직접 스트리밍할 수 있도록 설정하여 중복된 호스트 수준 항목을 방지합니다.

앱에서 OpenTelemetry 사용

OpenTelemetry를 사용하도록 Functions 호스트를 구성한 후 애플리케이션 코드를 업데이트하여 OpenTelemetry 데이터를 출력합니다. 호스트 및 애플리케이션 코드 모두에서 OpenTelemetry를 사용하도록 설정하면 Functions가 호스트하는 추적 및 로그와 언어 작업자 프로세스가 내보내는 상관 관계가 향상됩니다.

OpenTelemetry를 사용하도록 애플리케이션을 계측하는 방법은 대상 OpenTelemetry 엔드포인트에 따라 달라집니다.

이 문서의 예제에서는 앱이 IHostApplicationBuilder 버전 2.x 이상 버전에서 사용할 수 있는 앱을 사용한다고 가정합니다. 자세한 내용은 C# 격리 작업자 모델 가이드의 버전 2.x 를 참조하세요.

  1. 앱에 필요한 어셈블리를 설치하려면 다음 명령을 실행합니다.

    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 문을 추가합니다.

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. 프로젝트 시작 시 IHostBuilder 또는 IHostApplicationBuilder 사용 여부에 따라 OpenTelemetry를 구성합니다. 후자는 .NET 격리 작업자 모델 확장의 v2.x에 도입되었습니다.

    program.cs 다음 코드 줄을 추가합니다.ConfigureFunctionsWebApplication

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

    동일한 앱에서 두 OpenTelemetry 엔드포인트로 내보낼 수 있습니다.

  1. 앱에 필요한 라이브러리를 추가합니다. 라이브러리를 추가하는 방법은 Maven 또는 Kotlin을 사용하여 배포할지 여부와 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. (선택 사항) 사용자 지정 범위를 만들려면 다음 코드를 추가합니다.

    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 패키지를 설치합니다.

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

  1. 프로젝트에서 코드 파일을 만들고 다음 코드를 이 새 파일에 복사하여 붙여넣은 후 파일을 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. main 새 src/index.js 파일을 포함하도록 package.json 파일의 필드를 업데이트합니다. 다음은 그 예입니다.

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

  1. 프로젝트에서 코드 파일을 만들고 다음 코드를 이 새 파일에 복사하여 붙여넣은 후 파일을 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. 이 새 main 파일의 출력을 포함하도록 package.json 파일의 src/index.ts 필드를 업데이트합니다. 이는 다음과 같습니다.

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

중요합니다

언어 작업자에서 Application Insights로의 OpenTelemetry 출력은 현재 PowerShell 앱에서 지원되지 않습니다. 대신 OTLP 내보내기 도구 엔드포인트를 사용할 수도 있습니다. Application Insights에 대한 OpenTelemetry 출력에 대한 호스트를 구성하는 경우 PowerShell 작업자 프로세스에서 생성된 로그는 여전히 전달되지만 분산 추적은 현재 지원되지 않습니다.

이 지침은 OTLP 내보내기 도구에만 적용됩니다.

  1. 값이 OTEL_FUNCTIONS_WORKER_ENABLED인 True라는 애플리케이션 설정을 추가합니다.

  2. 앱 루트에 앱 수준 Modules 폴더를 만들고 다음 명령을 실행합니다.

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

    이 명령은 필요한 AzureFunctions.PowerShell.OpenTelemetry.SDK 모듈을 앱에 직접 설치합니다. requirements.psd1은 현재 Flex 사용량 플랜 미리 보기에서 지원되지 않으므로 파일을 사용하여 이 종속성을 자동으로 설치할 수 없습니다.

  3. profile.ps1 파일에 다음 코드를 추가합니다.

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

  1. 주석 처리를 제거하거나 직접 추가하여 requirements.txt 파일에 이러한 라이브러리가 있는지 확인합니다.

    azure-monitor-opentelemetry

  2. function_app.py 기본 진입점 파일에 다음 코드를 추가합니다.

    애플리케이션 설정에 이미 추가 PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true 한 경우 이 단계를 건너뛸 수 있습니다. 자동 계측 없이 Application Insights 컬렉션을 수동으로 사용하도록 설정하려면 다음 코드를 앱에 추가합니다.

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. SDK를 추가로 구성하는 방법에 대한 옵션은 Azure Monitor 배포판 사용 설명서를 검토하세요.

OpenTelemetry에 대한 고려 사항

OpenTelemetry를 사용하여 데이터를 내보낼 때는 이러한 고려 사항을 염두에 두어야 합니다.

  • Azure Portal은 원격 분석이 Azure Monitor로 전송되는 경우에만 Recent function invocation 추적을 지원합니다.

  • OpenTelemetry를 사용하도록 호스트를 구성하는 경우 Azure Portal은 로그 스트리밍을 지원하지 않습니다.

  • telemetryMode을 OpenTelemetry로 설정하면, host.json의 logging.applicationInsights 섹션에 있는 구성은 적용되지 않습니다.

  • 사용자 지정 범위는 자동으로 모든 리소스 특성을 포함하고 앱에 구성된 내보내기를 사용합니다.

  • 로컬 개발 중에를 포함하여 앱이 Azure 외부에서 실행되는 경우 리소스 탐지기는 기본적으로 특성을 service.name 설정합니다java-function-app.

  • 다음 JVM(Java Virtual Machine) 플래그를 사용하여 단위 테스트 중에 로컬로 실행할 때 원격 분석을 무음으로 처리합니다.

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • 미들웨어를 수동으로 등록할 필요가 없습니다. Java 작업자 자동 검색.OpenTelemetryInvocationMiddleware

Troubleshooting

OpenTelemetry를 사용하여 데이터를 내보낼 때는 이러한 일반적인 문제 및 솔루션을 염두에 두어야 합니다.

로그 필터링

함수 앱에서 로그 필터링을 올바르게 구성하려면 호스트 프로세스와 작업자 프로세스 간의 차이를 이해해야 합니다.

호스트 프로세스는 트리거, 크기 조정을 관리하고 초기화 로그, 요청 추적 및 런타임 상태 정보와 같은 시스템 수준 원격 분석을 내보내는 Azure Functions 런타임입니다.

작업자 프로세스는 언어별로 지정되고, 함수 코드를 실행하고, 애플리케이션 로그 및 원격 분석을 독립적으로 생성합니다.

중요합니다

host.json 정의된 필터는 호스트 프로세스에서 생성된 로그에만 적용됩니다. 작업자 프로세스에서 로그를 필터링하려면 언어별 OpenTelemetry 설정을 사용해야 합니다.

예: host.json모든 공급자에 대한 호스트 로그 필터링

이 방법을 사용하여 호스트에서 관리하는 모든 공급자에 전역 로그 수준을 설정합니다.

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

예: OpenTelemetry 로거 공급자에 대해서만 로그 필터링

다른 공급자(예: 콘솔 또는 파일 로깅)는 영향을 받지 않고 OpenTelemetry 로거 공급자만 대상으로 지정하려면 이 방법을 사용합니다.

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

콘솔 로깅

Functions 호스트는 stdout 또는 stderr에 기록된 모든 항목을 자동으로 캡처하고 원격 분석 파이프라인에 전달합니다. 또한 ConsoleExporter를 사용하거나 코드에서 콘솔에 직접 쓰는 경우 원격 분석 데이터에서 중복 로그가 발생할 수 있습니다.

비고

중복된 원격 분석 항목을 방지하려면 ConsoleExporter를 추가하거나 프로덕션 코드에서 콘솔에 쓰지 마세요.

"Microsoft Entra" 인증

OpenTelemetry에서 Microsoft Entra 인증을 사용하는 경우 호스트 프로세스와 작업자 프로세스 모두에 대해 별도로 인증을 구성해야 합니다.

호스트 프로세스에 대한 인증을 구성하려면 Microsoft Entra 인증 필요를 참조하세요.

작업자 프로세스에 대한 인증을 구성하려면 Microsoft Entra 인증 사용을 참조하세요.

리소스 특성 지원

Azure Monitor의 리소스 특성 지원은 현재 미리 보기로 제공됩니다. 이 기능을 사용하도록 설정하려면 환경 변수OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS를 true .로 설정합니다. 이 설정은 리소스 특성을 사용자 지정 메트릭 테이블에 수집합니다.

중복 요청 원격 분석

호스트 프로세스는 요청에 대한 원격 분석을 자동으로 내보냅니다. 작업자 프로세스가 요청 추적 라이브러리(예: .NET의 AspNetCoreInstrumentation)를 사용하여 계측되는 경우 동일한 요청이 두 번 보고됩니다.

비고

Azure Monitor 배포판은 일반적으로 .NET의 AspNetCoreInstrumentation 및 다른 언어의 유사한 계측을 포함하므로 작업자 프로세스에서 Azure Monitor 배포판 사용을 방지하여 중복 원격 분석을 방지합니다.

로깅 범위가 포함되지 않음

기본적으로 작업자 프로세스는 로그에 범위를 포함하지 않습니다. 범위를 사용하도록 설정하려면 작업자에서 이 설정을 명시적으로 구성해야 합니다. 다음 예제에서는 .NET 격리에서 범위를 사용하도록 설정하는 방법을 보여 줍니다.

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

누락된 요청 원격 분석

HTTP, Service Bus 및 Event Hubs와 같은 트리거는 분산 추적에 대한 컨텍스트 전파에 따라 달라집니다. 부모 기반 샘플링을 기본 동작으로 사용하는 경우 들어오는 요청 또는 메시지가 샘플링되지 않으면 요청 원격 분석이 생성되지 않습니다.

중복된 OperationId

Azure Functions에서 원격 분석의 상관 관계를 지정하는 데 사용되는 OperationId은(는) 들어오는 요청이나 메시지의 traceparent 값에서 직접 가져옵니다. 여러 호출이 동일한 traceparent 값을 다시 사용하는 경우 모두 동일합니다 OperationId.

환경 변수를 사용하여 OpenTelemetry 구성

표준 환경 변수를 사용하여 OpenTelemetry 동작을 구성할 수 있습니다. 이러한 변수는 다양한 언어 및 런타임에서 동작을 제어하는 일관된 방법을 제공합니다. 샘플링 전략, 내보내기 설정 및 리소스 특성을 조정할 수 있습니다. 지원되는 환경 변수에 대한 자세한 내용은 OpenTelemetry 설명서를 참조하세요.

진단을 사용하여 모니터링 문제 해결

Azure Portal의 Azure Functions 진단은 잠재적인 모니터링 관련 문제를 감지하고 진단하는 데 유용한 리소스입니다.

앱에서 진단에 액세스하려면 다음을 수행합니다.

  1. Azure Portal에서 함수 앱 리소스로 이동합니다.

  2. 왼쪽 창에서 진단 및 문제 해결을 선택하고 함수 앱에서 Application Insights 또는 OpenTelemetry로 전송되는 원격 분석 데이터 누락 워크플로를 검색합니다.

  3. 이 워크플로를 선택하고, 수집 방법을 선택하고, 다음을 선택합니다.

  4. 문제 해결사에서 제공하는 지침 및 권장 사항을 검토합니다.

다음 단계

OpenTelemetry 및 Azure Functions 모니터링에 대해 자세히 알아봅니다.

  • Last updated on