Application Insights를 사용하여 Node.js 서비스 및 앱 모니터링

Application Insights는 배포 후에 구성 요소를 모니터링하여 성능과 기타 문제를 발견합니다. 데이터 센터, Azure VM 및 웹앱에서 호스트되는 Node.js 서비스와 다른 퍼블릭 클라우드에서도 Application Insights를 사용할 수 있습니다.

모니터링 데이터를 수신, 저장 및 탐색하려면 코드에 SDK를 포함합니다. 그런 다음 Azure에서 해당 Application Insights 리소스를 설정합니다. SDK는 추가 분석 및 탐색을 위해 해당 리소스로 데이터를 보냅니다.

Node.js 클라이언트 라이브러리는 들어오고 나가는 HTTP 요청, 예외 및 여러 시스템 메트릭을 자동으로 모니터링할 수 있습니다. 0.20 버전부터 클라이언트 라이브러리는 MongoDB, MySQL 및 Redis와 같은 일반적인 타사 패키지 일부를 모니터링할 수 있습니다.

들어오는 HTTP 요청과 관련된 모든 이벤트는 좀 더 빠른 문제 해결을 위해 상호 관계가 지정됩니다.

TelemetryClient API를 사용하여 앱과 시스템의 다양한 측면을 수동으로 계측하고 모니터링 할 수 있습니다. TelemetryClient API는 이 문서의 뒷부분에 더 자세히 설명합니다.

시작하기

앱 또는 서비스에 대한 모니터링을 설정하려면 다음 작업을 완료합니다.

필수 조건

시작하기 전에 Azure 구독이 있는지 확인하여 없는 경우 무료 계정을 새로 만듭니다. 조직에 이미 Azure 구독이 있으면 관리자가 다음 지침에 따라 사용자를 구독에 추가할 수 있습니다.

Application Insights 리소스 설정

1. Azure Portal에 로그인합니다.
2. Application Insights 리소스를 만듭니다.

Node.js 클라이언트 라이브러리 설정

데이터를 수집할 수 있도록 앱에 SDK를 포함합니다.

1. 새 리소스에서 리소스의 연결 문자열을 복사합니다. Application Insights는 연결 문자열을 사용하여 Azure 리소스에 데이터를 매핑합니다. SDK에서 연결 문자열을 사용하려면 먼저 환경 변수 또는 코드에 연결 문자열을 지정해야 합니다.

   

2. package.json을 통해 앱의 종속성에 Node.js 클라이언트 라이브러리를 추가합니다. 앱의 루트 폴더에서 다음을 실행합니다.

   npm install applicationinsights --save
   

   참고 항목

   TypeScript를 사용하는 경우 별도의 "typings" 패키지를 설치하지 마세요. 이 NPM 패키지에는 기본 제공 입력 항목이 포함되어 있습니다.

3. 코드에서 라이브러리를 명시적으로 로드합니다. SDK는 여러 다른 라이브러리에 계측 값을 삽입합니다. 따라서 최대한 신속하게, 심지어 다른 require 문보다도 먼저 라이브러리를 로드합니다.

   let appInsights = require('applicationinsights');
   

4. 또한 연결 문자열을 setup() 또는 new appInsights.TelemetryClient()에 수동으로 전달하는 대신 APPLICATIONINSIGHTS_CONNECTION_STRING 환경 변수를 통해 제공할 수 있습니다. 이렇게 하면 연결 문자열이 커밋된 소스 코드의 영향을 받지 않고, 다른 환경에 다른 연결 문자열을 지정할 수 있습니다. 수동으로 구성하려면 appInsights.setup('[your connection string]');을 호출합니다.

   추가 구성 옵션은 다음 섹션을 참조하세요.

   appInsights.defaultClient.config.disableAppInsights = true를 설정하면 원격 분석을 전송하지 않고 SDK를 사용해 볼 수 있습니다.

5. appInsights.start();를 호출하면 데이터를 자동으로 수집하고 전송하기 시작합니다.

앱 모니터링

SDK는 Node.js 런타임 및 일반적인 타사 모듈 일부에 대한 원격 분석 데이터를 자동으로 수집합니다. 애플리케이션을 사용하여 이 데이터를 생성합니다.

그런 다음 Azure Portal에서 이전에 만든 Application Insights 리소스로 이동합니다. 타임라인 개요에서 먼저 몇 가지 데이터 요소를 찾습니다. 더 자세한 데이터를 보려면 차트에서 다른 구성 요소를 선택합니다.

앱에 대해 검색된 토폴로지를 보려면 애플리케이션 맵을 사용합니다.

데이터 없음

SDK는 제출을 위해 데이터를 일괄 처리하므로 항목이 포털에 표시되기까지 지연이 있을 수 있습니다. 리소스에 데이터가 보이지 않으면 다음 해결 방법 중 몇 가지를 시도해 보세요.

