JavaScript용 Azure Monitor OpenTelemetry

npm 버전

시작

패키지 설치

npm install @azure/monitor-opentelemetry

현재 지원되는 환경

• LTS 버전의 Node.js

• OpenTelemetry 지원 런타임

경고: 이 SDK는 Node.js 환경에서만 작동합니다. 웹 및 브라우저 시나리오에 Application Insights JavaScript SDK 사용합니다.

자세한 내용은 지원 정책 참조하세요.

필수 구성 요소

• Azure 구독
• Application Insights 작업 영역

Azure Monitor OpenTelemetry 클라이언트 사용

중요: 다른 항목을 가져올 전에 호출해야 합니다. 다른 라이브러리를 먼저 가져오는 경우 원격 분석 손실이 발생할 수 있습니다.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString:
      process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
  },
}
useAzureMonitor(options);

• 환경 변수 APPLICATIONINSIGHTS_CONNECTION_STRING 사용하여 연결 문자열을 설정할 수 있습니다.

구성

import { AzureMonitorOpenTelemetryOptions, useAzureMonitor } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";

const resource = new Resource({ "testAttribute": "testValue" });
const options: AzureMonitorOpenTelemetryOptions = {
    azureMonitorExporterOptions: {
        // Offline storage
        storageDirectory: "c://azureMonitor",
        // Automatic retries
        disableOfflineStorage: false,
        // Application Insights Connection String
        connectionString:
              process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
    },
    samplingRatio: 1,
    instrumentationOptions: {
        // Instrumentations generating traces
        azureSdk: { enabled: true },
        http: { enabled: true },
        mongoDb: { enabled: true },
        mySql: { enabled: true },
        postgreSql: { enabled: true },
        redis: { enabled: true },
        redis4: { enabled: true },
        // Instrumentations generating logs
        bunyan: { enabled: true },
        winston: { enabled: true },
    },
    enableLiveMetrics: true,
    enableStandardMetrics: true,
    browserSdkLoaderOptions: {
        enabled: false,
        connectionString: "",
    },
    resource: resource,
    logRecordProcessors: [],
    spanProcessors: []
};

useAzureMonitor(options);

@azure/monitor-opentelemetry 패키지 설치 폴더의 루트 폴더 아래에 있는 구성 파일 applicationinsights.json 사용하여 옵션을 설정할 수 있습니다. 예: node_modules/@azure/monitor-opentelemetry. 이러한 구성 값은 모든 AzureMonitorOpenTelemetryClient 인스턴스에 적용됩니다.

{
    "samplingRatio": 0.8,
    "enableStandardMetrics": true,
    "enableLiveMetrics": true,
    "instrumentationOptions":{
        "azureSdk": {
            "enabled": false
        }
    },
    ...
}

사용자 지정 JSON 파일은 APPLICATIONINSIGHTS_CONFIGURATION_FILE 환경 변수를 사용하여 제공할 수 있습니다.

process.env.APPLICATIONINSIGHTS_CONFIGURATION_FILE = "C:/applicationinsights/config/customConfig.json"

// Application Insights SDK setup....

계측 라이브러리

다음 OpenTelemetry 계측 라이브러리는 Azure Monitor OpenTelemetry의 일부로 포함됩니다.

경고: 계측 라이브러리는 실험적 OpenTelemetry 사양을 기반으로 합니다. Microsoft의 미리 보기 지원 약정은 다음 라이브러리가 Azure Monitor Application Insights에 데이터를 내보내도록 하는 것이지만, 호환성이 손상되는 변경 또는 실험적 매핑으로 일부 데이터 요소가 차단될 수 있습니다.

분산 추적

• HTTP/HTTPS
• MongoDB
• mySQL
• Postgres
• Redis
• Redis-4
• Azure SDK

운율학

• HTTP/HTTPS

로그

• 부얀

• 윈스턴

다른 OpenTelemetry 계측은 여기에서 사용할 수 있으며 AzureMonitorOpenTelemetryClient에서 TracerProvider를 사용하여 추가할 수 있습니다.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { metrics, trace } from "@opentelemetry/api";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";

useAzureMonitor();
const instrumentations = [
   new ExpressInstrumentation(),
];
registerInstrumentations({
   tracerProvider:  trace.getTracerProvider(),
   meterProvider: metrics.getMeterProvider(),
   instrumentations: instrumentations,
});  

Application Insights 브라우저 SDK 로더

Application Insights 브라우저 SDK 로더를 사용하면 다음 조건이 충족되면 웹 SDK를 노드 서버 응답에 삽입할 수 있습니다.

• 응답에 상태 코드 200있습니다.
• 응답 메서드가 GET.
• 서버 응답에는 Conent-Type html 헤더가 있습니다.
• 서버 공명에는 태그와 태그가 모두 포함됩니다.
• 응답에는 현재 /backup 웹 계측 CDN 엔드포인트가 포함되어 있지 않습니다. (현재 및 백업 Web Instrumentation CDN 엔드포인트는여기에 )

