設定 Azure 監視器 OpenTelemetry

  • 發行項

本文涵蓋 Azure 監視器 OpenTelemetry 散發套件的組態設定。

連接字串

Application Insights 中的 連接字串 會定義傳送遙測數據的目標位置，確保其達到適當的資源以進行監視和分析。

使用下列三種方式之一來設定 連接字串：

  • 在類別中program.cs，將 新增UseAzureMonitor()至應用程式啟動。

    // Create a new ASP.NET Core web application builder.    
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    options.ConnectionString = "<Your Connection String>";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.    
app.Run();

  • 設定環境變數。

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • 將下列區段新增至組 appsettings.json 態檔。

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

注意

如果您在多個位置設定 連接字串，我們會遵循下列優先順序：

  1. 代碼
  2. 環境變數
  3. 組態檔

設定雲端角色名稱和雲端角色執行個體

針對支援的語言，Azure 監視器 OpenTelemetry Distro 會自動偵測資源內容，並提供您元件的雲端角色名稱和雲端角色實例屬性的預設值。 不過，您可能想要將預設值覆寫為對您的小組有意義的專案。 雲端角色名稱值會顯示在應用程式對應上，做為節點底下的名稱。

透過資源屬性來設定雲端角色名稱和雲端角色執行個體。 雲端角色名稱會使用 service.namespace 和 service.name 屬性，但如果 service.namespace 未設定，則會回復為 service.name。 雲端角色執行個體會使用 service.instance.id 屬性值。 如需資源標準屬性的詳細資訊，請參閱 OpenTelemetry Semantic 慣例。

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Configure the OpenTelemetry tracer provider to add the resource attributes to all traces.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => 
    builder.ConfigureResource(resourceBuilder => 
        resourceBuilder.AddAttributes(resourceAttributes)));

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

啟用取樣

您可能想要啟用取樣以減少資料擷取量，以降低您的成本。 Azure 監視器提供自定義 固定速率 取樣器，以取樣比例填入事件，Application Insights 會 ItemCount轉換成 。 固定比率取樣器可確保精確的體驗和事件計數。 取樣器的設計目的是為了保留跨服務的追蹤資料，並可以與舊版的 Application Insights SDK 交互運作。 如需詳細資訊，請參閱深入了解取樣。

注意

計量和記錄不會受到取樣影響。

取樣器預期取樣速率介於 0 到 1 之間。 0.1 的速率表示會傳送大約 10% 的追蹤。

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    o.SamplingRatio = 0.1F;
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

提示

使用固定速率/百分比取樣而且您不確定在何處設定取樣率，請從 5% 開始 (也就是 0.05 的取樣率)，並根據失敗和效能刀鋒窗格中所示作業的精確度來調整比率。 較高的比率通常會導致較高的精確度。 不過，「任何的」取樣都會影響精確度，因此我們建議在 OpenTelemetry 計量上發出警示，這不會受到取樣的影響。

啟用 Microsoft Entra 識別碼 （先前稱為 Azure AD） 驗證

您可能想要啟用 Microsoft Entra 驗證，以建立更安全的 Azure 連線，以防止未經授權的遙測擷取到您的訂用帳戶。

我們支援 Azure 身分識別所提供的認證類別。

  • 建議您 DefaultAzureCredential 進行本機開發。
  • 我們建議 ManagedIdentityCredential 使用系統指派和使用者指派的受控識別。
    • 若為系統指派，請使用不含參數的預設建構函式。
    • 針對使用者指派，請將用戶端標識碼提供給建構函式。
  • 我們建議 ClientSecretCredential 使用服務主體。
    • 將租使用者標識碼、用戶端標識碼和客戶端密碼提供給建構函式。

  1. 安裝最新的 Azure.Identity 套件：

    dotnet add package Azure.Identity

  2. 提供所需的認證類別：

    // Create a new ASP.NET Core web application builder.    
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    // Set the Azure Monitor credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

離線儲存和自動重試

為了改善可靠性和復原能力，Azure 監視器 OpenTelemetry 型供應項目預設會在應用程式與 Application Insights 失去連線時寫入離線/本機記憶體。 它會將應用程式遙測儲存至磁碟，並定期嘗試再次傳送最多 48 小時。 在高負載應用程式中，遙測偶爾會因為兩個原因而卸除。 首先，當超過允許的時間，而第二個超過檔案大小上限，或 SDK 沒有機會清除檔案時。 如果需要選擇，產品會將較新的事件儲存在舊事件上。 深入瞭解

散發套件包含 AzureMonitorExporter，預設會針對離線記憶體使用下列其中一個位置（依優先順序列出）：

  • Windows
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • 非 Windows
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

若要覆寫預設目錄，您應該設定 AzureMonitorOptions.StorageDirectory。

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that cannot be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

