Skip to content
Monithub DocsMonithub Docs

애플리케이션 연결

전체 문서 PDF

애플리케이션 카탈로그는 Java, Node.js, Python의 시작 과정에 OpenTelemetry 자동 계측을 적용합니다. Connect에서 애플리케이션의 실행 환경을 선택하고 설정을 생성한 뒤, 아래에서 언어별 적용 방법을 확인하세요.

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

자동 계측 범위는 애플리케이션이 사용하는 라이브러리에 따라 달라집니다. HTTP 요청, 배치 작업, 메시지 처리 등 지원되는 작업이 실행되면 해당 데이터가 수집됩니다.

공통 적용 순서

Section titled “공통 적용 순서”

설치 · 설정 적용에서 생성된 블록을 설치 → 환경 변수 적용 → 애플리케이션 재시작 순서로 반영합니다. 환경 변수는 설정을 작성하는 PC가 아니라 실제 애플리케이션 프로세스에 전달되어야 합니다.

실행 방식 환경 변수를 적용할 곳
Linux / macOS에서 직접 실행 Connect의 Bash 환경 변수 블록을 적용한 같은 터미널에서 앱 실행
Windows에서 직접 실행 Connect의 PowerShell 환경 변수 블록을 적용한 같은 PowerShell 창에서 앱 실행
서비스 관리자·프로세스 관리자로 실행 해당 서비스의 환경 변수 설정과 시작 명령에 반영한 뒤 서비스 재시작
Docker 앱 컨테이너의 환경 변수와 시작 명령에 반영한 뒤 컨테이너 재생성

Docker의 생성 명령은 Bash 기준입니다. Docker Compose를 사용한다면 환경 변수는 해당 서비스의 environment 또는 env_file에 반영합니다. 환경 변수 파일에는 셸용 export 명령 대신 각 변수의 실제 값을 이름=값 형식으로 저장하세요.

현재 연결에 표시된 환경 변수 전체를 사용하세요. 조직 인증과 연결 식별에 필요한 값이 포함됩니다. 애플리케이션에 서비스 이름이 이미 설정되어 있다면 생성된 블록에서 사용하는 이름도 확인합니다.

Java

Section titled “Java”

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

  1. Connect의 다운로드·체크섬 확인 명령으로 Agent JAR을 준비합니다. Java 프로세스가 읽을 수 있는 경로에 저장합니다.
  2. 생성된 환경 변수 블록 전체를 Java 프로세스의 실행 환경에 적용합니다.
  3. 기존 JVM 옵션, 애플리케이션 JAR 이름과 인자를 유지하면서 -javaagent를 JVM 옵션에 추가하고 다시 시작합니다.
Linux / macOS 실행 예시
java -javaagent:./opentelemetry-javaagent.jar -jar app.jar
Windows PowerShell 실행 예시
java -javaagent:.\opentelemetry-javaagent.jar -jar app.jar

위 예시의 app.jar와 Agent 경로를 실제 값으로 바꾸세요. 시작 스크립트나 애플리케이션 서버를 사용한다면 해당 Java 프로세스의 JVM 옵션에 반영합니다. 이미 OpenTelemetry Java Agent를 사용 중이면 같은 Agent를 중복으로 추가하지 않습니다.

Java Docker에 적용

Section titled “Java Docker에 적용”
  1. Agent JAR을 이미지에 포함하거나 컨테이너에 읽기 전용으로 마운트합니다. 생성 명령의 마운트 경로는 /otel/opentelemetry-javaagent.jar입니다.
  2. 기존 Dockerfile의 ENTRYPOINT·CMD 또는 시작 스크립트에서 실제 Java 명령에 -javaagent:/otel/opentelemetry-javaagent.jar를 추가합니다. 기존 초기화 작업과 앱 인자는 유지합니다.
  3. 생성된 환경 변수 전체를 앱 컨테이너에 전달하고 재생성합니다. 이미지에 Agent나 시작 명령을 추가했다면 먼저 이미지를 다시 빌드합니다.

Connect의 docker run 예시는 이미지 뒤에 Java 실행 명령을 지정합니다. 기존 이미지에 ENTRYPOINT가 있으면 이 명령이 인자로 전달되므로, 예시 전체를 그대로 추가하지 말고 기존 컨테이너 실행 정의에 Agent 옵션과 환경 변수를 반영하세요.

Node.js

Section titled “Node.js”

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

설정 생성 시 Node.js가 실제로 실행하는 빌드 결과를 기준으로 모듈 방식을 선택합니다.

