다음을 통해 공유

Node.js Application Insights SDK 2.X에서 Azure Monitor OpenTelemetry로 마이그레이션

  • 아티클

이 가이드에서는 Azure Monitor Application Insights Node.js SDK 2.X에서 OpenTelemetry로 업그레이드하는 두 가지 옵션을 제공합니다.

  • 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를 사용하도록 설정합니다.

    Important

    다른 항목을 가져오기 전에 useAzureMonitor를 호출해야 합니다. 다른 라이브러리를 먼저 가져오면 원격 분석이 손실될 수 있습니다. 시작에 따라 Azure Monitor OpenTelemetry Distro에 온보딩합니다.

Azure Monitor OpenTelemetry Distro 변경 내용 및 제한 사항

  • Application Insights SDK 2.X의 API는 Azure Monitor OpenTelemetry Distro에서 사용할 수 없습니다. Application Insights SDK 3.X의 주요 업그레이드 경로를 통해 이러한 API에 액세스할 수 있습니다.
  • 작업 이름을 기준으로 종속성, 로그, 예외 필터링은 아직 지원되지 않습니다.

변경 내용 및 제한 사항

두 업그레이드 경로 모두에 다음 변경 내용 및 제한 사항이 적용됩니다.

Node.js 버전 지원

ApplicationInsights 3.X SDK에서 Node.js 버전을 지원하려면 Azure SDK와 OpenTelemetry 모두에서 중복 지원이 있어야 합니다. 최신 업데이트는 OpenTelemetry 지원 런타임을 확인합니다. 이전에 ApplicationInsights SDK에서 지원되었던 Node 8과 같은 이전 버전의 사용자는 OpenTelemetry 솔루션을 계속 사용할 수 있지만 예기치 않거나 중단되는 동작이 발생할 수 있습니다. 또한 ApplicationInsights SDK는 수명이 종료된 Node.js 버전에 대한 지원을 보장하지 않는 JS용 Azure SDK에 따라 다릅니다. 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에서 지원됩니다. 그러나 이러한 메트릭에 대한 지원은 ApplicationInsights 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를 distro 구성에 전달하도록 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);