Node.js 수집기 구성

수집기는 IP 127.0.0.1 및 호스트의 기본 게이트웨이를 통한 폴백으로 Instana 에이전트와 통신을 시도합니다. 이러한 IP 중 하나에서 상담원을 사용할 수 없는 경우에는 agentHost 옵션을 사용하여 사용자 지정 IP를 사용할 수 있습니다.

require('@instana/collector')({
  agentHost: '::1' // use IPv6 to contact via localhost
});
 

또는 환경 변수를 활용하세요.

require('@instana/collector')({
  agentHost: process.env.HOST_IP
});
 

구성하지 않은 경우 Instana 수집기는 INSTANA_AGENT_HOST 이라는 환경 변수를 찾고 이 환경 변수에 정의된 내용을 사용하여 상담원과 통신합니다. 이러한 환경 변수가 없는 경우에는 먼저 localhost 에서 상담원에게 연결한 다음 기본 게이트웨이에서 연결을 시도합니다.

수집기는 포트 42699 를 통해 Instana 에이전트와 통신을 시도합니다. 포트가 변경된 경우 agentPort 옵션을 사용하여 포트를 변경할 수 있습니다.

require('@instana/collector')({
  agentPort: 42699
});
 

구성하지 않은 경우 Instana 수집기는 INSTANA_AGENT_PORT 이라는 환경 변수를 찾고 이 환경 변수에 정의된 내용을 사용하여 상담원과 통신합니다. 이러한 환경 변수가 없는 경우 기본 포트 42699로 돌아갑니다.

Node.js 애플리케이션과 Instana 에이전트가 Kubernetes 클러스터에서 실행되는 경우, 이 설정에 필요한 구성에 대한 정보는 Kubernetes 네트워크 액세스 설명서를 참조하세요.

Instana 에이전트가 있는 서버리스 환경이 아닌 환경에서는 실행 중인 Node.js 버전이 수명 종료(EOL)에 도달했음을 감지하면 Node.js 추적기가 문제 이벤트를 트리거합니다.

이러한 EOL 이벤트를 억제하려면 다음 환경 변수를 사용하여 비활성화할 수 있습니다:

INSTANA_TRACING_DISABLE_EOL_EVENTS=true
 

EOL Node.js 버전의 전체 목록은 공식 Node.js 릴리스 페이지를 참조하세요.

기본적으로 Instana Node.js 추적기는 활성 입력 스팬이 있는 종료 스팬만 캡처합니다. 이 기능을 활성화하면 추적기가 독립 실행형 종료 범위를 추적할 수 있습니다.

이 기능을 사용하려면 다음 옵션 중 하나를 사용하세요:

• 환경 변수를 설정합니다 INSTANA_ALLOW_ROOT_EXIT_SPAN 환경 변수를 설정합니다.

• 트레이서 초기화 기능을 통해 기능을 구성합니다:

  require('@instana/collector')({
  tracing: {
    allowRootExitSpan: true
  }
  });
   

만약 INSTANA_ALLOW_ROOT_EXIT_SPAN 가 1 또는 true 로 설정되어 있거나 allowRootExitSpan 가 true 로 설정되어 있으면 활성 입력 스팬이 없는 경우에도 추적기가 종료 스팬을 캡처합니다.

이 기능은 Instana 자동 계측이 지원하지 않는 메커니즘에 의해 작업이 트리거되는 다음과 같은 시나리오에 유용합니다:

