搭配 Azure Functions 使用 OpenTelemetry

本文說明如何設定函數應用程式，以 OpenTelemetry 格式匯出記錄與追蹤資料。 Azure Functions 會從 Functions 主機處理序與執行函數程式碼的特定語言背景工作處理序中，產生函數執行的遙測資料。預設情況下，這些遙測資料會透過 Application Insights SDK 傳送給 Application Insights。不過，你可以選擇使用 OpenTelemetry 語意來匯出這些資料。雖然您仍可使用 OpenTelemetry 格式將資料傳送至 Application Insights，現在也可以將相同資料匯出至任何其他符合 OpenTelemetry 規範的端點。

您可以在函數應用程式中啟用 OpenTelemetry 來取得這些優點：

讓在主機與應用程式程式碼中產生的追蹤與記錄資料相互關聯。
啟用一致且以標準為基礎的可匯出遙測資料產生。
與其他可取用符合 OpenTelemetry 規範資料的提供者整合。

使用本文時請考慮以下幾點：

試試 OpenTelemetry 教學，它設計來幫助你快速開始使用 OpenTelemetry 和 Azure Functions。本文使用 Azure Developer CLI（azd）來建立並部署一個使用 OpenTelemetry 整合進行分散式追蹤的函式應用程式。
由於本文會以您選擇的開發語言為目標，請記得在本文頂端選取正確的語言。

目前 OpenTelemetry 不支援 C# 處理序內的應用程式。

OpenTelemetry 會在函數應用程式層級啟用，同時於主機設定 (host.json) 與您的程式碼專案中啟用。 Azure 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 和 OpenTelemetry 協定（OTLP）匯出器提供連線設定時，OpenTelemetry 資料會傳送到兩個端點。

應用程式深入解析
OTLP 匯出工具

APPLICATIONINSIGHTS_CONNECTION_STRING：Application Insights 工作區的連接字串。當此設定存在時，OpenTelemetry 資料會傳送至該工作區。未啟用 OpenTelemetry 的情況下，使用相同的設定來連接 Application Insights。如果您的應用程式尚未有此設定，您可能需要啟用 Application Insights 整合。

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY：設定為 true，以便 Functions 主機允許 Java 工作進程直接流式傳輸 OpenTelemetry 紀錄，以防止重複的主機層級項目。

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY：設定 true，讓 Functions 主機允許 Python 工作程序直接串流 OpenTelemetry 記錄，以防止重複的主機層級記錄。

Azure Functions 支援將 OpenTelemetry 資料匯出到任何符合 OTLP 標準的端點。你需要設定的具體環境變數取決於你選擇的可觀察性提供者（例如 Datadog、New Relic、Grafana 或其他）。

大多數醫療提供者要求：

OTEL_EXPORTER_OTLP_ENDPOINT：由你的可觀察性提供者提供的 OTLP 端點網址。

許多醫療提供者還要求：

OTEL_EXPORTER_OTLP_HEADERS：用於認證憑證的標頭，例如 API 金鑰。

PYTHON_ENABLE_OPENTELEMETRY：設定為 true ，讓 Functions 主機允許 Python 工作進程直接串流 OpenTelemetry 記錄，以防止重複的主機層級記錄。

Azure Functions 支援 OpenTelemetry SDK 設定文件中定義的任何環境變數。不過，具體的變數和要求的數值會因醫療提供者而異。請參閱您的可觀察性服務提供者的文件，以了解以下內容：

必須的端點網址與認證方法
建議組態設定
提供者專屬環境變數
還有其他設定步驟嗎

在你的函式應用程式中，將所有必要的環境變數加入應用程式設定。

除非你也想把主機的 OpenTelemetry 輸出傳送到 Application Insights，否則就移除這個 APPLICATIONINSIGHTS_CONNECTION_STRING 設定吧。

在您的應用程式中啟用 OpenTelemetry

在你設定 Functions 主機使用 OpenTelemetry 後，更新你的應用程式碼以輸出 OpenTelemetry 資料。當您在主機和應用程式碼中啟用 OpenTelemetry 時，您可以更好地關聯 Functions 主機處理程序與語言工作處理程序發出的追蹤和日誌。

你如何將應用程式儀器化以使用 OpenTelemetry，取決於你選擇的 OpenTelemetry 端點：

本文中的範例假設您的應用程式使用 IHostApplicationBuilder，這在 Microsoft.Azure.Functions.Worker 的版本 2.x 及更高版本中提供。如需詳細資訊，請參閱 C# 隔離背景工作模型指南中的 2.x 版。

執行下列命令，以在應用程式中安裝必要的組件：

應用程式深入解析
OTLP 匯出工具

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

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

