메인 콘텐츠로 건너뛰기
요약OpenTelemetry Collector를 사용해 EC2 메타데이터(인스턴스 ID, 리전, AZ, 인스턴스 유형)를 자동으로 보강하고, ClickStack에서 EC2 시스템 로그를 수집하고 시각화합니다. 데모 데이터셋과 사전 구축된 대시보드가 포함됩니다.

​
기존 EC2 인스턴스와의 통합

이 섹션에서는 시스템 로그를 수집하고 EC2 메타데이터를 자동으로 보강해 ClickStack으로 전송할 수 있도록 EC2 인스턴스에 OpenTelemetry Collector를 설치하는 방법을 설명합니다. 이 분산 아키텍처는 프로덕션 환경에 적합하며 여러 인스턴스로 확장할 수 있습니다.
같은 EC2 인스턴스에서 ClickStack을 실행 중입니까?모니터링하려는 로그가 있는 동일한 EC2 인스턴스에서 ClickStack을 실행 중이라면 Generic Host Logs guide와 유사한 올인원 방식을 사용할 수 있습니다. /var/log를 ClickStack 컨테이너에 마운트하고 사용자 지정 구성에 resourcedetection processor를 추가하면 EC2 메타데이터를 자동으로 수집할 수 있습니다. 이 가이드는 프로덕션 배포에서 더 일반적으로 사용하는 분산 아키텍처에 중점을 둡니다.
프로덕션 인스턴스를 구성하기 전에 EC2 호스트 로그 통합을 테스트하려면 “데모 데이터셋” 섹션의 사전 구성된 설정과 샘플 데이터를 사용하면 됩니다.
사전 요구 사항
  • 실행 중인 ClickStack 인스턴스(온프레미스, 클라우드 또는 로컬 환경)
  • 실행 중인 EC2 인스턴스(Ubuntu, Amazon Linux 또는 기타 Linux 배포판)
  • EC2 인스턴스에서 ClickStack의 OTLP 엔드포인트로의 네트워크 연결(HTTP는 포트 4318, gRPC는 포트 4317)
  • EC2 인스턴스 메타데이터 서비스에 접근 가능(기본적으로 활성화됨)
1

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

EC2 인스턴스에서 메타데이터 서비스에 액세스할 수 있는지 확인합니다:
# 메타데이터 토큰 가져오기 (IMDSv2)
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
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 인스턴스 자체에서 실행하고 있는지
EC2 메타데이터는 인스턴스 내부에서 http://169.254.169.254를 통해 사용할 수 있습니다. OpenTelemetry resourcedetection processor는 이 엔드포인트를 사용해 로그에 클라우드 Context를 자동으로 보강합니다.
2

​
syslog 파일이 있는지 확인

EC2 인스턴스에 syslog 파일이 기록되고 있는지 확인합니다:
# Ubuntu 인스턴스
ls -la /var/log/syslog

# Amazon Linux / RHEL 인스턴스
ls -la /var/log/messages

# 최근 항목 확인
tail -20 /var/log/syslog
# 또는
tail -20 /var/log/messages
3

​
OpenTelemetry Collector 설치

EC2 인스턴스에 OpenTelemetry Collector Contrib 배포판을 설치하세요:
# 최신 릴리스 다운로드
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.114.0/otelcol-contrib_0.114.0_linux_amd64.tar.gz

# 압축 해제 및 설치
tar -xvf otelcol-contrib_0.114.0_linux_amd64.tar.gz
sudo mv otelcol-contrib /usr/local/bin/

# 설치 확인
otelcol-contrib --version
4

​
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

구성에서 다음 항목을 교체하십시오:
  • 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으로 로그를 전송합니다
EC2 메타데이터 보강resourcedetection processor가 모든 로그에 다음 속성을 자동으로 추가합니다:
  • cloud.provider: “aws”
  • cloud.platform: “aws_ec2”
  • cloud.region: AWS 리전(예: “us-east-1”)
  • cloud.availability_zone: AZ(예: “us-east-1a”)
  • cloud.account.id: AWS 계정 ID
  • host.id: EC2 인스턴스 ID(예: “i-1234567890abcdef0”)
  • host.type: 인스턴스 유형(예: “t3.medium”)
  • host.name: EC2 인스턴스의 호스트명
