인프라 연결

인프라 카탈로그는 서버, 컨테이너 런타임과 NGINX의 상태를 Collector로 수집합니다. 설치 대상은 수집 대상이 아니라 Collector를 실제로 실행할 방식입니다.

카탈로그	수집 데이터	Collector 실행 위치
Linux 호스트	CPU·메모리·디스크·파일시스템·네트워크 메트릭, 시스템 로그	수집할 Linux 서버
Docker	컨테이너 런타임 메트릭	Docker Engine이 실행되는 Linux 호스트
NGINX	`stub_status` 연결·요청 메트릭	NGINX 상태 주소에 접근할 수 있는 Linux 호스트 또는 컨테이너

Linux 방식은 대상 Linux 호스트에 Collector 바이너리를 설치합니다. Docker 방식은 대상과 가까운 곳에서 전용 Collector 컨테이너를 실행합니다. 생성된 설정 파일과 실행 명령은 선택한 방식을 섞지 말고 같은 열의 안내를 따르세요.

Linux 호스트

Linux 호스트는 Collector가 실행되는 서버 자체의 호스트 메트릭과 표준 시스템 로그를 수집합니다. 다른 서버를 대신 수집하는 방식이 아니므로 대상 Linux 서버에서 실행해야 합니다.

Linux 바이너리로 실행

Linux 호스트와 Linux를 선택합니다.
설정 생성 후 대상 서버 CPU에 맞는 x86_64 또는 ARM64 설치 명령을 실행합니다.
생성된 YAML을 otelcol-monithub.yaml로 저장하고 Collector를 실행합니다.

uname -m
otelcol-contrib --config ./otelcol-monithub.yaml

Docker로 실행

Linux 호스트와 Docker를 선택합니다.
생성된 YAML을 대상 Linux 서버에 저장합니다.
Connect가 생성한 명령으로 호스트 파일시스템을 /hostfs에 읽기 전용으로 마운트해 Collector를 실행합니다.

docker run --rm --read-only \
  -v /:/hostfs:ro \
  -v "$PWD/otelcol-monithub.yaml:/etc/otelcol-contrib/config.yaml:ro" \
  <Connect가 표시한 Collector 이미지> --config /etc/otelcol-contrib/config.yaml

시스템 로그는 Collector가 시작된 이후 새로 기록되는 내용을 읽습니다. 실행했는데 로그가 보이지 않으면 /var/log/syslog, /var/log/messages, /var/log/*.log 중 실제 서버에서 사용하는 파일에 새 로그가 기록되는지와 Collector의 읽기 권한을 확인하세요.

YAML을 복사하고 저장하는 전체 화면 흐름은 Connect 시작하기의 Linux 호스트 예시를 참고하세요.

Docker

Docker 카탈로그는 Docker Engine에서 실행 중인 컨테이너의 CPU, 메모리, 네트워크, 블록 I/O와 상태 메트릭을 수집합니다. 컨테이너 애플리케이션 로그는 이 카탈로그의 수집 범위가 아닙니다.

Docker를 선택합니다.
Docker Engine이 실행되는 Linux 호스트에서 Collector를 바이너리로 실행할지 컨테이너로 실행할지 선택합니다.
수집 대상 이름과 운영 환경을 입력하고 설정 생성을 누릅니다.

Linux 바이너리 방식은 Collector 프로세스가 /var/run/docker.sock에 접근할 수 있어야 합니다. Docker 방식은 Connect가 생성한 명령이 socket을 읽기 전용으로 마운트하고 호스트 socket의 그룹 ID를 Collector에 추가합니다.

docker_socket_gid="$(stat -c '%g' /var/run/docker.sock)"
docker run --group-add "$docker_socket_gid" \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  <Connect가 표시한 나머지 실행 옵션>

Collector 실행 후 테스트 컨테이너를 시작하거나 기존 컨테이너에 부하를 발생시킨 뒤 수집을 확인합니다. 권한 오류가 표시되면 socket의 그룹 ID와 실행 명령의 --group-add 값이 같은지 확인하세요.

OpenTelemetry Docker Stats Receiver

NGINX

NGINX 카탈로그는 NGINX OSS의 stub_status가 제공하는 연결 수와 누적 요청 수를 수집합니다. access/error 로그, 응답 시간, 상태 코드, upstream 정보는 수집하지 않습니다.

NGINX를 선택합니다.
NGINX 옆에서 Collector를 Linux 바이너리 또는 Docker 컨테이너로 실행할지 선택합니다.
수집 대상 이름과 운영 환경을 입력하고 설정 생성을 누릅니다.

Linux에서 적용

Connect가 생성한 monithub-status.conf 전체를 기존 NGINX 설정의 include 경로에 저장합니다. 짧은 형태는 다음과 같습니다.

server {
    listen 127.0.0.1:18080;
    location = /status { stub_status; }
}

다음 순서로 모듈, 전체 설정, 상태 응답을 확인한 뒤 기존 서비스 관리 방식으로 NGINX를 reload합니다.

nginx -V 2>&1 | grep http_stub_status_module
nginx -t
curl --fail http://127.0.0.1:18080/status

Docker에서 적용

Connect가 생성한 location = /status 조각을 기존 NGINX server 블록에 포함합니다. NGINX와 Collector를 같은 비공개 Docker network에 두고 상태 포트는 호스트에 공개하지 않습니다.

Collector 설정의 기본 주소는 http://nginx:80/status입니다. Compose 서비스 이름이 nginx가 아니라면 생성된 YAML의 hostname을 실제 서비스 이름으로 바꾸고, 그 network 안에서 상태 응답을 확인하세요.

Connect는 NGINX 설정을 직접 수정하거나 reload하지 않습니다. nginx -t가 실패하면 새 조각을 적용하지 말고 기존 설정을 유지하세요.

연결 후 확인

증상	확인할 내용
Collector가 시작되지 않음	선택한 OS·CPU와 설치 파일이 맞는지, YAML 전체를 저장했는지 확인합니다.
Linux 호스트 로그만 없음	새 로그가 기록되는 파일 경로와 Collector의 파일 읽기 권한을 확인합니다.
Docker 메트릭이 없음	Docker socket mount와 socket 그룹 권한을 확인합니다.
NGINX 메트릭이 없음	`stub_status` 모듈, `nginx -t`, 상태 URL 응답과 Docker network hostname을 확인합니다.

대상에서 실제 활동을 발생시킨 뒤 데이터 수집 확인을 다시 누르세요. 상태의 의미와 재시도 방법은 연결 및 수집 확인에서 안내합니다.