Skip to content
Monithub DocsMonithub Docs

인프라 연결

전체 문서 PDF

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

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

Linux는 Collector를 바이너리로, Docker는 컨테이너로 실행하는 방식입니다. 선택한 환경에서 생성된 설정 파일과 실행 명령을 함께 사용하세요. 이미 Collector를 운영하고 있다면 기존 Collector에 추가를 따릅니다.

Linux 호스트

Section titled “Linux 호스트”

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

Linux 바이너리로 실행

Section titled “Linux 바이너리로 실행”
  1. Linux 호스트와 Linux를 선택합니다.
  2. uname -m으로 CPU를 확인하고, 설정 생성 후 x86_64 또는 ARM64 중 해당하는 설치 명령 하나를 실행합니다.
  3. 생성된 YAML을 otelcol-monithub.yaml로 저장하고 Collector를 실행합니다.
Terminal window
otelcol-contrib --config ./otelcol-monithub.yaml

Docker로 실행

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

두 방식 모두 수집할 Linux 서버에서 실행합니다. Docker Desktop의 내부 Linux VM은 macOS·Windows 호스트 자체와 다릅니다.

시스템 로그는 Collector가 시작된 이후 새로 기록되는 내용을 읽습니다. /var/log/syslog, /var/log/messages, /var/log/*.log에 새 로그가 기록되는지와 Collector의 읽기 권한을 확인하세요. journald에만 저장되는 로그는 기본 파일 수집 설정에 포함되지 않습니다.

Docker

Section titled “Docker”

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

Docker 카탈로그에서 실행 환경을 선택하고, Docker Engine이 실행되는 Linux 호스트에 생성된 Collector 설정을 저장합니다.

  • Linux: CPU에 맞는 설치 명령을 실행하고, /var/run/docker.sock에 접근할 수 있는 계정으로 Collector를 시작합니다.
  • Docker: 생성된 명령의 socket 마운트와 --group-add를 함께 사용합니다. 그룹 ID는 수집할 Docker 호스트에서 확인합니다.
Terminal window
docker_socket_gid="$(stat -c '%g' /var/run/docker.sock)"

생성된 명령은 위 그룹 ID를 --group-add에 전달합니다. 권한 오류가 나면 실제 socket 경로와 그룹 권한을 확인하세요. Rootless Docker처럼 socket 위치가 다르면 바이너리 방식은 YAML의 endpoint를, Docker 방식은 마운트할 호스트 경로와 그룹 ID 확인 명령을 실제 위치에 맞춥니다.

Docker socket 접근은 Docker 제어 권한을 부여합니다. 마운트의 :ro는 Docker API를 읽기 전용으로 제한하지 않으므로, 해당 호스트의 socket 접근 정책에 따라 Collector 계정에 권한을 부여하세요.

Collector가 실행되면 기존 실행 중인 컨테이너의 메트릭을 주기적으로 수집합니다. 별도 테스트 컨테이너나 부하는 필요하지 않습니다.

NGINX

Section titled “NGINX”

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

NGINX 카탈로그에서 실행 환경을 선택합니다. 먼저 NGINX의 상태 주소를 준비한 뒤, 생성된 YAML로 Collector를 실행합니다. 이미 stub_status 주소가 있다면 새로 만들지 않고 생성된 YAML의 nginx.endpoint를 그 주소로 변경할 수 있습니다.

Linux에서 적용

Section titled “Linux에서 적용”

NGINX와 Collector를 같은 Linux 호스트에서 실행합니다. Connect가 생성한 monithub-status.conf 전체를 NGINX의 http 블록에서 읽는 include 경로에 저장합니다. 생성되는 상태 주소는 이 호스트에서만 접근할 수 있습니다.

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

NGINX 호스트에서 모듈과 전체 설정을 확인합니다.

Terminal window
nginx -V 2>&1 | grep -- --with-http_stub_status_module
sudo nginx -t

검증에 성공하면 기존 서비스 관리 방식으로 reload합니다. 다음은 NGINX 명령으로 반영하는 예시입니다.

Terminal window
sudo nginx -s reload

반영 후 같은 호스트에서 상태 응답을 확인합니다. Active connections 등 상태 값이 반환되면 생성된 YAML로 Collector를 시작합니다.

Terminal window
curl --fail http://127.0.0.1:18080/status

Docker에서 적용

Section titled “Docker에서 적용”

NGINX와 Collector를 같은 사용자 정의 Docker 네트워크에 둡니다. 생성된 location = /status 조각은 외부에 공개되지 않은 NGINX server 블록에 포함하세요. 이미 공개 중인 웹 서비스의 server 블록에 넣으면 /status도 외부에서 접근할 수 있습니다.

별도 상태 server를 사용한다면 다음처럼 구성하고, 해당 포트를 호스트에 게시하지 않습니다.

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

NGINX 컨테이너에서 nginx -t를 실행하고, 성공하면 같은 컨테이너에서 nginx -s reload를 실행합니다. Docker 호스트에서는 다음처럼 실행할 수 있습니다. nginx는 실제 컨테이너 이름으로 바꾸세요.

Terminal window
docker exec nginx nginx -t

검증에 성공한 뒤 반영합니다.

Terminal window
docker exec nginx nginx -s reload

Collector 설정과 실행 명령도 맞춥니다.

  1. YAML의 기본 주소 http://nginx:80/status를 실제 컨테이너 이름 또는 네트워크 별칭과 상태 포트로 변경합니다. 위 예시라면 http://nginx:18080/status입니다.
  2. 같은 네트워크에서 상태 URL을 요청해 Active connections 등 상태 값이 반환되는지 확인합니다. Collector 이미지에 셸이나 curl이 없다면 해당 네트워크의 진단용 컨테이너를 사용합니다.
  3. 실행 명령의 {REPLACE_WITH_PRIVATE_NETWORK}를 해당 네트워크 이름으로 바꾸고 Collector를 시작합니다.

Connect는 NGINX 설정을 직접 수정하거나 reload하지 않습니다. 설정 검증에 실패했다면 오류를 수정한 뒤 다시 검증하세요.

연결 후 확인

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

메트릭은 주기적으로 수집됩니다. Collector를 실행한 뒤 데이터 수집 확인에서 결과를 확인하세요. 상태의 의미와 계속 수집하기 위한 운영 방법은 연결 및 수집 확인에서 안내합니다.