Skip to content
Monithub DocsMonithub Docs

애플리케이션 연결

전체 문서 PDF

애플리케이션 카탈로그는 소스 코드를 직접 수정하지 않고 OpenTelemetry 자동 계측을 시작 과정에 적용합니다. Connect에서 실제 실행 환경을 고르고, 생성된 설치·환경 변수·실행 블록을 같은 애플리케이션에 순서대로 적용하세요.

카탈로그 지원 버전 주로 확인하는 데이터
Java Java 8 이상 트레이스, JVM 메트릭, 지원 Logback·Log4j2 로그
Node.js Node.js 22·24, npm 트레이스, Node·V8 메트릭, 지원 logger 로그
Python Python 3.10 이상 지원 라이브러리 텔레메트리, 표준 logging 로그

자동 계측 범위는 애플리케이션이 사용하는 라이브러리에 따라 달라집니다. 연결 후 HTTP 요청, 배치 작업, 메시지 처리처럼 실제 활동을 발생시키고 먼저 트레이스와 로그를 확인하세요.

공통 적용 순서

Section titled “공통 적용 순서”
  1. 카탈로그와 애플리케이션이 실제 실행되는 환경을 선택합니다.
  2. 서비스 이름과 운영 환경을 입력합니다. 애플리케이션에 service.name이 이미 있으면 기존 값이 사용됩니다.
  3. 설정 생성을 누르고 표시된 설치 명령을 애플리케이션 디렉터리에서 실행합니다.
  4. 생성된 환경 변수 블록 전체를 애플리케이션 실행 환경에 설정합니다.
  5. 생성된 방식으로 애플리케이션을 다시 시작하고 실제 요청이나 작업을 발생시킵니다.
  6. Connect의 데이터 수집 확인에서 신호별 결과를 확인합니다.

문서의 축약 예시를 그대로 복사하지 말고 현재 연결에 표시된 명령과 환경 변수 전체를 사용하세요. 여기에는 실제 조직과 연결에 필요한 값이 포함됩니다.

Java

Section titled “Java”

Java는 OpenTelemetry Java Agent JAR을 JVM 시작 시 연결합니다. 애플리케이션 코드나 빌드 의존성을 바꾸지 않고 지원되는 라이브러리의 요청, 외부 호출, 데이터베이스 호출 등을 계측합니다.

Java 카탈로그와 Agent 설치 대상, 연결 정보가 순서대로 강조된 Connect 화면
  1. Java를 선택합니다.
  2. JAR을 내려받아 실행할 환경을 선택합니다. Docker는 기존 이미지와 실행 방식을 유지한 채 Agent를 포함하거나 마운트하는 경우에 선택합니다.
  3. 서비스 이름과 운영 환경을 입력하고 설정 생성을 누릅니다.

생성된 다운로드와 체크섬 확인 명령을 먼저 실행합니다. 이어서 같은 실행 환경에 환경 변수 블록을 적용하고 기존 JAR 이름과 인자를 보존한 채 Agent 옵션을 추가합니다.

Terminal window
# Connect가 생성한 환경 변수 블록을 먼저 적용합니다.
java -javaagent:./opentelemetry-javaagent.jar -jar <your-app>.jar

서비스 관리자나 시작 스크립트가 Java를 실행한다면 그 명령에 -javaagent 옵션을 추가한 뒤 서비스를 다시 시작하세요. Docker에서는 Connect가 표시한 마운트 경로와 환경 변수를 기존 이미지 실행 명령에 반영합니다.

Node.js

Section titled “Node.js”

Node.js는 애플리케이션 소스에 OpenTelemetry 패키지를 npm 의존성으로 설치하고, NODE_OPTIONS로 자동 계측을 애플리케이션 코드보다 먼저 불러옵니다.

Node.js 카탈로그와 npm 설치 대상, CJS와 ESM 모듈 방식 선택 영역이 순서대로 강조된 Connect 화면
  1. Node.js를 선택합니다.
  2. npm 패키지를 설치할 애플리케이션 환경을 선택합니다.
  3. Node.js가 실제로 실행하는 빌드 결과를 기준으로 모듈 방식을 선택합니다.
    • CommonJS (CJS): 실행 파일이 require()를 사용하거나 CommonJS로 빌드된 경우
    • ECMAScript modules (ESM): 실행 파일이 .mjs이거나 실행 시 사용하는 package.json에 "type": "module"이 있는 경우

