從 Node.js Application Insights SDK 2.X 移轉至 Azure 監視器 OpenTelemetry

發行項
09/30/2024

本指南提供兩個從 Azure 監視器 Application Insights Node.js SDK 2.X 移轉至 OpenTelemetry 的選項。

全新安裝 Node.js Azure 監視器 OpenTelemetry 發行版本。
- 移除對 Application Insights 傳統 API 的相依性。
- 熟悉 OpenTelemetry API 和術語。
- 將自己定位為使用 OpenTelemetry 現在和未來提供的所有功能。
升級至 Node.js SDK 3.X。
- 延後程式碼變更，同時保留與現有自訂事件和計量的相容性。
- 存取更豐富的 OpenTelemetry 檢測程式庫。
- 維護最新錯誤和安全性修正的資格。

全新安裝
升級

取得 OpenTelemetry JavaScript 應用程式開發介面 (API) 和軟體開發工具套件 (SDK) 的必要條件知識。
- 閱讀 OpenTelemetry JavaScript 文件。
- 檢閱設定 Azure 監視器 OpenTelemetry。
- 評估新增、修改和篩選 OpenTelemetry (部分機器翻譯)。
從您的專案解除安裝 applicationinsights 相依性。
```
npm uninstall applicationinsights
```
從程式碼中移除 SDK 2.X 實作。

從您的程式碼移除所有的 Application Insights 檢測設備。刪除 Application Insights 用戶端初始化、修改或呼叫的任何區段。
使用 Azure 監視器 OpenTelemetry 發行版本啟用 Application Insights。

重要

在您匯入任何其他專案之前，必須呼叫 useAzureMonitor。如果先匯入其他程式庫，可能會遺失遙測資料。請遵循開始使用以上線至 Azure 監視器 OpenTelemetry 發行版本。

Azure 監視器 OpenTelemetry 散發版本變更和限制

Application Insights SDK 2.X 的 API 無法在 Azure 監視器 OpenTelemetry 發行版本中使用。您可以透過 Application Insights SDK 3.X 中的不中斷升級路徑來存取這些 API。
尚不支援依作業名稱篩選相依性、記錄和例外狀況。

升級 applicationinsights 套件相依性。
```
npm update applicationinsights
```
重建應用程式。
測試您的應用程式。

若要避免在 Application Insights SDK 3.X 中使用不支援的設定選項，請參閱不支援的屬性。

如果 SDK 在主要版本更動之後記錄有關不支援 API 使用量的警告，而且您需要相關的功能，請繼續使用 Application Insights SDK 2.X。

變更和限制

下列變更和限制適用於這兩個升級路徑。

Node.js 版本支援

若要讓 ApplicationInsights 3.X SDK 支援 Node.js 版本，其必須同時具有 Azure SDK 和 OpenTelemetry 的重疊支援。檢查 OpenTelemetry 支援的執行階段是否有最新的更新。先前受 ApplicationInsights SDK 支援的舊版 Node 8 使用者仍可以使用 OpenTelemetry 解決方案，但可能會發生非預期或中斷的行為。 ApplicationInsights SDK 也取決於適用於 JS 的 Azure SDK，其不保證支援已屆生命週期結束的任何 Node.js 版本。請參閱適用於 JS 的 Azure SDK 支援原則。若要讓 ApplicationInsights 3.X SDK 支援 Node.js 版本，其必須同時具有 Azure SDK 和 OpenTelemetry 的重疊支援。

設定選項

Application Insights SDK 2.X 版提供無法在 Azure 監視器 OpenTelemetry 發行版本或 Application Insights SDK 3.X 主要版本升級中使用的設定選項。若要尋找這些變更，以及我們仍支援的選項，請參閱 SDK 設定文件。

擴充計量

Application Insights SDK 2.X 支援擴充計量；不過，這些計量的支援會在 ApplicationInsights SDK 和 Azure 監視器 OpenTelemetry 發行版本的 3.X 版結束。

遙測處理器

雖然 Azure 監視器 OpenTelemetry 發行版本和 Application Insights SDK 3.X 不支援 TelemetryProcessors，但它們確實可讓您傳遞範圍並記錄記錄處理器。如需詳細資訊，請參閱 Azure 監視器 OpenTelemetry 發行版本專案。

此範例示範建立和套用遙測處理器，以附加 Application Insights SDK 2.X 中的自訂屬性。

const applicationInsights = require("applicationinsights");
applicationInsights.setup("YOUR_CONNECTION_STRING");
applicationInsights.defaultClient.addTelemetryProcessor(addCustomProperty);
applicationInsights.start();

function addCustomProperty(envelope: EnvelopeTelemetry) {
    const data = envelope.data.baseData;
    if (data?.properties) {
        data.properties.customProperty = "Custom Property Value";
    }
    return true;
}

此範例示範如何修改 Azure 監視器 OpenTelemetry 發行版本實作，以將 SpanProcessor 傳遞至發行版本的設定。

import { Context, Span} from "@opentelemetry/api";
import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
const { useAzureMonitor } = require("@azure/monitor-opentelemetry");

class SpanEnrichingProcessor implements SpanProcessor {
    forceFlush(): Promise<void> {
        return Promise.resolve();
    }
    onStart(span: Span, parentContext: Context): void {
        return;
    }
    onEnd(span: ReadableSpan): void {
        span.attributes["custom-attribute"] = "custom-value";
    }
    shutdown(): Promise<void> {
        return Promise.resolve();
    }
}

const options = {
    azureMonitorExporterOptions: {
        connectionString: "YOUR_CONNECTION_STRING"
    },
    spanProcessors: [new SpanEnrichingProcessor()],
};
useAzureMonitor(options);

共用方式為