Skip to content
Monithub DocsMonithub Docs

기존 설정에 적용

전체 문서 PDF

기존 설정 수정은 새 Collector나 Java Agent를 추가하지 않고 현재 실행 중인 구성에 Connect 설정만 병합하는 방식입니다. Monithub는 사용자 환경을 자동으로 수정하지 않으므로 백업, 병합, 검증과 재시작은 기존 배포 절차로 진행합니다.

지원 범위

Section titled “지원 범위”
카탈로그 기존 설정에 추가하는 내용 먼저 확인할 것
Custom OTLP Connect 전용 receiver와 메트릭·로그·트레이스 pipeline 전용 OTLP 포트와 기존 포트가 충돌하지 않는지 확인
Linux 호스트 hostmetrics·filelog receiver와 pipeline Collector가 같은 호스트에서 로그 파일을 읽을 수 있는지 확인
Docker docker_stats receiver와 메트릭 pipeline Collector가 Docker socket에 접근할 수 있는지 확인
Java 애플리케이션 기존 Java Agent의 OTLP 환경 변수 기존 Agent와 애플리케이션 시작 명령을 유지할 수 있는지 확인

Node.js, Python, NGINX, 데이터베이스와 Kubernetes 카탈로그는 이 방식을 제공하지 않습니다. 해당 카탈로그 문서의 새 설정 적용 절차를 사용하세요.

1. 현재 구성 백업

Section titled “1. 현재 구성 백업”

Collector 설정 파일, 서비스 정의, Compose 파일 또는 애플리케이션 배포 설정을 먼저 백업합니다. 실행 중인 Collector가 otelcol-contrib인지도 확인하세요.

Terminal window
otelcol-contrib --version
cp /etc/otelcol-contrib/config.yaml /etc/otelcol-contrib/config.yaml.backup

경로와 백업 방식은 실제 배포 환경에 맞게 변경합니다. 다른 호스트나 Docker Engine의 데이터는 기존 Collector가 자동으로 읽을 수 없으므로 수집 대상과 같은 환경의 구성을 수정해야 합니다.

2. Connect 설정 복사

Section titled “2. Connect 설정 복사”
  1. 지원 카탈로그와 실행 환경을 선택하고 설정 생성을 누릅니다.
  2. 설정 결과의 설정 적용 방식에서 기존 설정 수정을 선택합니다.
  3. 표시된 Connect ID와 설정 조각 전체를 복사합니다.
  4. 카탈로그별 접근 조건 경고를 확인합니다.

3. 기존 구성에 병합

Section titled “3. 기존 구성에 병합”

Collector YAML은 receivers, processors, exporters, service를 파일 아래에 다시 만들지 말고 기존 최상위 키 아래에 생성된 하위 항목을 추가합니다.

receivers:
  existing_receiver: { ... }
  generated_receiver: { ... }
service:
  pipelines:
    generated_pipeline: { ... }
  • 기존 receiver, processor, exporter와 pipeline을 삭제하거나 교체하지 않습니다.
  • 생성된 컴포넌트 이름과 Connect ID를 바꾸거나 다른 연결과 공유하지 않습니다.
  • Custom OTLP 포트를 변경한다면 송신 애플리케이션의 endpoint도 같은 값으로 변경합니다.
  • 컨테이너 Collector는 화면에서 안내한 host root 또는 Docker socket mount를 기존 배포 정의에 추가합니다.

Java 애플리케이션은 Collector YAML 대신 표시된 OTLP 환경 변수를 기존 서비스, Compose 또는 배포 설정에 병합합니다. 기존 service.name과 다른 resource attribute는 유지하세요.

4. 검증하고 반영

Section titled “4. 검증하고 반영”

실제 운영에서 사용하는 Collector로 병합한 전체 파일을 검증합니다.

Terminal window
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

검증이 성공하면 현재 관리 방식으로 Collector 또는 Java 애플리케이션을 재시작하거나 다시 배포합니다.

실행 방식 반영 후 확인
systemd 서비스 상태와 journal 로그
Docker Compose 다시 생성된 컨테이너 상태와 Compose 로그
직접 실행 Collector 표준 출력의 설정·export 오류
Java 서비스 Java Agent 시작과 OTLP export 오류

검증이나 재시작에 실패하면 백업한 설정으로 복구한 뒤 오류를 확인하세요.

5. 데이터 수집 확인

Section titled “5. 데이터 수집 확인”
  1. Collector 또는 애플리케이션 로그에 설정, 권한, 포트 충돌과 인증 오류가 없는지 확인합니다.
  2. Custom OTLP와 Java는 실제 요청을 발생시키고, Linux와 Docker는 한 번 이상의 수집 주기를 기다립니다.
  3. Connect의 데이터 수집 확인에서 예상 신호가 들어오는지 확인합니다.
  4. 연결 목록에서 마지막 수집 시각을 확인합니다.
증상 확인할 내용
mapping key ... already defined 최상위 YAML 키를 중복으로 추가하지 않았는지 확인합니다.
unknown type 실제 실행 파일이 otelcol-contrib이고 생성된 receiver를 지원하는 버전인지 확인합니다.
address already in use Custom OTLP receiver와 애플리케이션 endpoint의 포트를 함께 변경합니다.
데이터가 없음 파일·host root·Docker socket 권한과 pipeline의 Connect ID를 확인합니다.
401 또는 403 Connect에서 최신 설정을 다시 생성해 인증 정보를 교체합니다.

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