기존 설정에 적용

기존 수집 설정에 추가는 운영 중인 OpenTelemetry Collector에 새 수집 대상을 연결하는 방식입니다. Connect에서 생성한 YAML 조각을 현재 설정에 병합하고, 같은 Collector를 재시작해 적용합니다.

기존 수집을 유지하려면 현재 설정을 백업한 뒤 설정 조각 생성 → 이름 변경 → 병합 → 전체 설정 검증 → 재시작 → 기존·신규 수집 확인 순서로 진행하세요. Connect는 현재 파일을 읽거나 자동으로 병합·재시작하지 않습니다.

지원 범위

카탈로그	추가되는 내용	먼저 확인할 것
Linux 호스트	호스트 메트릭·시스템 로그 수집 설정	같은 Linux 호스트에서 실행하며 로그 파일에 접근 가능
Docker	Docker 메트릭 수집 설정	대상 Linux 호스트의 Docker socket에 접근 가능
PostgreSQL·MySQL·Redis	데이터베이스 메트릭 수집 설정과 환경 변수	연결 주소, 모니터링 계정과 필요한 인증서 준비
NGINX	NGINX 메트릭 수집 설정과 환경 변수, 필요 시 stub_status 설정	Collector에서 상태 확인 주소에 접근 가능

각 조각에는 Monithub 연결을 식별하는 processor, 전송용 exporter와 별도의 pipeline이 포함됩니다. 기존 receiver가 같은 대상을 이미 수집하고 있다면 먼저 중복 수집 여부를 확인하세요. 이 방식은 기존 receiver를 찾아 재사용하는 기능이 아닙니다.

Java, Node.js, Python, Custom OTLP, Kubernetes는 이 방식을 제공하지 않습니다. 애플리케이션은 해당 카탈로그에서 새 Connect를 만들거나 여러 소스의 데이터를 모으는 Custom OTLP를 사용하세요.

1. 현재 구성 백업

1. 실행 중인 Collector의 버전, 설정 파일 경로와 시작 명령을 확인합니다. 설정을 여러 파일로 나눴다면 모두 확인합니다.
2. 설정 파일과 서비스·Compose 정의, 환경 변수 전달 방식과 마운트 경로를 함께 백업합니다.
3. 기존 수집 대상에서 최근 데이터가 들어오는지 확인합니다. 적용 후에도 같은 대상으로 수집이 유지되는지 비교합니다.
4. 기존 receiver, processor, exporter와 pipeline 이름을 확인합니다. 특히 memory_limiter와 batch를 사용 중이면 실제 이름을 기록합니다.

아래 경로는 예시입니다. 현재 서비스가 사용하는 실행 파일과 설정 경로로 바꿔 실행하세요.

Linux와 macOS

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

Windows

./otelcol-contrib.exe --version
Copy-Item ./otelcol-monithub.yaml ./otelcol-monithub.yaml.backup

Docker

현재 이미지의 버전 태그, 설정·인증서 마운트, 환경 변수, 네트워크와 실행 사용자 설정을 Compose 파일 또는 기존 실행 명령과 함께 보관합니다.

생성 설정은 OpenTelemetry Collector Contrib 0.158.0을 기준으로 합니다. 현재 배포판과 버전이 생성된 receiver·processor·exporter를 지원하는지 확인하세요. Connect는 기존 Collector를 업그레이드하지 않습니다.

2. Connect에서 설정 조각 생성

1. 지원 카탈로그와 현재 Collector의 실행 환경을 선택합니다. 예를 들어 DB는 Linux에서 실행하더라도 Collector가 컨테이너라면 Docker를 선택합니다.
2. 연결 정보와 카탈로그별 필수 항목을 입력하고 설정 생성을 누릅니다.
3. 설치 · 설정 적용 단계에서 기존 수집 설정에 추가를 선택합니다.
4. 설치 · 설정 적용에서 Collector YAML 조각과, 제공되는 경우 환경 변수·NGINX 설정을 복사합니다.

이 흐름에는 Collector 설치나 실행 명령이 표시되지 않습니다. 기존 설정에 직접 병합한 뒤 현재 운영 방식으로 검증하고 재시작해야 합니다.

초안을 계속 설정으로 다시 열었다면 적용 방식이 기존 수집 설정에 추가인지 확인하고, 필요하면 다시 선택하세요.

생성된 설정에는 전송 인증 정보가 포함됩니다. 현재 사용 중인 비밀정보 관리 방식으로 보관하세요.