在您的 Program.cs 專案檔案中，新增此 using 陳述式：
- 應用程式深入解析
- OTLP 匯出工具
```
using Azure.Monitor.OpenTelemetry.Exporter; 
```
```
using OpenTelemetry; 
```
根據你的專案啟動是否使用 IHostBuilder 或 IHostApplicationBuilder來設定 OpenTelemetry 。後者則在 .NET 隔離工作者模型擴充的 v2.x 版本中引入。
在 program.cs 中，在之後 ConfigureFunctionsWebApplication新增這行程式代碼：
```
builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();
```
在program.cs中，將此ConfigureServices調用新增至您的HostBuilder管線中：
```
.ConfigureServices(s =>
{
    s.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();
})
```
在 program.cs 中，在之後 ConfigureFunctionsWebApplication新增這行程式代碼：
```
builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseOtlpExporter();
```
在program.cs中，將此ConfigureServices調用新增至您的HostBuilder管線中：
```
.ConfigureServices(s =>
{
    s.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseOtlpExporter();
})
```
您可以從相同的應用程式匯出至兩個 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>

implementation("com.microsoft.azure.functions:azure-functions-java-opentelemetry:1.0.0")
implementation("com.azure:azure-monitor-opentelemetry-autoconfigure:1.2.0")

<dependency>
  <groupId>com.microsoft.azure.functions</groupId>
  <artifactId>azure-functions-java-opentelemetry</artifactId>
  <version>1.0.0</version>
</dependency>

implementation("com.microsoft.azure.functions:azure-functions-java-opentelemetry:1.0.0")

（可選）新增以下程式碼以建立自訂區間：

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 套件：

應用程式深入解析
OTLP 匯出工具

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

npm install @opentelemetry/api 
npm install @opentelemetry/auto-instrumentations-node 
npm install @opentelemetry/exporter-logs-otlp-http 
npm install @azure/functions-opentelemetry-instrumentation

在您的專案中建立程式碼檔案，將下列程式碼複製並貼上至此新檔案中，並將檔案另存為 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()],
});

const { AzureFunctionsInstrumentation } = require('@azure/functions-opentelemetry-instrumentation');
const { getNodeAutoInstrumentations, getResourceDetectors } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPLogExporter } = require('@opentelemetry/exporter-logs-otlp-http');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
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 OTLPTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new OTLPLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

請在 package.json 檔案中的 main 欄位中加入新檔案 src/index.js 。例如：
```
"main": "src/{index.js,functions/*.js}"
```

在您的專案中建立程式碼檔案，將下列程式碼複製並貼上至此新檔案中，並將檔案另存為 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()],
});

import { AzureFunctionsInstrumentation } from '@azure/functions-opentelemetry-instrumentation';
import { getNodeAutoInstrumentations, getResourceDetectors } from '@opentelemetry/auto-instrumentations-node';
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
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 OTLPTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new OTLPLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

更新 package.json 檔案中的 main 欄位以包含此新 src/index.ts 檔案的輸出，可能會如下所示：
```
"main": "dist/src/{index.js,functions/*.js}"
```

重要事項

目前不支援 PowerShell 應用程式從語言背景工作處理序將 OpenTelemetry 輸出至 Application Insights。您可能會想改用 OTLP 匯出工具端點。當你設定主機將 OpenTelemetry 輸出到 Application Insights 時，PowerShell 工作程序產生的日誌仍會被轉發，但目前不支援分散式追蹤。

這些指示僅適用於 OTLP 匯出工具：

新增名稱為 OTEL_FUNCTIONS_WORKER_ENABLED 且值為 True 的應用程式設定。
在應用程式根目錄中建立一個應用程式層級Modules資料夾，然後執行下列命令：
```
Save-Module -Name AzureFunctions.PowerShell.OpenTelemetry.SDK
```
這個指令會直接在你的應用程式中安裝所需的 AzureFunctions.PowerShell.OpenTelemetry.SDK 模組。您無法使用 requirements.psd1 檔案自動安裝此相依性，因為在彈性使用量方案預覽版中，目前不支援受控相依性。

將此程式碼新增至您的 profile.ps1 檔案：

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

請確定這些程式庫已包含在您的 requirements.txt 檔案中，不論是來自取消註解或自行新增：
- 應用程式深入解析
- OTLP 匯出工具
```
azure-monitor-opentelemetry
```
```
opentelemetry-api
opentelemetry-sdk
opentelemetry-exporter-otlp
opentelemetry-instrumentation-logging
```

將此程式碼新增至您的 function_app.py 主要進入點檔案：

應用程式深入解析
OTLP 匯出工具

如果您已在應用程式設定中新增 PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true ，您可以略過此步驟。若要在不自動檢測的情況下手動啟用 Application Insights 集合，請將此程式代碼新增至您的應用程式：

from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