• 지원되지 않는 메시징 라이브러리에서 수신되는 메시지
• 지원되지 않는 프로토콜(예: 원시 Transmission Control Protocol (TCP) 또는 WebSocket
• setTimeout, setInterval, 또는 지원되지 않는 Node.js 스케줄링 라이브러리와 같은 메커니즘을 사용하여 애플리케이션에서 내부적으로 시작된 예약된 작업

Node.js 추적기 4.9.0 에서 특정 추적 또는 호출을 제외하여 불필요한 데이터 수집을 줄일 수 있습니다. 이 필터링 메커니즘은 추적 수집을 세분화합니다. 추적을 제외하려면 Node.js 추적기 구성 설정에서 이러한 매개변수를 정의하세요:

• 기술: 관련 기술을 지정합니다(예: Kafka, Redis, DynamoDB, 또는 HTTP).
• 메소드: 제외할 방법을 식별합니다. 예를 들어 다음 기술에 대해서는 이러한 방법을 제외하세요:
  • Kafka: send, consume
  • Redis: get, type
  • DynamoDB: query, scan
  • HTTP: get, post
• 엔드포인트(해당되는 경우): 특정 엔드포인트를 기준으로 필터링을 더욱 세분화할 수 있습니다. 예를 들어 다음 기술의 엔드포인트는 다음과 같이 정의됩니다:
  • Kafka: 엔드포인트는 주제 이름입니다.
  • HTTP: 엔드포인트는 URL 경로입니다.
• 연결(선택 사항): 특정 연결에 대한 추적을 제외합니다. 예를 들어, 다음 기술에 대한 연결은 다음과 같이 정의됩니다:
  • Redis: 연결은 연결 문자열입니다.
  • HTTP: 연결에는 호스트와 포트가 포함됩니다.

추적을 사용하지 않으려면 추적을 완전히 끄거나 데이터베이스, 메시징 또는 로깅과 같은 특정 계측 또는 전체 그룹을 선택적으로 제외할 수 있습니다. 이러한 유연성을 통해 애플리케이션의 필요에 따라 추적을 미세 조정할 수 있습니다.

추적을 비활성화하도록 구성을 적용하려면 다음 방법 중 하나를 사용합니다:

• 환경 변수
• 코드 내 구성
• 상담원 구성(YAML)

자동 추적도 기본적으로 활성화되어 있습니다. 자동 추적만 비활성화하려면(SDK 또는 openTracing 을 통한 수동 추적은 활성화된 상태로 유지) 다음 옵션을 초기화 함수에 전달합니다:

require('@instana/collector')({
  tracing: {
    automaticTracingEnabled: false
  }
});
 

마지막으로 환경 변수 INSTANA_DISABLE_AUTO_INSTR=true 를 설정하여 자동 추적을 비활성화할 수 있습니다.

자동 추적이 비활성화된 경우에도 SDK 또는 OpenTracing API를 사용하여 수동으로 스팬을 생성할 수 있습니다.

오픈 텔레메트리 통합은 기본적으로 활성화되어 있습니다. 통합을 비활성화하려면 초기화 함수에 다음 옵션을 전달하세요:

require('@instana/collector')({
  tracing: {
    useOpentelemetry: false
  }
});
 

또한 INSTANA_DISABLE_USE_OPENTELEMETRY 변수를 true 로 설정하여 OpenTelemetry 통합을 비활성화할 수 있습니다. 자세한 내용은 Instana 환경 변수를 참조하십시오.

Instana Node.js 수집기가 워커 스레드를 추적하지 못하도록 하려면 다음 환경 변수를 설정하세요:

INSTANA_DISABLE_WORKER_THREADS=true

이 구성은 모든 작업자 스레드에 대한 추적을 비활성화하지만 메인 프로세스는 여전히 자동으로 추적됩니다. 작업자 스레드가 추적에서 제외하려는 내부 또는 백그라운드 작업을 실행하는 경우 이 구성을 사용합니다.

기본적으로 수집기는 캡처된 각 종료 스팬에 대해 마지막 10개의 호출 위치를 캡처합니다. 이 값은 필요에 따라 증가하거나 감소시킬 수 있습니다.

스택 추적 캡처의 두 가지 측면을 구성할 수 있습니다:

• 스택 추적 길이 : 캡처할 호출 위치의 수.
  • 지원되는 값: 0–500
  • 기본값: 10
• 스택 추적 모드 : 스택 추적이 캡처되는 방식.
  • 지원되는 값:
    • all: 모든 종료 스팬에 대한 스택 추적을 수집합니다(기본값).
    • error오류가 발생한 스팬에 대해서만 스택 추적을 수집합니다.
    • none: 스택 추적을 수집하지 않습니다.

다음 옵션 중 하나를 사용하여 스택 추적 캡처를 구성할 수 있습니다:

• 환경 변수
• 코드 내 구성
• 에이전트 구성

Instana 수집기는 프로젝트 내에서 기본 package.json 파일을 찾아 애플리케이션 이름과 같은 중요한 정보를 추출하려고 시도합니다. package.json 파일에 대한 사용자 지정 경로를 정의해야 하거나 수집기가 파일을 찾을 수 없는 경우 packageJsonPath 이라는 구성 옵션을 사용할 수 있습니다.

require('@instana/collector')({
  packageJsonPath: 'absolute/path/to/package.json'
});
 

INSTANA_PACKAGE_JSON_PATH 환경 변수를 설정하여 package.json 파일의 경로를 구성할 수도 있습니다.

서비스는 Instana의 핵심 개념입니다. 통화, 범위 및 추적은 서비스와 밀접하게 연관되어 있습니다. 기본적으로 Node.js 수집기는 기본 package.json 파일의 name 및 version 속성을 사용합니다. 서비스 이름을 사용자 지정하려면 serviceName 속성을 구성하면 됩니다.

require('@instana/collector')({
  serviceName: 'shop'
});
 

환경 변수 INSTANA_SERVICE_NAME 를 설정하여 사용자 지정 서비스 이름을 구성할 수도 있습니다. 사용자 지정 서비스 구성에 대한 자세한 내용은 전역으로 서비스 이름 설정하기를 참조하세요.

수집기 버전 4.x, Kafka 추적 상관관계 헤더는 항상 string 형식으로 전송되며, binary 형식은 지원되지 않습니다. 자세한 내용은 Kafka 헤더 마이그레이션을 참조하세요.

환경 변수 INSTANA_KAFKA_HEADER_FORMAT 및 코드 내 구성 옵션 tracing: { kafka: { headerFormat: .... }}} 을 참조하는 모든 구성을 제거합니다.

기본 로그 수준을 변경하려면 다음을 통해 구성할 수 있습니다:

require('@instana/collector')({
  level: 'debug'
});
 

환경 변수 INSTANA_LOG_LEVEL 를 debug, info, warn 또는 error 로 설정하여 로그 수준을 구성할 수도 있습니다. 마지막으로 INSTANA_DEBUG 을 비어 있지 않은 문자열로 설정하면 로그 수준이 debug 으로 설정됩니다.

기본 로그 수준은 info 입니다. 예기치 않은 Instana 관련 디버그 로그( "name":"@instana/collector" 및 "level":20 등의 로그 행)가 표시되는 경우 구성에서 로그 수준을 디버깅으로 설정했는지 또는 INSTANA_LOG_LEVEL=debug 또는 INSTANA_DEBUG 이 설정되어 있는지 확인합니다. 자체 로거를 제공하는 경우(아래 참조) 원하는 대로 로그 수준을 설정할 책임이 있습니다.

로거 설정을 참조하세요.