ClickStack를 사용한 EC2 호스트 로그 모니터링

기존 EC2 인스턴스와의 통합

이 섹션에서는 시스템 로그를 수집하고 EC2 메타데이터를 자동으로 보강해 ClickStack으로 전송할 수 있도록 EC2 인스턴스에 OpenTelemetry Collector를 설치하는 방법을 설명합니다. 이 분산 아키텍처는 프로덕션 환경에 적합하며 여러 인스턴스로 확장할 수 있습니다.

프로덕션 인스턴스를 구성하기 전에 EC2 호스트 로그 통합을 테스트하려면 "데모 데이터셋" 섹션의 사전 구성된 설정과 샘플 데이터를 사용하면 됩니다.

사전 요구 사항

실행 중인 ClickStack 인스턴스(온프레미스, 클라우드 또는 로컬 환경)
실행 중인 EC2 인스턴스(Ubuntu, Amazon Linux 또는 기타 Linux 배포판)
EC2 인스턴스에서 ClickStack의 OTLP 엔드포인트로의 네트워크 연결(HTTP는 포트 4318, gRPC는 포트 4317)
EC2 인스턴스 메타데이터 서비스에 접근 가능(기본적으로 활성화됨)

EC2 메타데이터에 액세스할 수 있는지 확인

EC2 인스턴스에서 메타데이터 서비스에 액세스할 수 있는지 확인합니다:

# Get metadata token (IMDSv2)
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# Verify instance metadata
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/placement/region
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-type

인스턴스 ID, 리전, 인스턴스 유형이 표시되어야 합니다. 이 명령이 실패하면 다음 사항을 확인하십시오:

인스턴스 메타데이터 서비스가 활성화되어 있는지
IMDSv2가 보안 그룹 또는 네트워크 ACL에 의해 차단되지 않았는지
이 명령을 EC2 인스턴스 자체에서 실행하고 있는지

syslog 파일이 있는지 확인

EC2 인스턴스에 syslog 파일이 기록되고 있는지 확인합니다:

# Ubuntu instances
ls -la /var/log/syslog

# Amazon Linux / RHEL instances
ls -la /var/log/messages

# View recent entries
tail -20 /var/log/syslog
# or
tail -20 /var/log/messages

OpenTelemetry Collector 설치

EC2 인스턴스에 OpenTelemetry Collector Contrib 배포판을 설치하세요:

# Download the latest release
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# Extract and install
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# Verify installation
otelcol-contrib --version

Collector 구성 만들기

/etc/otelcol-contrib/config.yaml에 OpenTelemetry Collector용 설정 파일을 생성하세요:

sudo mkdir -p /etc/otelcol-contrib

Linux 배포판에 맞는 구성을 선택하십시오:

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /var/log/syslog
      - /var/log/**/*.log
    start_at: end
    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_type: gotime
        layout: '2006-01-02T15:04:05.999999-07:00'
      
      - type: add
        field: attributes.source
        value: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

sudo tee /etc/otelcol-contrib/config.yaml > /dev/null << 'EOF'
receivers:
  filelog/syslog:
    include:
      - /var/log/messages
      - /var/log/**/*.log
    start_at: end
    operators:
      - type: regex_parser
        regex: '^(?P<timestamp>\w+ \d+ \d{2}:\d{2}:\d{2}) (?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: '%b %d %H:%M:%S'
      
      - type: add
        field: attributes.source
        value: "ec2-host-logs"

processors:
  resourcedetection:
    detectors: [ec2, system]
    timeout: 5s
    override: false
    ec2:
      tags:
        - ^Name
        - ^Environment
        - ^Team
  
  batch:
    timeout: 10s
    send_batch_size: 10000

exporters:
  otlphttp:
    endpoint: "http://YOUR_CLICKSTACK_HOST:4318"
    headers:
      authorization: "${env:CLICKSTACK_API_KEY}"

service:
  pipelines:
    logs:
      receivers: [filelog/syslog]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]
EOF

구성에서 다음 항목을 교체하십시오:

YOUR_CLICKSTACK_HOST: ClickStack이 실행되는 호스트명 또는 IP 주소
로컬에서 테스트하려면 SSH 터널을 사용할 수 있습니다(문제 해결 섹션 참조).

이 구성:

표준 경로(Ubuntu의 경우 /var/log/syslog, Amazon Linux/RHEL의 경우 /var/log/messages)에서 시스템 로그 파일을 읽습니다
syslog 포맷을 파싱해 구조화된 필드(타임스탬프, 호스트명, 유닛/서비스, PID, 메시지)를 추출합니다
resourcedetection processor를 사용해 EC2 메타데이터를 자동으로 감지해 추가합니다
있는 경우 EC2 태그(Name, Environment, Team)도 선택적으로 포함됩니다
OTLP HTTP를 통해 ClickStack으로 로그를 전송합니다

ClickStack API Key 설정

ClickStack API Key를 환경 변수로 설정하십시오:

export CLICKSTACK_API_KEY="your-api-key-here"

재부팅해도 이 설정이 유지되도록 하려면 셸 프로필에 추가하십시오:

echo 'export CLICKSTACK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

collector를 실행합니다

OpenTelemetry Collector를 시작합니다:

CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml

HyperDX에서 로그 확인

collector가 실행 중이면 HyperDX에 로그인한 다음, EC2 메타데이터와 함께 로그가 유입되고 있는지 확인합니다:

Search view로 이동합니다
source를 Logs로 설정합니다
source:ec2-host-logs로 필터링합니다
로그 항목을 클릭해 펼칩니다
리소스 속성에서 EC2 메타데이터가 표시되는지 확인합니다:
- cloud.provider
- cloud.region
- host.id (instance ID)
- host.type (인스턴스 유형)
- cloud.availability_zone

데모 데이터세트

프로덕션 인스턴스를 구성하기 전에 EC2 호스트 로그 통합을 테스트해 보려는 사용자를 위해 시뮬레이션된 EC2 메타데이터가 포함된 샘플 데이터셋을 제공합니다.

샘플 데이터셋 다운로드

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

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log

데이터셋에는 다음이 포함됩니다:

시스템 부팅 과정
SSH 로그인 활동(성공 및 실패 시도)
보안 사고(fail2ban 대응이 포함된 무차별 대입 공격)
정기 유지 관리(cron 작업, anacron)
서비스 재시작(rsyslog)
커널 메시지와 방화벽 활동
일반적인 운영과 주요 이벤트의 혼재

테스트용 collector 구성 만들기

다음과 같은 구성으로 ec2-host-logs-demo.yaml 파일을 만드세요:

cat > ec2-host-logs-demo.yaml << 'EOF'
receivers:
  filelog/journal:
    include:
      - /tmp/host-demo/journal.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: "ec2-demo"

processors:
  # Simulate EC2 metadata for demo (no real EC2 instance required)
  resource:
    attributes:
      - key: service.name
        value: "ec2-demo"
        action: insert
      - key: cloud.provider
        value: "aws"
        action: insert
      - key: cloud.platform
        value: "aws_ec2"
        action: insert
      - key: cloud.region
        value: "us-east-1"
        action: insert
      - key: cloud.availability_zone
        value: "us-east-1a"
        action: insert
      - key: host.id
        value: "i-0abc123def456789"
        action: insert
      - key: host.type
        value: "t3.medium"
        action: insert
      - key: host.name
        value: "prod-web-01"
        action: insert

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

데모 구성으로 ClickStack 실행

데모 로그와 구성을 사용해 ClickStack을 실행합니다:

docker run --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)/ec2-host-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/journal.log:/tmp/host-demo/journal.log:ro" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

HyperDX에서 로그 확인

collector가 실행되면 다음 단계를 따르세요:

HyperDX를 열고 계정에 로그인합니다 (먼저 계정을 생성해야 할 수 있습니다)
검색 뷰로 이동한 다음 source를 Logs로 설정합니다
시간 범위를 2025-11-10 00:00:00 - 2025-11-13 00:00:00로 설정합니다
source:ec2-demo로 필터링합니다
로그 항목을 펼쳐 리소스 속성에서 EC2 메타데이터를 확인합니다

다음과 같은 시뮬레이션된 EC2 컨텍스트가 포함된 로그가 표시되어야 합니다:

인스턴스 ID: i-0abc123def456789
리전: us-east-1
가용 영역: us-east-1a
인스턴스 유형: t3.medium

대시보드 및 시각화

ClickStack로 EC2 호스트 로그 모니터링을 시작할 수 있도록 클라우드 컨텍스트가 포함된 핵심 시각화를 제공합니다.