若要停用此功能，您應該設定 AzureMonitorOptions.DisableOfflineStorage = true。

啟用 OTLP 匯出工具

您可能想要啟用 OpenTelemetry 通訊協定 （OTLP） 匯出工具與 Azure 監視器匯出工具，以將您的遙測傳送至兩個位置。

注意

OTLP 匯出工具的顯示只是為了方便起見。 我們並未正式支援 OTLP 匯出工具，或其下游的任何元件或協力廠商體驗。

  1. 在您的 專案中安裝 OpenTelemetry.Exporter.OpenTelemetryProtocol 套件。

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. 新增下列程式碼片段。 此範例假設您的 OpenTelemetry 收集器正在執行 OTLP 接收器。 如需詳細資訊，請參閱 GitHub 範例。

    // Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

OpenTelemetry 組態

使用 Azure 監視器 OpenTelemetry Distros 時，可以透過環境變數存取下列 OpenTelemetry 組態。

環境變數 描述
APPLICATIONINSIGHTS_CONNECTION_STRING 將它設定為 Application Insights 資源的 連接字串。
APPLICATIONINSIGHTS_STATSBEAT_DISABLED 將它設定為 true ，以退出退出內部計量集合。
OTEL_RESOURCE_ATTRIBUTES 要當做資源屬性使用的索引鍵/值組。 如需資源屬性的詳細資訊，請參閱 資源 SDK 規格。
OTEL_SERVICE_NAME 設定資源屬性的值 service.name 。 如果在 service.name 中 OTEL_RESOURCE_ATTRIBUTES也提供 ，則 OTEL_SERVICE_NAME 優先使用 。

常見問題集

本節提供常見問題的答案。

什麼是 OpenTelemetry？

適用於可檢視性的新開放原始碼標準。 若要深入了解，請參閱 OpenTelemetry。

為什麼 Microsoft Azure 監視器投資 OpenTelemetry？

Microsoft 是 OpenTelemetry 的最大參與者之一。

OpenTelemetry 的主要價值主張在於，其為廠商中性並提供跨語言的一致 API/SDK。

一段時間後，我們相信 OpenTelemetry 能讓 Azure 監視器客戶觀察使用我們支援語言以外的語言所撰寫的應用程式。 這也會擴充您可以透過一組多樣化的檢測程式庫所收集的資料類型。 此外，OpenTelemetry SDK 的規模比其前身 Application Insights SDK 更具效能。

最後，OpenTelemetry 也會配合 Microsoft 的策略採用開放原始碼。

OpenTelemetry 的狀態為何？

請參閱 OpenTelemetry 狀態。

什麼是「Azure 監視器 OpenTelemetry Distro」？

您可以將此視為精簡包裝函式，將全部 OpenTelemetry 元件組合在一起，以獲得 Azure 的絕佳體驗。 此包裝函式也稱為 OpenTelemetry 中的散發 套件。

為何應該使用「Azure 監視器 OpenTelemetry Distro」？

相較於原生 OpenTelemetry，從社群使用 Azure 監視器 OpenTelemetry Distro 的一些優點如下：

秉持 OpenTelemetry 的精神，我們設計出開放且可延伸的發行版本。 例如，您可以新增：

  • OpenTelemetry 通訊協定 （OTLP） 匯出工具，並同時傳送至第二個目的地
  • 發行版本未包含的其他檢測程式庫

因為散發版本提供 OpenTelemetry 散發套件，因此 Distro 支援 OpenTelemetry 所支援的任何專案。 例如，如果 OpenTelemetry 支援遙測處理器、匯出者或檢測連結庫，您可以新增更多遙測處理器、導出者或檢測連結庫。

注意

散發版本會將取樣器設定為 Application Insights 的自定義固定速率取樣器。 您可以將此變更為不同的取樣器，但這樣做可能會停用部分散發版本包含的功能。 如需支持取樣器的詳細資訊，請參閱設定 Azure 監視器 OpenTelemetry 的啟用取樣一節。

對於沒有支持的獨立 OpenTelemetry 導出工具的語言，Azure 監視器 OpenTelemetry Distro 是目前唯一支援搭配 Azure 監視器使用 OpenTelemetry 的方式。 針對具有支持的獨立 OpenTelemetry 匯出工具的語言，您可以選擇使用 Azure 監視器 OpenTelemetry Distro 或視您的遙測案例而定的適當獨立 OpenTelemetry 導出工具。 如需詳細資訊，請參閱 何時應該使用 Azure 監視器 OpenTelemetry 導出工具？。

如何測試 Azure 監視器 OpenTelemetry Distro？

請查看 .NET、Java、JavaScript (Node.js) 和 Python 的啟用文件。

我應該使用 OpenTelemetry 或 Application Insights SDK 嗎？