브라우저 SDK 로더 사용에 대한 자세한 내용은여기에서 찾을 수 있습니다.

클라우드 역할 이름 및 클라우드 역할 인스턴스 설정

OpenTelemetry 리소스 특성을 통해 클라우드 역할 이름 및 클라우드 역할 인스턴스를 설정할 수 있습니다.

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";

// ----------------------------------------
// Setting role name and role instance
// ----------------------------------------
const customResource = Resource.EMPTY;
customResource.attributes[SemanticResourceAttributes.SERVICE_NAME] = "my-helloworld-service";
customResource.attributes[SemanticResourceAttributes.SERVICE_NAMESPACE] = "my-namespace";
customResource.attributes[SemanticResourceAttributes.SERVICE_INSTANCE_ID] = "my-instance";

const options: AzureMonitorOpenTelemetryOptions = { resource : customResource }
useAzureMonitor(options);

리소스의 표준 특성에 대한 자세한 내용은 리소스 의미 체계 규칙참조하세요.

원격 분석 수정

이 섹션에서는 원격 분석을 수정하는 방법을 설명합니다.

범위 특성 추가

범위 특성을 추가하려면 다음 두 가지 방법 중 하나를 사용합니다.

• 계측 라이브러리에서 제공하는 옵션을 사용합니다.
• 사용자 지정 범위 프로세서를 추가합니다.

이러한 특성에는 원격 분석에 사용자 지정 속성을 추가하는 것이 포함될 수 있습니다.

팁: 계측 라이브러리에서 제공하는 옵션을 사용할 수 있는 경우 전체 컨텍스트를 사용할 수 있다는 장점이 있습니다. 따라서 사용자는 더 많은 특성을 추가하거나 필터링하도록 선택할 수 있습니다. 예를 들어 HttpClient 계측 라이브러리의 보강 옵션은 사용자에게 httpRequestMessage 자체에 대한 액세스 권한을 제공합니다. 모든 항목을 선택하여 특성으로 저장할 수 있습니다.

추적에 사용자 지정 속성 추가

범위에 추가할 모든 특성은 사용자 지정 속성으로 내보내집니다.

사용자 지정 프로세서 사용:

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { SemanticAttributes } from "@opentelemetry/semantic-conventions";


class SpanEnrichingProcessor implements SpanProcessor{
  forceFlush(): Promise<void>{
    return Promise.resolve();
  }
  shutdown(): Promise<void>{
    return Promise.resolve();
  }
  onStart(_span: Span): void{}
  onEnd(span: ReadableSpan){
    span.attributes["CustomDimension1"] = "value1";
    span.attributes["CustomDimension2"] = "value2";
    span.attributes[SemanticAttributes.HTTP_CLIENT_IP] = "<IP Address>";
  }
}

// Enable Azure Monitor integration.
const options: AzureMonitorOpenTelemetryOptions = {
    // Add the SpanEnrichingProcessor
    spanProcessors: [new SpanEnrichingProcessor()] 
}
useAzureMonitor(options);

원격 분석 필터링

다음 방법을 사용하여 애플리케이션을 나가기 전에 원격 분석을 필터링할 수 있습니다.

1. 많은 HTTP 계측 라이브러리에서 제공하는 URL 옵션을 제외합니다.

   다음 예제에서는 HTTP/HTTPS 계측 라이브러리사용하여 특정 URL을 추적에서 제외하는 방법을 보여 줍니다.

   import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
   import { IncomingMessage } from "http";
   import { RequestOptions } from "https";
   import { HttpInstrumentationConfig } from "@opentelemetry/instrumentation-http";
   
   const httpInstrumentationConfig: HttpInstrumentationConfig = {
       enabled: true,
       ignoreIncomingRequestHook: (request: IncomingMessage) => {
           // Ignore OPTIONS incoming requests
           if (request.method === 'OPTIONS') {
               return true;
           }
           return false;
       },
       ignoreOutgoingRequestHook: (options: RequestOptions) => {
           // Ignore outgoing requests with /test path
           if (options.path === '/test') {
               return true;
           }
           return false;
       }
   };
   const options : AzureMonitorOpenTelemetryOptions = {
       instrumentationOptions: {
       http:  httpInstrumentationConfig,
       }
   };
   useAzureMonitor(options);
   

2. 사용자 지정 프로세서를 사용합니다. 사용자 지정 범위 프로세서를 사용하여 특정 범위를 내보내지 않도록 제외할 수 있습니다. 범위를 내보내지 않도록 표시하려면 TraceFlagDEFAULT설정합니다. 사용자 지정 속성 추가 예제를 사용하지만 다음 코드 줄을 바꿉 있습니다.

   ...
   import { SpanKind, TraceFlags } from "@opentelemetry/api";
   import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base";
   
   class SpanEnrichingProcessor implements SpanProcessor {
       ...
   
       onEnd(span: ReadableSpan) {
           if(span.kind == SpanKind.INTERNAL){
               span.spanContext().traceFlags = TraceFlags.NONE;
           }
       }
   }
   

