この記事では、OpenTelemetry 形式でログおよびトレース データをエクスポートするように関数アプリを構成する方法について説明します。 Azure Functions は、Functions ホスト プロセスと、関数コードを実行する言語固有のワーカー プロセスの両方から、関数の実行に関するテレメトリ データを生成します。 既定では、このテレメトリ データは Application Insights SDK を使用して Application Insights に送信されます。 ただし、OpenTelemetry セマンティクスを使用してこのデータをエクスポートすることもできます。 OpenTelemetry 形式を使用して Application Insights にデータを送信することはできますが、同じデータを他の OpenTelemetry 準拠のエンドポイントにエクスポートすることもできます。
関数アプリで OpenTelemetry を有効にすると、次の利点が得られます。
- ホストとアプリケーション コードの両方で生成されるトレースとログ間でデータを関連付けます。
- エクスポート可能なテレメトリ データの一貫性のある標準ベースの生成を可能にします。
- OpenTelemetry 準拠のデータを使用できる他のプロバイダーとの統合。
この記事を使用する場合は、次の考慮事項に注意してください。
OpenTelemetry と Azure Functions をすぐに使い始めるのに役立つ OpenTelemetry チュートリアルをお試しください。 この記事では、Azure Developer CLI (
azd) を使用して、分散トレースに OpenTelemetry 統合を使用する関数アプリを作成してデプロイします。この記事は選択された開発言語を対象としているため、記事の上部で適切な言語を必ず選択してください。
- OpenTelemetry は現在、 C# インプロセス アプリではサポートされていません。
- OpenTelemetry は、ホスト構成 (
host.json) とコード プロジェクトの両方で、関数アプリ レベルで有効になります。 関数は、言語固有のワーカー プロセスで実行されている関数コードから 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 と OpenTelemetry プロトコル (OTLP) エクスポーターの両方に接続設定を指定すると、OpenTelemetry データが両方のエンドポイントに送信されます。
APPLICATIONINSIGHTS_CONNECTION_STRING: Application Insights ワークスペースの接続文字列。 この設定が存在すると、OpenTelemetry データがそのワークスペースに送信されます。 OpenTelemetry を有効にせずに Application Insights に接続するには、同じ設定を使用します。 アプリにこの設定がまだない場合は、Application Insights の統合を有効にする必要がある場合があります。
JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: Functions ホストが Java ワーカー プロセスで OpenTelemetry ログを直接ストリーミングできるように、 true に設定すると、ホスト レベルのエントリが重複しないようにします。
PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY: Functions ホストが OpenTelemetry ログを直接ストリーミングできるように、Functions ホストが true に設定すると、ホスト レベルのエントリの重複を防ぐことができます。
アプリで OpenTelemetry を有効にする
OpenTelemetry を使用するように Functions ホストを構成したら、OpenTelemetry データを出力するようにアプリケーション コードを更新します。 ホストとアプリケーション コードの両方で OpenTelemetry を有効にすると、Functions ホスト プロセスと言語ワーカー プロセスによって出力されるトレースとログの間の相関関係が向上します。
OpenTelemetry を使用するようにアプリケーションをインストルメント化する方法は、ターゲットの OpenTelemetry エンドポイントによって異なります。
この記事の例では、アプリでバージョン 2.x 以降のIHostApplicationBuilder で使用できるを使用していることを前提としています。 詳細については、C# 分離ワーカー モデル ガイドの バージョン 2.x を参照してください。
次のコマンドを実行して、必要なアセンブリをアプリにインストールします。
dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry dotnet add package OpenTelemetry.Extensions.Hosting dotnet add package Azure.Monitor.OpenTelemetry.ExporterProgram.cs プロジェクト ファイルに、次の
usingステートメントを追加します。using Azure.Monitor.OpenTelemetry.Exporter;プロジェクトのスタートアップで
IHostBuilderとIHostApplicationBuilderのどちらを使用するかに基づいて OpenTelemetry を構成します。 後者は、.NET 分離ワーカー モデル拡張機能の v2.x で導入されました。program.csで、次のコード行を
ConfigureFunctionsWebApplication後に追加します。builder.Services.AddOpenTelemetry() .UseFunctionsWorkerDefaults() .UseAzureMonitorExporter();同じアプリから両方の OpenTelemetry エンドポイントにエクスポートできます。
必要なライブラリをアプリに追加します。 ライブラリを追加する方法は、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>(省略可能)カスタム スパンを作成するには、次のコードを追加します。
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(); }
プロジェクト ディレクトリに次の npm パッケージをインストールします。
npm install @opentelemetry/api npm install @opentelemetry/auto-instrumentations-node npm install @azure/monitor-opentelemetry-exporter npm install @azure/functions-opentelemetry-instrumentation
プロジェクトにコード ファイルを作成し、この新しいファイルに次のコードをコピーして貼り付け、ファイルを
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()], });package.json ファイルの
mainフィールドを更新して、新しいsrc/index.jsファイルを含めます。 例えば次が挙げられます。"main": "src/{index.js,functions/*.js}"
プロジェクトにコード ファイルを作成し、この新しいファイルに次のコードをコピーして貼り付け、ファイルを
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()], });package.json ファイルの
mainフィールドを更新して、この新しいsrc/index.tsファイルの出力を含めます。これは、次のようになります。"main": "dist/src/{index.js,functions/*.js}"
重要
言語ワーカーからの Application Insights への OpenTelemetry 出力は、PowerShell アプリでは現在サポートされていません。 代わりに、OTLP エクスポーター エンドポイントを使用することもできます。 Application Insights への OpenTelemetry 出力用にホストを構成する場合、PowerShell ワーカー プロセスによって生成されたログは転送されますが、現時点では分散トレースはサポートされていません。
これらの手順は、OTLP エクスポーターにのみ適用されます。
値が
OTEL_FUNCTIONS_WORKER_ENABLEDのTrueという名前のアプリケーション設定を追加します。アプリのルートに アプリレベルの
Modulesフォルダーを作成し、次のコマンドを実行します。Save-Module -Name AzureFunctions.PowerShell.OpenTelemetry.SDKこのコマンドは、必要な
AzureFunctions.PowerShell.OpenTelemetry.SDKモジュールをアプリに直接インストールします。requirements.psd1ファイルを使用してこの依存関係を自動的にインストールすることはできません。マネージド依存関係 は、Flex 従量課金プラン プレビューでは現在サポートされていないためです。次のコードを profile.ps1 ファイルに追加します。
Import-Module AzureFunctions.PowerShell.OpenTelemetry.SDK -Force -ErrorAction Stop Initialize-FunctionsOpenTelemetry
コメントを解除するか、自分を追加するかに関係なく、これらのライブラリが
requirements.txtファイル内にあることを確認します。azure-monitor-opentelemetryfunction_app.pyメイン エントリ ポイント ファイルに次のコードを追加します。アプリケーション設定に
PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=trueを既に追加している場合は、この手順をスキップできます。 自動インストルメンテーションなしで Application Insights コレクションを手動で有効にするには、次のコードをアプリに追加します。from azure.monitor.opentelemetry import configure_azure_monitor configure_azure_monitor()SDK をさらに構成する方法のオプションについては、 Azure Monitor Distro の使用状況 に関するドキュメントを参照してください。
OpenTelemetry に関する考慮事項
OpenTelemetry を使用してデータをエクスポートする場合は、これらの考慮事項に留意してください。
Azure portal では、テレメトリが Azure Monitor に送信された場合にのみ、
Recent function invocationトレースがサポートされます。OpenTelemetry を使用するようにホストを構成すると、Azure portal ではログ ストリーミングがサポートされません。
telemetryModeをOpenTelemetryに設定した場合、host.json のlogging.applicationInsightsセクションの構成は適用されません。
カスタム スパンには、すべてのリソース属性が自動的に含まれており、アプリで構成されたエクスポーターが使用されます。
ローカル開発中を含め、アプリが Azure の外部で実行されている場合、リソース検出機能によって、
service.name属性が既定でjava-function-appに設定されます。単体テスト中にローカルで実行するときにテレメトリを無音にするには、次の Java 仮想マシン (JVM) フラグを使用します。
-Dotel.traces.exporter=none-Dotel.metrics.exporter=none-Dotel.logs.exporter=none
- ミドルウェアを手動で登録する必要はありません。Java ワーカー自動検出
OpenTelemetryInvocationMiddleware。
トラブルシューティング
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 など) でもインストルメント化されている場合、同じ要求が 2 回報告されます。
注
通常、Azure Monitor Distro には .NET の AspNetCoreInstrumentation と他の言語での同様のインストルメンテーションが含まれるため、ワーカー プロセスで Azure Monitor ディストリビューションを使用してテレメトリの重複を防ぐのは避けてください。
ログスコープが含まれていません
既定では、ワーカー プロセスのログにはスコープは含まれません。 スコープを有効にするには、worker でこの設定を明示的に構成する必要があります。 次の例は、.NET Isolated でスコープを有効にする方法を示しています。
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 診断は、潜在的な監視関連の問題を検出して診断するのに役立つリソースです。
アプリで診断にアクセスするには:
Azure portal で、関数アプリ リソースに移動します。
左側のウィンドウで、[問題の診断と解決] を選択し、機能アプリのテレメトリが不足している場合の Application Insights または OpenTelemetry ワークフローを検索します。
このワークフローを選択し、インジェスト方法を選択して、[ 次へ] を選択します。
トラブルシューティング ツールによって提供されるガイドラインと推奨事項を確認します。
次のステップ
OpenTelemetry と Azure Functions の監視の詳細については、以下をご覧ください。