• 애플리케이션을 계속 사용합니다. 더 많은 작업을 수행하여 더 많은 원격 분석을 생성합니다.
• 포털 리소스 보기에서 새로 고침을 선택합니다. 차트는 자체에서 주기적으로 새로 고치지만, 수동으로 새로 고침하면 즉시 새로 고쳐집니다.
• 필요한 발신 포트가 열려 있는지 확인합니다.
• 검색을 사용하여 특정 이벤트를 찾습니다.
• FAQ를 확인합니다.

기본 사용법

HTTP 요청, 인기 있는 타사 라이브러리 이벤트, 처리되지 않은 예외, 시스템 메트릭에 대한 기본 제공 컬렉션은 다음과 같습니다.

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

다른 패키지를 로드하기 전에 스크립트에서 최대한 빨리 Application Insights 라이브러리 require("applicationinsights")를 로드합니다. 이 단계는 Application Insights 라이브러리에서 나중에 추적하기 위한 패키지를 준비할 수 있도록 하는 데 필요합니다. 비슷하게 준비하는 과정에서 다른 라이브러리와 충돌하는 경우, 충돌이 발생한 후 Application Insights 라이브러리를 로드해 보세요.

JavaScript가 콜백을 처리하는 방식 때문에 외부 종속성과 이후 콜백에서 요청을 추적하려면 추가 작업이 필요합니다. 이 추가 추적은 기본적으로 사용하도록 설정되어 있습니다. SDK 구성 섹션에 설명된 대로 setAutoDependencyCorrelation(false)을 호출하여 사용하지 않도록 설정합니다.

0.22 이전 버전에서 마이그레이션

0.22 이전 버전과 이후 버전의 릴리스 사이에는 호환성이 손상되는 변경 내용이 포함되어 있습니다. 해당 변경 내용은 다른 Application Insights SDK와의 일관성을 유지하고 향후 확장성을 허용하도록 설계되었습니다.

일반적으로 다음 작업을 통해 마이그레이션할 수 있습니다.

• appInsights.client에 대한 참조를 appInsights.defaultClient로 바꾸기.
• appInsights.getClient()에 대한 참조를 new appInsights.TelemetryClient()로 바꾸기.
• 인수를 명명된 속성을 포함하는 단일 개체를 사용하여 모든 인수를 client.track* 메서드로 바꿉니다. 각 원격 분석 형식의 예외 개체 관련 사항은 IDE의 기본 제공 형식 힌트 또는 TelemetryTypes를 참조하세요.

appInsights.setup()에 연결하지 않고 SDK 구성 함수에 액세스하는 경우 이제 appInsights.Configurations에서 이러한 함수를 찾을 수 있습니다. 예제는 appInsights.Configuration.setAutoCollectDependencies(true)입니다. 다음 섹션의 기본 구성에 대한 변경 내용을 검토합니다.

SDK 구성

appInsights 개체는 많은 구성 메서드를 제공합니다. 해당 구성 메서드는 다음 코드 조각에 기본값과 함께 나열됩니다.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

서비스에서 이벤트의 상관 관계를 완전하게 지정하려면 .setAutoDependencyCorrelation(true)을 설정합니다. 이 옵션을 설정하면 SDK가 Node.js의 비동기 콜백에서 컨텍스트를 추적할 수 있습니다.

IDE의 기본 제공 형식 힌트 또는 applicationinsights.ts에서 자세한 정보와 선택적 2차 인수에 대한 설명을 검토합니다.

샘플링

기본적으로 SDK는 수집된 모든 데이터를 Application Insights 서비스로 보냅니다. 샘플링을 사용하여 데이터의 양을 줄이려면 클라이언트의 config 개체에서 samplingPercentage 필드를 설정합니다. samplingPercentage를 100(기본값)으로 설정하면 모든 데이터가 전송되고, 0으로 설정하면 아무 데이터도 전송되지 않습니다.

자동 상관 관계를 사용하는 경우 단일 요청과 관련된 모든 데이터가 하나의 단위로 포함되거나 제외됩니다.

다음과 같은 코드를 추가해 샘플링을 사용하도록 설정합니다.

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

다중 구성 요소 애플리케이션을 위한 다중 역할

일부 시나리오에서 애플리케이션은 동일한 연결 문자열로 모두 계측하려는 여러 구성 요소로 구성될 수 있습니다. 별도의 연결 문자열을 사용하는 것처럼 이러한 구성 요소를 포털에서 별도의 단위로 계속 표시하려고 합니다. 예를 들어, 애플리케이션 맵의 개별 노드가 있습니다. Application Insights 리소스에 데이터를 보내는 다른 구성 요소와 한 구성 요소의 원격 분석을 구별하려면 RoleName 필드를 수동으로 구성해야 합니다.