我們建議您使用 OpenTelemetry Distro，除非您需要只有 Application Insights SDK中的正式支援所提供的功能。

採用 OpenTelemetry 現在可防止稍後移轉。

何時應該使用 Azure 監視器 OpenTelemetry 匯出工具？

針對 ASP.NET Core、Java、Node.js 和 Python，我們建議使用 Azure 監視器 OpenTelemetry Distro。 這是開始使用的一行程式碼。

針對所有其他 .NET 案例，包括傳統 ASP.NET、控制台應用程式等，我們建議使用 .NET Azure 監視器 OpenTelemetry 導出工具： Azure.Monitor.OpenTelemetry.Exporter。

如需需要進階設定的更複雜的 Python 遙測案例，建議您使用 Python Azure 監視器 OpenTelemetry 導出工具。

Azure 監視器 OpenTelemetry Distro 功能的目前發行狀態為何？

下圖細分每個語言的 OpenTelemetry 功能支援。

功能 .NET Node.js Python Java
分散式追蹤 ✅ ✅ ✅ ✅
自訂計量 ✅ ✅ ✅ ✅
標準計量 (目前受取樣影響的正確性) ✅ ✅ ✅ ✅
固定取樣率 ✅ ✅ ✅ ✅
離線儲存和自動重試 ✅ ✅ ✅ ✅
例外狀況報告 ✅ ✅ ✅ ✅
記錄集合 ✅ ⚠️ ✅ ✅
自訂事件 ⚠️ ⚠️ ⚠️ ✅
Microsoft Entra 驗證 ✅ ✅ ✅ ✅
即時計量 ❌ ❌ ❌ ✅
偵測 VM/VMSS 和 App Service 的資源內容 ✅ ❌ ✅ ✅
偵測 AKS 和函式的資源內容 ❌ ❌ ❌ ✅
可用性測試範圍篩選 ❌ ❌ ❌ ✅
自動填入使用者識別碼、已驗證的使用者識別碼和使用者 IP ❌ ❌ ❌ ✅
手動覆寫/設定作業名稱、使用者識別碼或已驗證的使用者識別碼 ❌ ❌ ❌ ✅
調適型取樣 ❌ ❌ ❌ ✅
分析工具 ❌ ❌ ❌ ⚠️
快照偵錯工具 ❌ ❌ ❌ ❌

索引鍵

OpenTelemetry 是否可以用於網頁瀏覽器？

可以，但我們不建議使用，而且 Azure 不支援。 OpenTelemetry JavaScript 已針對 Node.js進行大量最佳化。 不過，我們建議使用Application Insights JavaScript SDK。

何時可以預期 OpenTelemetry SDK 可用於網頁瀏覽器？

OpenTelemetry Web SDK 沒有確定的可用性時間表。 我們與瀏覽器 SDK 很可能有相距數年的落差，這是 Application Insights JavaScript SDK 的可行替代方案。

我今天可以在網頁瀏覽器中測試 OpenTelemetry 嗎？

OpenTelemetry Web 沙箱是一個分支，其設計目的是讓 OpenTelemetry 在瀏覽器中運作。 尚無法將遙測傳送至 Application Insights。 SDK 不會定義一般用戶端事件。

是否支援與 AppDynamics、DataDog 和 NewRelic 等競爭對手代理程式一起執行 Application Insights？

否。 雖然我們的發行版本可讓您 同時匯出至 OTLP 端點與 Azure 監視器，但這種做法並非我們打算測試或支援的做法。

是否可以在生產環境中使用預覽功能？

不建議這樣做。 請參閱 Microsoft Azure 預覽專用的使用補充條款。

手動和自動檢測有何不同？

請參閱 OpenTelemetry 概觀。

我可以使用 OpenTelemetry 收集器嗎？

儘管 Microsoft 尚未正式支援以代理程式型方法進行應用程式監視，有些客戶使用 OpenTelemetry 收集器做為代理程式替代方案。 同時，開放原始碼社群貢獻了 OpenTelemetry 收集器 Azure 監視器匯出工具，部分客戶目前已使用該工具來將資料傳送至 Azure 監視器 Application Insights。 Microsoft 不支援這項功能。

OpenCensus 和 OpenTelemetry 之間有何差異？

OpenCensus 是 OpenTelemetry 的前身。 Microsoft 協助整合 OpenTracing 和 OpenCensus，以建立 OpenTelemetry，這是世界上的單一可檢視性標準。 目前生產環境建議而且適用於 Azure 監視器的 Python SDK 是以 OpenCensus 為基礎。 Microsoft 致力於根據 OpenTelemetry 製作 Azure 監視器。

疑難排解

無法運作？ 請參閱 ASP.NET Core 的疑難排解頁面。

支援

選取您選擇的語言索引標籤，以探索支援選項。

OpenTelemetry 意見反應

若要提供意見反應：