모듈 방식 선택 기준
CommonJS (CJS) 실행 파일이 .cjs이거나 require()·module.exports를 사용하는 CommonJS 코드인 경우
ECMAScript modules (ESM) 실행 파일이 .mjs이거나 실행 시 사용하는 package.json에 "type": "module"이 있는 경우

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

  1. Connect가 생성한 고정 버전 npm 설치 명령을 애플리케이션 소스 디렉터리에서 실행합니다.
  2. 변경된 package.json과 package-lock.json을 기존 배포 방식에 반영합니다. 계측 패키지는 앱 실행에 필요한 의존성이므로 배포 시 제외하지 않습니다.
  3. 생성된 환경 변수 블록 전체와 NODE_OPTIONS를 앱 실행 환경에 적용합니다. 기존 NODE_OPTIONS가 있다면 필요한 옵션을 유지하면서 계측 옵션을 추가합니다.
  4. 기존 시작 명령으로 앱을 다시 시작합니다. npm start를 사용하지 않는 앱은 실제 시작 명령을 사용합니다.

로그는 현재 앱이 사용하는 지원 로깅 라이브러리에서 수집합니다. 계측을 위해 Winston, Pino, Bunyan을 새로 설치할 필요는 없습니다.

Node.js Docker에 적용

Section titled “Node.js Docker에 적용”
  1. 소스 디렉터리에서 생성된 npm 설치 명령을 실행하고 변경된 package.json·package-lock.json을 Docker 빌드에 포함합니다.
  2. 기존 Dockerfile의 npm ci로 의존성을 설치하고 이미지를 다시 빌드합니다. 멀티 스테이지라면 최종 실행 이미지에도 계측 패키지가 포함되어야 합니다.
  3. 생성된 환경 변수와 NODE_OPTIONS를 앱 컨테이너에 전달하고 재생성합니다. 기존 ENTRYPOINT·CMD로 앱을 시작합니다.

Python

Section titled “Python”

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

  1. 앱 의존성이 설치된 Python 환경에서 Connect의 pip 설치 명령을 실행합니다.
  2. opentelemetry-bootstrap -a install을 실행합니다. 현재 환경에 설치된 라이브러리에 맞는 계측 패키지가 추가됩니다.
  3. 생성된 환경 변수 블록을 적용하고 기존 실행 명령 앞에 opentelemetry-instrument를 붙여 다시 시작합니다.
python app.py로 실행하던 앱의 예시
opentelemetry-instrument python app.py

이 실행 예시는 Linux/macOS와 Windows PowerShell에서 같습니다. python app.py는 실제 앱 시작 명령과 인자로 바꾸고, 환경 변수 블록은 선택한 OS의 형식을 사용하세요. python, opentelemetry-bootstrap, opentelemetry-instrument가 모두 앱과 같은 Python 환경에 있어야 합니다.

Python Docker에 적용

Section titled “Python Docker에 적용”
  1. 기존 Dockerfile에서 앱 의존성을 설치한 다음에 Connect의 RUN 블록을 추가합니다. 멀티 스테이지라면 최종 실행 이미지의 Python 환경에 앱 의존성과 계측 패키지가 함께 포함되어야 합니다.
  2. 실제 앱 시작 명령 앞에 opentelemetry-instrument를 추가합니다. 패키지 설치만으로 시작 명령이 바뀌지는 않습니다.
  3. 이미지를 다시 빌드하고, 생성된 환경 변수 전체를 전달해 앱 컨테이너를 재생성합니다.
기존 CMD가 python app.py인 경우
CMD ["opentelemetry-instrument", "python", "app.py"]

앱을 ENTRYPOINT에서 시작한다면 해당 명령에 계측을 추가합니다. 초기화 스크립트를 사용 중이면 초기화 과정은 유지하고, 스크립트 안에서 실제 앱을 시작하는 명령에 반영하세요.

연결 후 확인

Section titled “연결 후 확인”

애플리케이션을 다시 시작한 뒤 지원되는 HTTP 요청이나 작업을 실행하고, Connect의 데이터 수집 확인을 실행합니다. 필요한 메트릭·로그·트레이스는 각 데이터 조회에서도 확인하세요.

  • 트레이스가 없으면 새 프로세스의 실행 명령에 Agent 또는 자동 계측 옵션이 포함됐는지 확인합니다.
  • Node.js 로그가 없으면 사용하는 로깅 라이브러리가 계측 대상인지, 자동 계측이 해당 라이브러리보다 먼저 로드됐는지 확인합니다.
  • Python 계측 명령을 찾지 못하면 패키지를 설치한 Python 환경과 실행 환경이 같은지 확인합니다.
  • Docker에서는 변경된 패키지·시작 명령이 실행 중인 이미지에 반영되었는지 확인합니다. 환경 변수나 마운트만 바꿨다면 컨테이너를 재생성해 적용합니다.
  • Node.js와 Python의 메트릭은 사용하는 라이브러리와 실제 활동에 따라 보이지 않을 수 있습니다. 먼저 트레이스와 지원 로그로 연결을 확인합니다.

공통 확인 순서는 연결 및 수집 확인을 참고하세요.