ClickStack를 사용한 Systemd 로그 모니터링

TL;DROpenTelemetry Collector의 journald 수신기를 사용해 ClickStack에서 systemd journal 로그를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함됩니다.

기존 시스템 통합

OpenTelemetry Collector를 journald 수신기와 함께 실행해 기존 Linux 시스템의 journald 로그를 수집하고, OTLP를 통해 ClickStack으로 전송하여 모니터링할 수 있습니다. 기존 설정을 변경하지 않고 먼저 이 통합을 테스트하려면 데모 데이터세트 섹션으로 이동하십시오.

사전 요구 사항

실행 중인 ClickStack 인스턴스
systemd를 사용하는 Linux 시스템(Ubuntu 16.04+, CentOS 7+, Debian 8+)
모니터링 대상 시스템에 Docker 또는 Docker Compose가 설치되어 있어야 합니다

ClickStack API Key 가져오기

OpenTelemetry Collector는 ClickStack의 OTLP 엔드포인트로 데이터를 전송하며, 이 엔드포인트에는 인증이 필요합니다.

ClickStack URL(예: http://localhost:8080)에서 HyperDX를 엽니다
필요하면 계정을 생성하거나 로그인합니다
Team Settings → API Keys로 이동합니다
수집 API key를 복사합니다

이를 환경 변수로 설정합니다:

export CLICKSTACK_API_KEY=your-api-key-here

systemd journal 실행 여부 확인

시스템에서 systemd를 사용 중이며 journal 로그가 있는지 확인합니다:

# systemd 버전 확인
systemctl --version

# 최근 journal 항목 보기
journalctl -n 20

# journal 디스크 사용량 확인
journalctl --disk-usage

journal 저장소가 메모리에만 유지되는 경우 영구 저장소를 활성화합니다:

sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal
sudo systemctl restart systemd-journald

OpenTelemetry Collector 구성 생성

OpenTelemetry Collector용 설정 파일을 생성합니다:

cat > otel-config.yaml << 'EOF'
receivers:
  journald:
    directory: /var/log/journal
    priority: info
    units:
      - sshd
      - nginx
      - docker
      - containerd
      - systemd

processors:
  batch:
    timeout: 10s
    send_batch_size: 10000
  
  resource:
    attributes:
      - key: service.name
        value: systemd-logs
        action: insert
      - key: host.name
        from_attribute: _HOSTNAME
        action: upsert
  
  attributes:
    actions:
      - key: unit
        from_attribute: _SYSTEMD_UNIT
        action: upsert
      - key: priority
        from_attribute: PRIORITY
        action: upsert

exporters:
  otlphttp:
    endpoint: ${CLICKSTACK_ENDPOINT}
    headers:
      authorization: ${CLICKSTACK_API_KEY}

service:
  pipelines:
    logs:
      receivers: [journald]
      processors: [resource, attributes, batch]
      exporters: [otlphttp]
EOF

Docker Compose로 배포

journald 수신기는 journal 파일을 읽기 위해 journalctl 바이너리가 필요합니다. 공식 otel/opentelemetry-collector-contrib 이미지에는 기본적으로 journalctl이 포함되어 있지 않습니다.컨테이너 환경에 배포하는 경우, collector를 호스트에 직접 설치하거나 systemd 유틸리티가 포함된 사용자 지정 이미지를 빌드할 수 있습니다. 자세한 내용은 문제 해결 섹션을 참조하십시오.

이 예시는 ClickStack과 함께 OTel Collector를 배포하는 방법을 보여줍니다:

services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring
  
  otel-collector:
    image: otel/opentelemetry-collector-contrib:0.115.1
    depends_on:
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
      - CLICKSTACK_ENDPOINT=http://clickstack:4318
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
      - /var/log/journal:/var/log/journal:ro
      - /run/log/journal:/run/log/journal:ro
      - /etc/machine-id:/etc/machine-id:ro
    command: ["--config=/etc/otelcol/config.yaml"]
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge

서비스를 시작합니다:

docker compose up -d

HyperDX에서 로그 확인

구성이 완료되면 HyperDX에 로그인하여 로그가 수집되는지 확인합니다:

Search view로 이동합니다
source를 Logs로 설정합니다
service.name:systemd-logs로 필터링합니다
unit, priority, MESSAGE, _HOSTNAME 등의 필드가 포함된 구조화된 로그 항목이 표시되어야 합니다

데모 데이터세트

프로덕션 시스템을 구성하기 전에 systemd 로그 통합을 테스트하려는 사용자를 위해, 실제와 유사한 패턴을 포함하는 미리 생성된 systemd 로그 샘플 데이터세트를 제공합니다.

샘플 데이터세트 다운로드

샘플 로그 파일을 다운로드하세요:

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/systemd/systemd-demo.log

데모 collector 구성 생성

데모용 설정 파일을 생성하세요:

cat > systemd-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/systemd-demo/systemd-demo.log
    start_at: beginning
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\S+) (?P<hostname>\S+) (?P<unit>\S+?)(?:\[(?P<pid>\d+)\])?: (?P<message>.*)$'
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.timestamp
        layout: '%Y-%m-%dT%H:%M:%S%z'
      - type: add
        field: attributes.source
        value: "systemd-demo"

service:
  pipelines:
    logs/systemd-demo:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

데모 데이터로 ClickStack 실행