대시보드 구성 파일 다운로드

대시보드 구성 파일 다운로드.

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

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

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

대시보드 보기

모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다:

EC2 컨텍스트를 기준으로 대시보드 시각화를 필터링할 수 있습니다:

cloud.region:us-east-1 - 특정 리전의 로그 표시
host.type:t3.medium - 인스턴스 유형으로 필터링
host.id:i-0abc123def456 - 특정 인스턴스의 로그

문제 해결

로그에 EC2 메타데이터가 표시되지 않는 경우

EC2 메타데이터 서비스에 접근할 수 있는지 확인하세요:

# 메타데이터 토큰 가져오기
TOKEN=$(curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")

# 메타데이터 엔드포인트 테스트
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id

이 작업이 실패하면 다음 사항을 확인하십시오:

인스턴스 메타데이터 서비스가 활성화되어 있는지
IMDSv2가 보안 그룹(Security Group)에 의해 차단되지 않는지
EC2 인스턴스 자체에서 collector를 실행하고 있는지

메타데이터 관련 오류가 있는지 collector 로그를 확인하십시오:

# systemd 서비스로 실행 중인 경우
sudo journalctl -u otelcol-contrib -f | grep -i "ec2\|metadata\|resourcedetection"

# 포그라운드에서 실행 중인 경우 stdout 확인

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

syslog 파일이 존재하고 정상적으로 기록되고 있는지 확인하세요:

ls -la /var/log/syslog /var/log/messages
tail -f /var/log/syslog

collector가 로그 파일을 읽을 수 있는지 확인하십시오:

cat /var/log/syslog | head -20

ClickStack으로의 네트워크 연결을 확인하세요:

# OTLP 엔드포인트 테스트
curl -v http://YOUR_CLICKSTACK_HOST:4318/v1/logs

# 응답이 오면 정상 (오류 응답이더라도 엔드포인트에 도달 가능함을 의미)

collector 로그에서 오류가 있는지 확인하세요:

# 포그라운드로 실행 중인 경우
# stdout에서 오류 메시지 확인

# systemd 서비스로 실행 중인 경우
sudo journalctl -u otelcol-contrib -f | grep -i "error\|failed"

로그 파싱이 올바르지 않은 경우

syslog 포맷을 확인하십시오:

Ubuntu 24.04+의 경우:

# ISO8601 포맷으로 표시되어야 합니다: 2025-11-17T20:55:44.826796+00:00
tail -5 /var/log/syslog

Amazon Linux 2 / Ubuntu 20.04에서는:

# 전통적인 포맷으로 표시되어야 합니다: Nov 17 14:16:16
tail -5 /var/log/messages

포맷이 맞지 않으면 배포판에 따라 collector 구성 만들기 섹션에서 해당 구성 탭을 사용하십시오.

collector가 systemd 서비스로 시작되지 않는 경우

서비스 상태를 확인하세요:

sudo systemctl status otelcol-contrib

상세 로그 보기:

sudo journalctl -u otelcol-contrib -n 50

일반적인 문제:

환경 변수에 API Key가 올바르게 설정되지 않음
구성 파일 구문 오류
로그 파일 읽기 권한 문제

다음 단계

중요한 시스템 이벤트(서비스 장애, 인증 실패, 디스크 경고)에 대한 알림을 설정합니다
EC2 메타데이터 속성(리전, 인스턴스 유형, 인스턴스 ID)으로 필터링해 특정 리소스를 모니터링합니다
종합적인 문제 해결을 위해 EC2 호스트 로그를 애플리케이션 로그와 연관시킵니다
보안 모니터링(SSH 시도, sudo 사용, 방화벽 차단)을 위한 사용자 지정 대시보드를 생성합니다

프로덕션 환경으로 전환

이 가이드에서는 호스트 수준 모니터링에 권장되는 프로덕션 패턴으로 OpenTelemetry Collector를 EC2 인스턴스에 직접 설치합니다. 여러 인스턴스에 걸쳐 collector를 관리하려면 구성 관리 도구(Ansible, Chef, Puppet) 또는 Kubernetes 환경의 OpenTelemetry Operator 사용을 고려하십시오. 프로덕션 구성에 대해서는 OpenTelemetry 데이터 전송을 참조하십시오.