다음 코드를 사용하여 RoleName 필드를 설정합니다.

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

브라우저 SDK 로더

구성에 따라 JavaScript(웹) SDK 로더 스크립트 삽입을 통해 노드 서버에 대해 자동 웹 계측을 사용하도록 설정할 수 있습니다.

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

또는 환경 변수 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true를 설정하여.

다음 요구 사항이 모두 충족되면 노드 서버 응답에서 웹 계측이 사용하도록 설정됩니다.

• 응답의 상태 코드는 200입니다.
• 응답 방법은 GET입니다.
• 서버 응답에 Content-Type HTML이 있습니다.
• 서버 응답에는 <head> 및 </head> 태그가 모두 포함되어 있습니다.
• 응답이 압축된 경우에는 Content-Encoding 형식이 하나만 있어야 하며 인코딩 형식은 gzip, br 또는 deflate 중 하나여야 합니다.
• 응답에 현재 /backup web Instrumentation CDN 엔드포인트가 포함되어 있지 않습니다. (현재 및 백업 웹 계측 CDN 엔드포인트는 여기)

웹 계측 CDN 엔드포인트는 환경 변수 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints"를 설정하여 변경할 수 있습니다. 웹 계측 연결 문자열은 환경 변수 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"을 설정하여 변경할 수 있습니다.

타사 라이브러리 자동 계측

비동기 호출에서 컨텍스트를 추적하려면 MongoDB 및 Redis와 같은 타사 라이브러리에 일부 변경이 필요합니다. 기본적으로 Application Insights는 diagnostic-channel-publishers를 사용하여 이러한 라이브러리 중 일부를 원숭이 패치합니다. APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL 환경 변수를 설정하면 이 기능을 사용하지 않을 수 있습니다.

APPLICATION_INSIGHTS_NO_PATCH_MODULES 환경 변수를 사용하지 않도록 설정할 패키지 목록을 쉼표로 구분하여 설정해 놓으면 개별 몽키 패치를 사용하지 않도록 설정할 수 있습니다. 예를 들어, console 및 redis 패키지를 패치하지 않으려면 APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis를 사용합니다.

현재 9개의 패키지(bunyan,console,mongodb,mongodb-core,mysql,redis,winston,pg 및 pg-pool)가 계측됩니다. 이러한 패키지의 정확한 버전에 대한 정보는 diagnostic-channel-publishers' 추가 정보를 참조하세요.

bunyan, winston 및 console 패치는 setAutoCollectConsole의 사용하도록 설정 여부에 따라 Application Insights 추적 이벤트를 생성합니다. 나머지는 setAutoCollectDependencies가 사용하도록 설정되었는지 여부에 따라 Application Insights 종속성 이벤트를 생성합니다.

라이브 메트릭

앱에서 Azure로 라이브 메트릭을 전송하려면 setSendLiveMetrics(true)를 사용합니다. 현재 포털의 라이브 메트릭 필터링은 지원되지 않습니다.

확장 메트릭

앱에서 Azure로 확장 원시 메트릭을 보낼 수 있도록 설정하려면 별도의 원시 메트릭 패키지를 설치합니다. SDK는 설치되면 자동으로 로드되고 Node.js 네이티브 메트릭 수집을 시작합니다.

npm install applicationinsights-native-metrics

현재 원시 메트릭 패키지는 가비지 수집 CPU 타임, 이벤트 루프 틱 및 힙 메모리 사용량의 자동수집을 수행합니다.

• 가비지 수집: 각 가비지 수집 형식에 소요된 CPU 시간과 형식별 발생 횟수입니다.
• 이벤트 루프: 발생한 틱 수 및 소요된 총 CPU 시간입니다.
• 힙 대 비힙: 애플리케이션에서 힙 메모리 또는 비힙 메모리로 사용된 메모리 사용량입니다.

분산 추적 모드

기본적으로 SDK는 Application Insights SDK로 계측된 다른 애플리케이션 또는 서비스에서 이해하는 헤더를 보냅니다. 기존 AI 헤더 외에 W3C Trace Context 헤더의 송수신을 사용하도록 설정할 수 있습니다. 이러한 방식으로 기존 레거시 서비스와의 상관 관계를 끊지 않습니다. W3C 헤더를 사용하도록 설정하면 앱이 Application Insights를 사용하여 계측되지 않은 다른 서비스와의 상관 관계를 지정할 수 있지만, 관련 W3C 표준을 적용합니다.

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

TelemetryClient API

TelemetryClient API에 대한 전체 설명은 사용자 지정 이벤트 및 메트릭용 Application Insights API를 참조하세요.