3. 고유 이름 바꾸기

생성된 조각의 다음 플레이스홀더는 병합 전에 실제 값으로 바꿔야 합니다.

플레이스홀더	바꿀 값
{REPLACE_WITH_UNIQUE_NAME}	현재 Collector 안에서 겹치지 않는 receiver·processor·exporter·pipeline의 이름 부분
REPLACE_WITH_UNIQUE_ENV_PREFIX	다른 연결의 환경 변수와 겹치지 않는 영문 대문자 접두어

{REPLACE_WITH_UNIQUE_NAME} → checkout_db
REPLACE_WITH_UNIQUE_ENV_PREFIX → CHECKOUT

같은 조각 안의 해당 플레이스홀더를 모두 바꾸되, postgresql/, resource/, otlp_http/, metrics/ 같은 유형은 유지합니다. 다른 연결에는 다른 이름과 접두어를 사용합니다.

예를 들어 postgresql/{REPLACE_WITH_UNIQUE_NAME}은 postgresql/checkout_db, ${env:REPLACE_WITH_UNIQUE_ENV_PREFIX_POSTGRESQL_ENDPOINT}는 ${env:CHECKOUT_POSTGRESQL_ENDPOINT}가 됩니다. 환경 변수 블록의 이름도 똑같이 바꿉니다. 환경 변수 블록이 없는 카탈로그는 접두어를 지정할 필요가 없습니다.

4. 카탈로그별 사전 조건

Linux 호스트

• Collector가 수집 대상과 같은 Linux 호스트에서 실행되는지 확인합니다.
• Collector 실행 계정이 생성된 설정의 로그 경로를 읽을 수 있어야 합니다. 실제 파일 위치가 다르면 include 경로를 조정합니다.
• Docker Collector는 호스트 루트를 /hostfs에 읽기 전용으로 마운트합니다. 이미 다른 경로로 마운트했다면 생성된 root_path, filelog의 include 경로와 regex_parser의 ^/hostfs 접두어를 모두 그 경로에 맞춥니다.

-v /:/hostfs:ro

Docker

• Collector 실행 계정이 대상 호스트의 /var/run/docker.sock에 접근할 수 있어야 합니다.
• Docker Collector는 socket을 읽기 전용으로 마운트하고, 기존에 접근 권한이 없다면 호스트 socket의 GID를 보조 그룹에 추가합니다. GID 확인 방법은 Docker 연결을 참고하세요.

-v /var/run/docker.sock:/var/run/docker.sock:ro
--group-add <docker-socket-gid>

PostgreSQL, MySQL과 Redis

• Collector에서 접근 가능한 데이터베이스 주소를 사용합니다. 별도 컨테이너의 DB에 연결할 때 localhost는 DB가 아니라 Collector 컨테이너 자신을 가리킵니다.
• 모니터링 계정과 카탈로그별 최소 권한은 데이터베이스 연결에서 확인합니다.
• Connect가 생성한 환경 변수 이름을 고유 접두어로 바꾼 뒤 같은 Collector 실행 환경에 추가합니다.
• TLS 또는 mTLS에서는 인증서 파일을 Collector가 읽을 수 있는 경로에 두고 생성된 환경 변수와 일치시킵니다.
• Docker Collector는 환경 변수와 인증서 마운트를 기존 서비스 정의에 추가합니다. DB 컨테이너 이름으로 연결한다면 같은 Docker 네트워크에도 참여해야 합니다. 컨테이너 안의 인증서 경로와 환경 변수 값이 일치하는지 확인합니다.
• 생성된 인증서 경로(/certs/ca.crt, /certs/client.crt, /certs/client.key)를 기존 연결이 다른 인증서로 사용 중이라면 덮어쓰지 않습니다. 새 연결에는 /certs/session-cache/ca.crt처럼 별도 경로로 마운트하고, 해당 연결의 인증서 환경 변수도 같은 경로로 바꿉니다. 실제로 같은 CA 또는 클라이언트 인증서를 사용하는 연결만 기존 파일을 공유합니다.

NGINX

• 기존 stub_status 주소가 있으면 재사용하고, 생성된 …_NGINX_ENDPOINT 환경 변수에 넣습니다.
• 없다면 NGINX가 실행되는 환경에 status 설정을 추가합니다. nginx -t로 검증한 뒤 reload하고, Collector가 접근하는 경로에서 상태 응답을 확인합니다.
• Docker에서 NGINX 컨테이너 이름으로 연결한다면 같은 비공개 네트워크에 참여합니다. {REPLACE_WITH_PRIVATE_NETWORK}를 실제 네트워크 이름으로 바꾸고, 공개 주소로 status 경로를 노출하지 않습니다. 새 status 주소가 필요하다면 NGINX Docker 적용의 비공개 server 블록 예시를 따릅니다.