사용자 지정 원격 분석

이 섹션에서는 애플리케이션에서 사용자 지정 원격 분석을 수집하는 방법을 설명합니다.

사용자 지정 메트릭 추가

계측 라이브러리에서 수집한 메트릭 이외의 메트릭을 수집할 수 있습니다.

OpenTelemetry API는 다양한 메트릭 시나리오를 다루는 6개의 메트릭 "계측"을 제공하며 메트릭 탐색기에서 메트릭을 시각화할 때 올바른 "집계 유형"을 선택해야 합니다. 이 요구 사항은 OpenTelemetry 메트릭 API를 사용하여 메트릭을 보내고 계측 라이브러리를 사용할 때 적용됩니다.

다음 표에서는 각 OpenTelemetry 메트릭 계측에 대해 권장되는 집계 유형]을 보여 있습니다.

주의: 집계 형식이 표에 표시된 것 이상으로 일반적으로 의미가 없습니다.

OpenTelemetry 사양 계측을 설명하고 각 계측을 사용할 수 있는 경우의 예를 제공합니다.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { ObservableResult, metrics } from "@opentelemetry/api";

useAzureMonitor();
const meter =  metrics.getMeter("testMeter");

let histogram = meter.createHistogram("histogram");
let counter = meter.createCounter("counter");
let gauge = meter.createObservableGauge("gauge");
gauge.addCallback((observableResult: ObservableResult) => {
    let randomNumber = Math.floor(Math.random() * 100);
    observableResult.observe(randomNumber, {"testKey": "testValue"});
});

histogram.record(1, { "testKey": "testValue" });
histogram.record(30, { "testKey": "testValue2" });
histogram.record(100, { "testKey2": "testValue" });

counter.add(1, { "testKey": "testValue" });
counter.add(5, { "testKey2": "testValue" });
counter.add(3, { "testKey": "testValue2" });

사용자 지정 예외 추가

계측 라이브러리를 선택하면 Application Insights에 대한 예외가 자동으로 지원됩니다. 그러나 계측 라이브러리에서 보고하는 것 이상으로 예외를 수동으로 보고할 수 있습니다. 예를 들어 코드에서 catch된 예외는 일반적으로 보고되지 않는 있으며, 이를 보고하여 오류 블레이드 및 엔드투엔드 트랜잭션 뷰를 비롯한 관련 환경에서 주의를 끌 수 있습니다.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { trace, Exception } from "@opentelemetry/api";

useAzureMonitor();
const tracer =  trace.getTracer("testMeter");

let span = tracer.startSpan("hello");
try{
    throw new Error("Test Error");
}
catch(error){
    span.recordException(error as Exception);
}

문제 해결

자체 진단

Azure Monitor OpenTelemetry는 내부 로그에 OpenTelemetry API 로거를 사용합니다. 사용하도록 설정하려면 다음 코드를 사용합니다.

import { useAzureMonitor } from "@azure/monitor-opentelemetry";
import { DiagLogLevel } from "@opentelemetry/api";

process.env.APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL = "VERBOSE";
process.env.APPLICATIONINSIGHTS_LOG_DESTINATION = "file";
process.env.APPLICATIONINSIGHTS_LOGDIR = "C:/applicationinsights/logs";

useAzureMonitor();

APPLICATIONINSIGHTS_INSTRUMENTATION_LOGGING_LEVEL 환경 변수를 사용하여 NONE, ERROR, WARN, INFO, DEBUG, VERBOSE 및 ALL값을 지원하는 원하는 로그 수준을 설정할 수 있습니다.

로그는 APPLICATIONINSIGHTS_LOG_DESTINATION 환경 변수를 사용하여 로컬 파일에 넣을 수 있고, 지원되는 값은 filefile+console, 기본적으로 모든 로그, *nix 및 Windows용 USERDIR/AppData/Local/Temp/tmp 포함하여 applicationinsights.log 이름이 지정된 파일이 tmp 폴더에 생성됩니다. APPLICATIONINSIGHTS_LOGDIR 환경 변수를 사용하여 로그 디렉터리를 구성할 수 있습니다.

예제

몇 가지 챔피언 시나리오의 전체 샘플은 samples/ 폴더를 참조하세요.

주요 개념

OpenTelemetry 프로젝트에 대한 자세한 내용은 OpenTelemetry 사양검토하세요.

플러그 인 레지스트리

사용 중인 라이브러리에 대한 플러그 인이 이미 만들어졌는지 확인하려면 OpenTelemetry 레지스트리확인하세요.

레지스트리에서 라이브러리를 사용할 수 없는 경우 opentelemetry-js-contrib새 플러그 인 요청을 자유롭게 제안하세요.

기여

이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.