5

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

​
collector를 실행합니다

OpenTelemetry Collector를 시작합니다:
CLICKSTACK_API_KEY="your-api-key-here" /usr/local/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml
프로덕션 환경에서 사용하는 경우부팅 시 자동으로 시작되고 장애 발생 시 자동으로 재시작되도록 collector를 systemd 서비스로 구성하십시오. 자세한 내용은 OpenTelemetry Collector 문서를 참조하십시오.
7

​
HyperDX에서 로그 확인

collector가 실행 중이면 HyperDX에 로그인한 다음, EC2 메타데이터와 함께 로그가 유입되고 있는지 확인합니다:
  1. Search view로 이동합니다
  2. source를 Logs로 설정합니다
  3. source:ec2-host-logs로 필터링합니다
  4. 로그 항목을 클릭해 펼칩니다
  5. 리소스 속성에서 EC2 메타데이터가 표시되는지 확인합니다:
    • cloud.provider
    • cloud.region
    • host.id (instance ID)
    • host.type (인스턴스 유형)
    • cloud.availability_zone

​
데모 데이터세트

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

​
샘플 데이터셋 다운로드

샘플 로그 파일을 다운로드하세요:
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/host-logs/journal.log
데이터셋에는 다음이 포함됩니다:
  • 시스템 부팅 과정
  • SSH 로그인 활동(성공 및 실패 시도)
  • 보안 사고(fail2ban 대응이 포함된 무차별 대입 공격)
  • 정기 유지 관리(cron 작업, anacron)
  • 서비스 재시작(rsyslog)
  • 커널 메시지와 방화벽 활동
  • 일반적인 운영과 주요 이벤트의 혼재
2

​
테스트용 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:
  # 데모용 EC2 메타데이터 시뮬레이션 (실제 EC2 인스턴스 불필요)
  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
데모 목적으로 resource processor를 사용해 EC2 메타데이터를 수동으로 추가합니다. 실제 EC2 인스턴스를 사용하는 프로덕션 환경에서는 EC2 메타데이터 API를 자동으로 조회하는 resourcedetection processor를 사용하십시오.
3

​
데모 구성으로 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
4

​
HyperDX에서 로그 확인

collector가 실행되면 다음 단계를 따르세요:
  1. HyperDX를 열고 계정에 로그인합니다 (먼저 계정을 생성해야 할 수 있습니다)
  2. 검색 뷰로 이동한 다음 source를 Logs로 설정합니다
  3. 시간 범위를 2025-11-10 00:00:00 - 2025-11-13 00:00:00로 설정합니다
  4. source:ec2-demo로 필터링합니다
  5. 로그 항목을 펼쳐 리소스 속성에서 EC2 메타데이터를 확인합니다
시간대 표시HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC) 범위에 걸쳐 있습니다. 시간 범위를 넓게 설정하면 위치와 관계없이 데모 로그를 확인할 수 있습니다. 로그가 표시되면 더 명확한 시각화를 위해 범위를 24시간으로 좁힐 수 있습니다.
다음과 같은 시뮬레이션된 EC2 컨텍스트가 포함된 로그가 표시되어야 합니다:
  • 인스턴스 ID: i-0abc123def456789
  • 리전: us-east-1
  • 가용 영역: us-east-1a
  • 인스턴스 유형: t3.medium

​
대시보드 및 시각화

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

​
대시보드 구성 파일

2

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

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

​
대시보드 보기

모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다:EC2 컨텍스트를 기준으로 대시보드 시각화를 필터링할 수 있습니다:
  • cloud.region:us-east-1 - 특정 리전의 로그 표시
  • host.type:t3.medium - 인스턴스 유형으로 필터링
  • host.id:i-0abc123def456 - 특정 인스턴스의 로그
데모 데이터셋의 경우 시간 범위를 **2025-11-11 00:00:00 - 2025-11-12 00:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되어 있지 않습니다.

​
문제 해결

​
로그에 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 데이터 전송을 참조하십시오.
마지막 수정일 2026년 6월 10일