데모 로그와 함께 ClickStack을 시작하세요:

docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/systemd-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/systemd-demo.log:/tmp/systemd-demo/systemd-demo.log:ro" \
  clickhouse/clickstack-all-in-one:latest

이 데모는 컨테이너에서 journalctl이 필요하지 않도록 journald 대신 텍스트 로그와 filelog 수신기를 사용합니다.

HyperDX에서 로그 확인

ClickStack이 실행되면 다음을 수행하세요:

HyperDX를 열고 계정에 로그인합니다
Search view로 이동한 다음 source를 Logs로 설정합니다
시간 범위를 2025-11-14 00:00:00 - 2025-11-17 00:00:00으로 설정합니다

시간대 표시HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC) 기간에 해당합니다. 시간 범위를 넉넉하게 설정했기 때문에 어느 지역에서 접속하더라도 데모 로그를 확인할 수 있습니다.

대시보드 및 시각화

ClickStack으로 systemd 로그 모니터링을 시작할 수 있도록 systemd journal 데이터에 대한 핵심 시각화를 제공합니다.

할 대시보드 구성 파일

사전 구축된 대시보드 가져오기

HyperDX를 열고 Dashboards 섹션으로 이동합니다
오른쪽 상단의 줄임표 메뉴에서 Import Dashboard를 클릭합니다

systemd-logs-dashboard.json 파일을 업로드한 다음 Finish Import를 클릭합니다

대시보드 보기

대시보드에는 다음 시각화가 포함되어 있습니다:

시간에 따른 로그량
로그 수 기준 상위 systemd 유닛
SSH 인증 이벤트
서비스 실패
오류율

데모 데이터세트에서는 시간 범위를 **2025-11-15 00:00:00 - 2025-11-16 00:00:00 (UTC)**로 설정한 뒤, 로컬 시간대에 맞게 조정하십시오.

문제 해결

HyperDX에 로그가 표시되지 않는 경우

로그가 ClickHouse에 수집되고 있는지 확인하세요:

docker exec clickstack clickhouse-client --query "
SELECT COUNT(*) as log_count
FROM otel_logs
WHERE ServiceName = 'systemd-logs'
"

결과가 표시되지 않으면 collector 로그를 확인하세요:

docker logs otel-collector | grep -i "error\|journald" | tail -20

journalctl not found 오류

exec: "journalctl": executable file not found in $PATH가 표시되면 다음과 같이 하십시오: otel/opentelemetry-collector-contrib 이미지에는 journalctl이 포함되어 있지 않습니다. 다음 중 하나를 선택할 수 있습니다:

호스트에 collector를 설치하세요:

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.115.0/otelcol-contrib_0.115.0_linux_amd64.tar.gz
tar -xzf otelcol-contrib_0.115.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/
otelcol-contrib --config=otel-config.yaml

텍스트 내보내기 방식을 사용하세요(데모와 같이). filelog 수신기가 journald 내보내기 데이터를 읽도록 구성합니다

다음 단계

중요한 시스템 이벤트(서비스 장애, 인증 실패, OOM kill)에 대한 알림을 설정하세요
특정 용도(SSH 보안 모니터링, 서비스 상태)에 맞는 추가 대시보드를 만드세요
특정 systemd 유닛으로 필터링하여 노이즈를 줄이고 중요한 서비스에 집중하세요

프로덕션 환경으로 전환하기

이 가이드에서는 systemd 로그를 읽어 ClickStack의 OTLP 엔드포인트로 전송하기 위해 별도의 OpenTelemetry Collector를 사용하며, 이는 프로덕션 환경에서 권장되는 패턴입니다. 여러 호스트가 있는 프로덕션 환경에서는 다음 사항을 고려하세요.

Kubernetes에서 collector를 데몬셋으로 배포
각 호스트에서 collector를 systemd 서비스로 실행
자동 배포를 위해 OpenTelemetry Operator 사용

프로덕션 배포 패턴은 OpenTelemetry로 수집하기를 참조하십시오.

​기존 시스템 통합

사전 요구 사항

​ClickStack API Key 가져오기

​systemd journal 실행 여부 확인

​OpenTelemetry Collector 구성 생성

​Docker Compose로 배포

​HyperDX에서 로그 확인

​데모 데이터세트

​샘플 데이터세트 다운로드

​데모 collector 구성 생성

​데모 데이터로 ClickStack 실행

​HyperDX에서 로그 확인

​대시보드 및 시각화

​할 대시보드 구성 파일

​사전 구축된 대시보드 가져오기

​대시보드 보기

​문제 해결

​HyperDX에 로그가 표시되지 않는 경우

​journalctl not found 오류

​다음 단계

​프로덕션 환경으로 전환하기

기존 시스템 통합

ClickStack API Key 가져오기

systemd journal 실행 여부 확인

OpenTelemetry Collector 구성 생성

Docker Compose로 배포

HyperDX에서 로그 확인

데모 데이터세트

샘플 데이터세트 다운로드

데모 collector 구성 생성

데모 데이터로 ClickStack 실행

HyperDX에서 로그 확인

대시보드 및 시각화

할 대시보드 구성 파일

사전 구축된 대시보드 가져오기

대시보드 보기

문제 해결

HyperDX에 로그가 표시되지 않는 경우

journalctl not found 오류

다음 단계

프로덕션 환경으로 전환하기