次の方法で共有

Node.js Application Insights SDK 2.X から Azure Monitor OpenTelemetry に移行する

  • [アーティクル]

このガイドでは、Azure Monitor Application Insights Node.js SDK 2.X から OpenTelemetry にアップグレードするための 2 つのオプションを提供します。

  • Node.js Azure Monitor OpenTelemetry Distro をクリーン インストールします。
    • Application Insights クラシック API に対する依存関係を削除します。
    • OpenTelemetry API と用語について理解します。
    • OpenTelemetry によって現在と将来提供されるすべての機能を自分で使用できるようにします。
  • Node.js SDK 3.X にアップグレードします。
    • 既存のカスタム イベントやメトリックとの互換性を維持している間は、コードの変更を延期します。
    • 豊富な OpenTelemetry インストルメンテーション ライブラリにアクセスします。
    • 最新のバグとセキュリティの修正プログラムを受け取れるようにしておきます。

  1. OpenTelemetry の JavaScript アプリケーション プログラミング インターフェイス (API) とソフトウェア開発キット (SDK) に関する前提条件となる知識を得ます。

  2. プロジェクトから applicationinsights 依存関係をアンインストールします。

    npm uninstall applicationinsights

  3. コードから SDK 2.X の実装を削除します。

    コードからすべての Application Insights インストルメンテーションを削除します。 Application Insights クライアントの初期化、変更、または呼び出しが行われているセクションをすべて削除します。

  4. Azure Monitor OpenTelemetry Distro を使用して Application Insights を有効にします。

    重要

    他をインポートする "前に"、useAzureMonitor を呼び出す必要があります。 他のライブラリが最初にインポートされると、テレメトリが失われる可能性があります。 作業の開始に関するページに従って、Azure Monitor OpenTelemetry Distro にオンボードします。

Azure Monitor OpenTelemetry Distro の変更点と制限事項

  • Application Insights SDK 2.X の API は、Azure Monitor OpenTelemetry Distro では使用できません。 これらの API には、Application Insights SDK 3.X の破壊的でないアップグレード パスを使ってアクセスできます。
  • 操作名による依存関係、ログ、例外のフィルター処理はまだサポートされていません。

変更点と制限

次の変更と制限は、両方のアップグレード パスに適用されます。

Node.js バージョンのサポート

ApplicationInsights 3.X SDK でサポートされる Node.js のバージョンでは、Azure SDK と OpenTelemetry の両方からの重複するサポートが必要です。 最新の更新については、OpenTelemetry でサポートされているランタイムに関する説明をご覧ください。 Application Insights 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 Monitor OpenTelemetry Distro や、Application Insights SDK 3.X へのメジャー バージョン アップグレードでは使用できない構成オプションがあります。 これらの変更および引き続きサポートされているオプションを確認するには、SDK 構成ドキュメントを参照してください。

拡張メトリック

拡張メトリックは、Application Insights SDK 2.X でサポートされています。ただし、これらのメトリックのサポートは、Application Insights SDK のバージョン 3.X と Azure Monitor OpenTelemetry Distro の両方で終了します。

テレメトリ プロセッサ

Azure Monitor OpenTelemetry Distro と Application Insights SDK 3.X では TelemetryProcessor はサポートされていませんが、スパンとログ レコード プロセッサを渡すことができます。 方法について詳しくは、Azure Monitor OpenTelemetry Distro プロジェクトに関するページをご覧ください。

この例では、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;
}

この例では、SpanProcessor をディストリビューションの構成に渡すように、Azure Monitor OpenTelemetry Distro の実装を変更する方法を示します。

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);