메인 콘텐츠로 건너뛰기
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가 설치되어 있어야 합니다
1

​
ClickStack API Key 가져오기

OpenTelemetry Collector는 ClickStack의 OTLP 엔드포인트로 데이터를 전송하며, 이 엔드포인트에는 인증이 필요합니다.
  1. ClickStack URL(예: http://localhost:8080)에서 HyperDX를 엽니다
  2. 필요하면 계정을 생성하거나 로그인합니다
  3. Team Settings → API Keys로 이동합니다
  4. 수집 API key를 복사합니다
  1. 이를 환경 변수로 설정합니다:
export CLICKSTACK_API_KEY=your-api-key-here
2

​
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
3

​
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
4

​
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
5

​
HyperDX에서 로그 확인

구성이 완료되면 HyperDX에 로그인하여 로그가 수집되는지 확인합니다:
  1. Search view로 이동합니다
  2. source를 Logs로 설정합니다
  3. service.name:systemd-logs로 필터링합니다
  4. unit, priority, MESSAGE, _HOSTNAME 등의 필드가 포함된 구조화된 로그 항목이 표시되어야 합니다

​
데모 데이터세트

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

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

샘플 로그 파일을 다운로드하세요:
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/systemd/systemd-demo.log
2

​
데모 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
3

​
데모 데이터로 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 수신기를 사용합니다.
4

​
HyperDX에서 로그 확인

ClickStack이 실행되면 다음을 수행하세요:
  1. HyperDX를 열고 계정에 로그인합니다
  2. Search view로 이동한 다음 source를 Logs로 설정합니다
  3. 시간 범위를 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 데이터에 대한 핵심 시각화를 제공합니다.
1

​
할 대시보드 구성 파일

2

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

  1. HyperDX를 열고 Dashboards 섹션으로 이동합니다
  2. 오른쪽 상단의 줄임표 메뉴에서 Import Dashboard를 클릭합니다
  1. systemd-logs-dashboard.json 파일을 업로드한 다음 Finish Import를 클릭합니다
3

​
대시보드 보기

대시보드에는 다음 시각화가 포함되어 있습니다:
  • 시간에 따른 로그량
  • 로그 수 기준 상위 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이 포함되어 있지 않습니다. 다음 중 하나를 선택할 수 있습니다:
  1. 호스트에 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
  1. 텍스트 내보내기 방식을 사용하세요(데모와 같이). filelog 수신기가 journald 내보내기 데이터를 읽도록 구성합니다

​
다음 단계

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

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

이 가이드에서는 systemd 로그를 읽어 ClickStack의 OTLP 엔드포인트로 전송하기 위해 별도의 OpenTelemetry Collector를 사용하며, 이는 프로덕션 환경에서 권장되는 패턴입니다. 여러 호스트가 있는 프로덕션 환경에서는 다음 사항을 고려하세요.
  • Kubernetes에서 collector를 데몬셋으로 배포
  • 각 호스트에서 collector를 systemd 서비스로 실행
  • 자동 배포를 위해 OpenTelemetry Operator 사용
프로덕션 배포 패턴은 OpenTelemetry로 수집하기를 참조하십시오.
마지막 수정일 2026년 6월 10일