在使用 OpenTelemetry 時，您必須手動配置追蹤、指標和記錄的匯出設定。如需詳細資訊，請參閱請參閱適用於 Python 的檢測。

以下範例展示了一個簡單的日誌匯出實作：

logging.basicConfig(level=logging.DEBUG)

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

# Initialize logging and an exporter that can send data to an OTLP endpoint by attaching OTLP handler to root logger
# SELECT * FROM Log WHERE instrumentation.provider='opentelemetry'
_logs.set_logger_provider(
    LoggerProvider(resource=Resource.create(OTEL_RESOURCE_ATTRIBUTES))
)
logging.getLogger().addHandler(
    LoggingHandler(
        logger_provider=_logs.get_logger_provider().add_log_record_processor(
            BatchLogRecordProcessor(OTLPLogExporter())
        )
    )
)

想學習如何使用 OpenTelemetry 元件來收集日誌，請參考 OpenTelemetry Logging SDK。

請檢閱 Azure Monitor Distro 使用說明檔，了解如何進一步設定 SDK。

OpenTelemetry 考量

使用 OpenTelemetry 匯出資料時，請記得這些考量。

Azure 入口網站僅在遙測資料傳送至 Azure Monitor 時才支援 Recent function invocation 追蹤。
當你設定主機使用 OpenTelemetry，Azure 入口網站不支援日誌串流。
如果你設 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"
      }
    }
  }
}

控制台日誌記錄

Azure Functions 主機會自動擷取寫入至 stdout 或 stderr 的任何內容，並將其轉送至遙測管線。如果您也使用 ConsoleExporter，或直接寫入到程式碼中的主控台，則遙測資料中可能會發生重複的記錄。

備註

請勿在生產程式碼中新增 ConsoleExporter 或寫入主控台，以免產生重複的遙測資料項目。

Microsoft Entra 驗證

當你使用 Microsoft Entra 認證搭配 OpenTelemetry，必須分別設定主機程序與工作程序的認證。

若要設定主機程式的驗證，請參閱需要 Microsoft Entra 驗證。

若要設定背景工作進程的驗證，請參閱啟用 Microsoft Entra 驗證。

資源屬性支援

Azure 監視器中的資源屬性支援目前處於預覽狀態。若要啟用此功能，請將 OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS 環境變數設定為 true。此設定會將資源屬性擷取至自訂計量表。

重複的要求遙測資料

主機進程會自動傳送要求遙測訊息。如果工作處理程序也配置了請求追蹤庫（例如 .NET 中的 AspNetCoreInstrumentation），則會兩次報告相同的請求。

備註

由於 Azure 監視器發行版本通常包含 .NET 中的 AspNetCoreInstrumentation 和其他語言中的類似檢測，為免產生重複的遙測資料，請避免在背景工作處理序中使用 Azure 監視器發行版本。

未包含記錄範圍

根據預設，背景工作處理序不會在其記錄中包含範圍。若要啟用範圍，您必須在 worker 中明確設定該設定。下列範例示範如何在 .NET Isolated 中啟用作用域：

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

遺漏要求遙測資料

HTTP、服務匯流排和事件中樞等觸發程序會依靠內容傳播來進行分散式追蹤。在以父系為基礎的取樣作為預設行為的情況下，當傳入的要求或訊息未被取樣時，便不會產生要求遙測資料。

重複的 OperationId（操作識別碼）

在 Azure 函式中，用於關聯遙測的 OperationId 直接來自輸入請求或訊息中的 traceparent 值。如果多次通話重複使用相同的 traceparent 值，它們都會得到相同的 OperationId。

用環境變數配置 OpenTelemetry

你可以透過使用其標準環境變數來設定 OpenTelemetry 的行為。這些變數提供了跨語言與執行環境的一致控制行為方式。你可以調整取樣策略、匯出器設定和資源屬性。如需支援環境變數的詳細資訊，請參閱 OpenTelemetry 文件。

使用診斷程式來疑難排解監視問題

Azure 入口網站中的 Azure Functions 診斷是用來偵測和診斷潛在監視相關問題的實用資源。

若要在應用程式中存取診斷功能：

在 Azure 入口網站中，移至您的函數應用程式。
在左窗格中，選取 [診斷並解決問題]，然後搜尋 [Function App 缺少遙測 Application Insights 或 OpenTelemetry] 工作流程。
選取此工作流程，選擇您的擷取方法，然後選取 [ 下一步]。
檢閱疑難解答員所提供的指導方針和任何建議。

後續步驟

了解更多關於 OpenTelemetry 與監控 Azure 函式的資訊：

使用 OpenTelemetry 分散式追蹤監視 Azure Functions
監視 Azure Functions (部分內容可能是機器或 AI 翻譯)

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19