TypeScript 소스의 import 문법만 보고 고르지 마세요. 컴파일 결과가 CommonJS라면 CJS를 선택합니다.

Connect가 생성한 고정 버전 npm 설치 명령을 애플리케이션 소스 디렉터리에서 실행하고 변경된 package.json과 package-lock.json을 기존 배포 방식에 반영합니다. 환경 변수와 NODE_OPTIONS를 설정한 같은 셸 또는 배포 환경에서 기존 시작 명령을 실행하세요.

Terminal window
npm install --save-exact <Connect가 표시한 OpenTelemetry 패키지>
export NODE_OPTIONS="<Connect가 표시한 CJS 또는 ESM 값>"
npm start

NODE_OPTIONS는 Node.js가 시작될 때 공통 옵션을 전달하는 환경 변수입니다. Connect가 생성한 값이 자동 계측을 먼저 불러오므로 애플리케이션과 logger가 계측 가능한 상태로 로드됩니다. 기존 시작 명령이 npm start가 아니라면 마지막 줄만 실제 명령으로 바꾸세요.

로그는 애플리케이션이 사용하는 공식 지원 logger에서 수집됩니다. logger를 사용하지 않는 애플리케이션에 Winston, Pino, Bunyan 자체를 새로 설치할 필요는 없습니다.

Python

Section titled “Python”

Python은 애플리케이션이 사용하는 Python 환경에 자동 계측 패키지를 설치합니다. 기존 가상환경이 있다면 먼저 활성화하고, 없다면 애플리케이션을 실행하는 현재 Python 환경에서 진행하세요.

Python 카탈로그와 pip 설치 대상, 연결 정보가 순서대로 강조된 Connect 화면
  1. Python을 선택합니다.
  2. 패키지를 설치하고 애플리케이션을 실행할 동일한 환경을 선택합니다.
  3. 서비스 이름과 운영 환경을 입력하고 설정 생성을 누릅니다.

Connect가 생성한 pip 설치 명령을 실행한 뒤 opentelemetry-bootstrap으로 현재 환경에 이미 설치된 지원 라이브러리의 계측 패키지를 설치합니다. 환경 변수 블록을 적용하고 기존 실행 명령 앞에 opentelemetry-instrument를 붙입니다.

Terminal window
python -m pip install <Connect가 표시한 OpenTelemetry 패키지>
opentelemetry-bootstrap -a install
opentelemetry-instrument <your-existing-command>

python, pip, opentelemetry-bootstrap, 실제 애플리케이션이 서로 다른 가상환경을 가리키지 않는지 확인하세요. Docker는 기존 Dockerfile의 애플리케이션 의존성 설치 뒤에 Connect가 생성한 블록을 추가하고 이미지를 다시 빌드합니다.

연결 후 확인

Section titled “연결 후 확인”

애플리케이션을 다시 시작한 뒤 실제 요청이나 작업을 여러 번 발생시키고 데이터 수집 확인을 누릅니다.

  • 트레이스가 없으면 새 프로세스의 실행 명령에 Agent 또는 자동 계측 옵션이 포함됐는지 확인합니다.
  • Node.js 로그가 없으면 사용하는 logger가 공식 계측 대상인지, 자동 계측이 logger보다 먼저 로드됐는지 확인합니다.
  • Python 계측 명령을 찾지 못하면 패키지를 설치한 Python 환경과 실행 환경이 같은지 확인합니다.
  • Docker 변경 후에는 이미지를 다시 빌드하고 Connect가 생성한 환경 변수를 새 컨테이너에 전달합니다.
  • Node.js와 Python의 메트릭은 사용하는 라이브러리와 실제 활동에 따라 보이지 않을 수 있습니다. 먼저 트레이스와 지원 로그로 연결을 확인합니다.

공통 상태 확인과 재시도 방법은 연결 및 수집 확인을 참고하세요.