5. 기존 YAML에 병합

생성된 조각을 파일 맨 아래에 통째로 붙이지 말고, 각 항목을 기존의 같은 키 아래에 추가합니다. 기존 설정이 여러 파일로 관리된다면 현재의 파일 분리 방식을 따릅니다.

생성된 항목	병합 위치
receivers의 하위 항목	기존 receivers 아래
processors의 하위 항목	기존 processors 아래
exporters의 하위 항목	기존 exporters 아래
service.pipelines의 하위 항목	기존 service → pipelines 아래

새 pipeline에는 생성된 receiver·processor·exporter 이름을 그대로 연결합니다. 기존 pipeline에 Monithub용 resource processor를 넣으면 기존 데이터의 연결 식별값까지 바뀔 수 있으므로, 생성된 별도 pipeline에 적용하세요.

기존 memory_limiter와 batch를 사용 중이면 새 pipeline에서도 실제 이름을 참조해 각각 처음과 마지막에 배치합니다. 기존 정의가 없다면 이름만 추가하지 않습니다. Linux 호스트의 resourcedetection 등 생성된 다른 processor도 순서를 유지합니다.

PostgreSQL 추가 시 병합 구조 예시

아래는 기존 metrics/existing을 유지하면서 metrics/checkout_db를 추가한 예시입니다. 실제 적용할 때는 기존 구성과 Connect에서 생성된 전체 receiver 설정·식별값·인증 헤더를 사용하세요. 이 예시는 구조 설명을 위해 receiver 옵션을 줄였으며 인증값은 자리표시자로 표시했습니다.

receivers:
  otlp/existing:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317
  postgresql/checkout_db:
    endpoint: ${env:CHECKOUT_POSTGRESQL_ENDPOINT}
    username: ${env:CHECKOUT_POSTGRESQL_USERNAME}
    password: ${env:CHECKOUT_POSTGRESQL_PASSWORD}
    databases: ["${env:CHECKOUT_POSTGRESQL_DATABASE}"]

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  batch: {}
  resource/checkout_db:
    attributes:
      - key: monithub.organization_id
        value: "<생성된 조직 ID>"
        action: upsert
      - key: monithub.connect_id
        value: "<생성된 연결 ID>"
        action: upsert

exporters:
  debug/existing: {}
  otlp_http/checkout_db:
    endpoint: https://otel.monithub.org
    headers:
      authorization: "Bearer <생성된 인증값>"
      x-monithub-user-id: "<생성된 사용자 ID>"
      x-monithub-organization-id: "<생성된 조직 ID>"
      x-monithub-connect-id: "<생성된 연결 ID>"

service:
  pipelines:
    metrics/existing:
      receivers: [otlp/existing]
      processors: [memory_limiter, batch]
      exporters: [debug/existing]
    metrics/checkout_db:
      receivers: [postgresql/checkout_db]
      processors: [memory_limiter, resource/checkout_db, batch]
      exporters: [otlp_http/checkout_db]

환경 변수는 Collector를 실행하는 서비스에 추가합니다. 터미널에서 export나 $env:로 설정해도 별도로 관리되는 서비스의 환경 변수가 바뀌지는 않습니다. Linux 서비스, Windows 서비스 또는 컨테이너의 기존 환경 변수 전달 방식을 사용하세요.

6. 검증하고 반영

현재 Collector를 실행한 채로, 병합한 전체 설정을 같은 버전의 실행 파일이나 이미지로 검증합니다. 검증 명령에도 실제 실행에 필요한 환경 변수·설정 파일·인증서 경로를 전달해야 합니다. 여러 --config나 기능 플래그를 사용한다면 검증할 때도 동일하게 지정합니다.

Linux와 macOS

검증할 터미널에 새로 추가한 값과 기존 설정이 참조하는 환경 변수를 모두 설정한 뒤 실행합니다. 설정·인증서 파일은 실제 Collector 실행 계정에서도 읽을 수 있어야 합니다.

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

Windows

검증할 PowerShell 세션에 필요한 $env:... 값을 설정한 뒤 실행합니다. 서비스로 운영 중이라면 검증 후 서비스의 환경 변수 설정에도 같은 값을 반영합니다.