Node.js용 Application Insights 클라이언트 라이브러리를 사용하여 모든 요청, 이벤트, 메트릭 또는 예외를 추적할 수 있습니다. 다음 코드 예제에는 사용할 수 있는 몇 가지 API가 나와 있습니다.

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

종속성 추적

다음 코드를 사용하여 종속성을 추적합니다.

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

이벤트 루프 예약 시간을 측정하기 위해 trackMetric을 사용하는 예제 유틸리티는 다음과 같습니다.

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

모든 이벤트에 사용자 지정 속성 추가

다음 코드를 사용하여 모든 이벤트에 사용자 지정 속성을 추가합니다.

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

HTTP GET 요청 추적

다음 코드를 사용하여 HTTP GET 요청을 수동으로 추적합니다.

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

또는 trackNodeHttpRequest 메서드를 사용하여 요청을 추적할 수 있습니다.

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

서버 시작 시간 추적

다음 코드를 사용하여 서버 시작 시간을 추적합니다.

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

플러시

기본적으로 원격 분석 데이터는 수집 서버로 전송되기 전에 15초 동안 버퍼링됩니다. 애플리케이션의 수명이 짧은 경우(예: CLI 도구) appInsights.defaultClient.flush()를 사용하여 애플리케이션이 종료될 때 버퍼링된 원격 분석을 수동으로 플러시해야 할 수 있습니다.

SDK가 애플리케이션 크래시를 검색하면 appInsights.defaultClient.flush({ isAppCrashing: true })를 사용하여 플러시를 호출합니다. 플러시 옵션 isAppCrashing을 사용하면 애플리케이션이 비정상 상태인 것으로 간주되며 원격 분석을 전송하는 데 적합하지 않습니다. 대신 SDK는 모든 버퍼링된 원격 분석을 영구 스토리지에 저장하고 애플리케이션이 종료되도록 합니다. 애플리케이션이 다시 시작되면 영구 스토리지에 저장된 모든 원격 분석을 보내려고 합니다.

원격 분석 프로세서를 사용하여 데이터 전처리

원격 분석 프로세서를 사용하여 수집된 데이터를 처리 및 필터링한 후에 보존용으로 전송할 수 있습니다. 원격 분석 항목을 클라우드로 보내기 전에 원격 분석 프로세서를 추가된 순서대로 하나씩 호출합니다.

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

원격 분석 프로세서가 false를 반환하면 해당 원격 분석 항목이 전송되지 않습니다.

모든 원격 분석 프로세서는 검사 및 수정을 위해 원격 분석 데이터 및 봉투를 수신합니다. 원격 분석 프로세서는 또한 컨텍스트 개체를 수신합니다. 해당 개체의 내용은 수동으로 추적된 원격 분석 데이터에 대해 track 메서드를 호출할 때 contextObjects 매개 변수에 의해 정의됩니다. 자동으로 수집된 원격 분석 데이터에 대해 해당 개체는 (자동 종속성 상관 관계를 사용하는 경우) appInsights.getCorrelationContext()에서 제공하는 사용 가능 요청 정보 및 영속 요청 콘텐츠로 채워집니다.

원격 분석 프로세서의 TypeScript 형식은 다음과 같습니다.

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

예를 들어 예외에서 스택 추적 데이터를 제거하는 프로세서를 작성하고 다음과 같이 추가할 수 있습니다.

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

여러 연결 문자열 사용

여러 Application Insights 리소스를 만들고 해당 연결 문자열을 사용하여 각각에 서로 다른 데이터를 보낼 수 있습니다.

예시:

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

고급 구성 옵션

클라이언트 개체에는 고급 시나리오에 대한 다양한 옵션 설정이 포함된 config 속성이 포함되어 있습니다. 설정하려면 다음을 사용합니다.

client.config.PROPERTYNAME = VALUE;

해당 속성은 클라이언트마다 고유하므로 new appInsights.TelemetryClient()를 사용하여 만든 클라이언트와 별도로 appInsights.defaultClient를 구성할 수 있습니다.

자주 묻는 질문

원격 분석 상관관계를 사용하지 않도록 설정하려면 어떻게 해야 하나요?

원격 분석 상관관계를 사용하지 않도록 설정하려면 구성에서 correlationHeaderExcludedDomains 속성을 사용합니다. 자세한 내용은 ApplicationInsights-node.js를 참조하세요.

문제 해결

"데이터 없음" 시나리오 및 로그 사용자 지정을 비롯한 문제 해결 정보는 Application Insights의 Node.js 앱 및 서비스 모니터링 문제 해결을 참조하세요.

다음 단계

• 포털에서 원격 분석 모니터링
• 원격 분석에 분석 쿼리 작성