./otelcol-contrib.exe validate --config ./otelcol-monithub.yaml

Docker

Compose를 사용한다면 수정한 서비스 정의로 일회성 검증 컨테이너를 실행할 수 있습니다. collector와 설정 경로를 현재 서비스에 맞게 바꿉니다. 이 명령은 Collector 실행 파일을 기본 ENTRYPOINT로 사용하는 이미지 기준입니다.

docker compose run --rm --no-deps collector \
  validate --config /etc/otelcol-contrib/config.yaml

docker run으로 운영한다면 기존 이미지와 --env-file, 마운트, 네트워크, 실행 사용자 옵션을 유지하고, 마지막 Collector 실행 인수를 validate --config ...로 바꿔 별도 검증 컨테이너를 실행합니다. YAML만 마운트하면 환경 변수와 인증서 경로가 실제 실행 조건과 달라집니다.

검증 성공은 설정을 읽을 수 있다는 뜻이며, DB 접속이나 Monithub 전송 성공까지 보장하지는 않습니다. 다음 순서로 적용합니다.

1. 검증이 성공한 전체 설정과 실행 환경을 현재 서비스에 반영합니다.
2. 기존 운영 방식으로 Collector를 재시작합니다. Docker의 환경 변수·마운트·네트워크를 바꿨다면 단순 재시작 대신 수정한 정의로 같은 서비스를 다시 생성합니다.
3. 시작 로그에서 구성 요소, 파일 권한, 연결 주소와 인증 오류를 확인합니다.
4. 시작에 실패하거나 기존 수집이 멈췄다면 백업한 설정과 서비스 정의로 복구하고 다시 시작합니다. 복구 후 기존 데이터가 들어오는지 확인합니다.

7. 데이터 수집 확인

1. 변경 전에 확인한 기존 수집 대상에서 최근 데이터가 계속 들어오는지 확인합니다.
2. 새 대상의 메트릭 수집 주기를 기다립니다. 시스템 로그는 설정된 파일에 새 로그가 기록되어야 수집됩니다.
3. Connect의 데이터 수집 확인 단계에서 수집 여부를 확인합니다.
4. 연결 목록과 해당 데이터 조회에서 새 연결의 최근 데이터를 확인합니다.

증상	확인할 내용
mapping key ... already defined	최상위 YAML 키를 중복으로 추가하지 않았는지 확인합니다.
unknown type	현재 배포판과 버전이 생성된 receiver·processor·exporter 유형을 지원하는지 확인합니다.
구성 요소 이름·참조 오류	유형/이름 형식을 유지했는지, pipeline에서 참조하는 이름이 실제 정의와 일치하는지 확인합니다.
환경 변수를 찾지 못함	바꾼 접두어와 YAML의 ${env:...} 참조가 일치하는지, 검증·실행 프로세스 모두에 값이 전달됐는지 확인합니다.
데이터가 없음	파일·host root·Docker socket·데이터베이스 권한·NGINX status 접근과 pipeline 참조를 확인합니다.
Monithub 전송에서 401 또는 403	해당 연결에서 생성된 exporter의 인증 헤더와 조직·연결 식별값을 모두 반영했는지 확인합니다.
새 연결은 수집되지만 기존 수집이 멈춤	기존 pipeline·exporter 참조와 실행 환경 변경을 확인합니다. 정상화가 어렵다면 백업한 구성으로 복구합니다.

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

설정 제거

1. 제거 전 현재 설정과 서비스 정의를 백업합니다.
2. 이 연결에 추가한 pipeline을 제거합니다. Linux 호스트는 메트릭·로그 pipeline을 모두 확인합니다.
3. 다른 pipeline에서 참조하지 않는 이 연결의 receiver·processor·exporter를 제거합니다. 공용 memory_limiter, batch, exporter와 다른 연결의 설정은 유지합니다.
4. 이 연결에만 사용한 환경 변수·인증서·마운트·네트워크 설정을 제거합니다. 다른 수집 대상이 함께 사용한다면 남겨 둡니다.
5. 전체 설정을 검증하고 같은 서비스를 재시작하거나 다시 생성합니다. 기존 대상의 수집은 유지되고 제거한 대상에는 새 데이터가 들어오지 않는지 확인합니다.
6. 필요한 경우 Connect에서 연결 또는 설정 초안을 삭제합니다. UI에서 삭제하는 것만으로 실행 중인 Collector 설정이 제거되지는 않습니다.