요약OpenTelemetry Collector의 CloudWatch 수신기를 사용해 AWS CloudWatch Logs를 ClickStack으로 전달합니다. 지정된 로그 그룹과 자동 검색을 지원합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함되어 있습니다.
개요
- 통합 플랫폼에서 로그를 메트릭 및 trace와 함께 분석할 수 있습니다
- ClickHouse의 SQL 인터페이스를 사용해 로그를 쿼리할 수 있습니다
- CloudWatch 보존 기간을 줄이거나 로그를 아카이브하여 비용을 절감할 수 있습니다
기존 CloudWatch 로그 그룹과의 통합
사전 요구 사항
- 실행 중인 ClickStack 인스턴스
- CloudWatch 로그 그룹이 있는 AWS 계정
- 적절한 IAM 권한이 있는 AWS 자격 증명
파일 기반 로그 통합(nginx, Redis)과 달리 CloudWatch는 CloudWatch API를 폴링하는 별도의 OpenTelemetry Collector를 실행해야 합니다. 이 collector는 AWS 자격 증명과 API 액세스가 필요하므로 ClickStack의 올인원 이미지 내부에서는 실행할 수 없습니다.
ClickStack API Key 가져오기
OpenTelemetry Collector는 데이터를 ClickStack의 OTLP endpoint로 전송하므로 인증이 필요합니다.- ClickStack URL(예: http://localhost:8080)에서 HyperDX를 여십시오
- 필요하면 계정을 만들거나 로그인하십시오
- Team Settings → API Keys로 이동하십시오
- 수집 API Key를 복사하십시오
AWS 자격 증명 구성
AWS 자격 증명을 환경 변수로 내보내십시오. 방법은 인증 유형에 따라 다릅니다.AWS SSO 사용자용(대부분의 조직에 권장):YOUR_PROFILE_NAME을 AWS SSO 프로필 이름(예: AccountAdministrators-123456789)으로 바꾸세요.장기 자격 증명을 사용하는 IAM 사용자용:YOUR_ACCOUNT_ID를 AWS 계정 ID로 바꾸십시오.CloudWatch receiver를 구성합니다
CloudWatch receiver 구성이 포함된otel-collector-config.yaml 파일을 생성합니다.계정에서 사용할 수 있는 로그 그룹을 확인합니다
계정에서 사용할 수 있는 로그 그룹을 확인합니다
구성을 편집하기 전에 리전에 있는 로그 그룹 목록을 확인하여 실제 이름을 선택하고, 리전이 올바른지도 확인합니다.예시 출력:아래 예시 1의 또는 원하는 그룹이 공통 prefix(여기서는
groups.named 블록에는 이 목록에 있는 이름을 그대로 사용합니다. 위 계정의 경우 named-groups 섹션은 다음과 같이 됩니다./aws-glue/)를 공유하는 경우, 각각 나열하는 대신 예시 2에서 prefix: /aws-glue/를 사용합니다./aws/lambda 접두사로 시작하는 로그 그룹을 최대 100개까지 자동으로 찾아 로그를 수집합니다:region: 로그 그룹이 위치한 AWS 리전poll_interval: 새 로그를 확인하는 주기(예:1m,5m)max_events_per_request: 요청당 가져올 최대 로그 이벤트 수groups.autodiscover.limit: 자동으로 검색할 최대 로그 그룹 수groups.autodiscover.prefix: 프리픽스로 로그 그룹을 필터링groups.named: 수집할 로그 그룹 이름을 명시적으로 지정
${CLICKSTACK_API_KEY}→ 앞서 설정한 환경 변수를 사용합니다http://localhost:4318→ ClickStack 엔드포인트(원격에서 실행 중이면 ClickStack 호스트 사용)us-east-1→ AWS 리전- 로그 그룹 이름/프리픽스 → 실제 CloudWatch 로그 그룹
CloudWatch receiver는 최근 시간 윈도우의 로그만 가져옵니다(
poll_interval 기준). 처음 시작되면 현재 시점부터 수집을 시작합니다. 과거 로그는 기본적으로 가져오지 않습니다.HyperDX에서 로그 확인
collector가 실행되면 다음을 수행하세요:- http://localhost:8080(또는 ClickStack URL)에서 HyperDX를 엽니다
- Logs 보기로 이동합니다
- 로그가 표시될 때까지 1~2분 정도 기다립니다(폴링 주기에 따라 다름)
- CloudWatch 로그 그룹의 로그를 검색합니다
ResourceAttributes['aws.region']: AWS 리전(예: “us-east-1”)ResourceAttributes['cloudwatch.log.group.name']: CloudWatch 로그 그룹 이름ResourceAttributes['cloudwatch.log.stream']: 로그 스트림 이름Body: 실제 로그 메시지 내용
데모 데이터세트
샘플 데이터셋 다운로드
- Lambda functions: 결제 처리, 주문 관리, 인증
- ECS services: rate limiting 및 timeout이 적용된 API gateway
- Background jobs: retry 패턴이 포함된 Batch 처리
데모 데이터 확인
가져오기가 완료되면 다음을 수행하세요.- http://localhost:8080에서 HyperDX를 열고 로그인합니다(필요한 경우 계정을 생성합니다).
- Logs 보기로 이동합니다.
- 시간 범위를 **2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)**로 설정합니다.
cloudwatch-demo를 검색하거나LogAttributes['source'] = 'cloudwatch-demo'로 필터링합니다.
시간대 표시HyperDX는 타임스탬프를 브라우저의 로컬 시간대로 표시합니다. 데모 데이터는 2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC) 범위에 해당합니다. 위치와 관계없이 데모 로그가 보이도록 시간 범위를 2025-12-06 00:00:00 - 2025-12-09 00:00:00로 설정하세요. 로그가 표시되면 더 명확한 시각화를 위해 범위를 24시간으로 좁힐 수 있습니다.
대시보드 및 시각화
대시보드 구성 파일
대시보드 가져오기
- HyperDX를 열고 Dashboards 섹션으로 이동합니다
- 오른쪽 상단의 줄임표 메뉴에서 Import Dashboard를 클릭합니다
cloudwatch-logs-dashboard.json파일을 업로드한 다음 Finish Import를 클릭합니다
대시보드 보기
대시보드는 모든 시각화가 미리 구성된 상태로 생성됩니다:데모 데이터세트의 경우 시간 범위를 **2025-12-07 00:00:00 - 2025-12-08 00:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되어 있지 않습니다.
문제 해결
HyperDX에 로그가 표시되지 않는 경우
logs:DescribeLogGroups 및 logs:FilterLogEvents permission이 있는지 확인하세요.
collector logs에서 오류 확인:
The security token included in the request is invalid: 자격 증명이 올바르지 않거나 만료되었습니다. 임시 자격 증명(SSO)을 사용하는 경우AWS_SESSION_TOKEN이 설정되어 있는지 확인하세요.operation error CloudWatch Logs: FilterLogEvents, AccessDeniedException: IAM 권한이 부족합니다failed to refresh cached credentials, no EC2 IMDS role found: AWS 자격 증명 환경 변수가 설정되지 않았습니다connection refused: ClickStack 엔드포인트에 연결할 수 없습니다
오래된 로그만 보이거나 최근 로그가 누락되는 경우
유효하지 않은 보안 토큰 / 자격 증명 만료
지연 시간이 높거나 최신 로그가 누락됨
poll_interval은 1분입니다. 실시간에 가까운 로그가 필요하면 이 값을 줄이십시오:
collector의 메모리 사용량이 너무 많음
다음 단계
- 중요한 이벤트(연결 실패, 오류 급증)에 대한 알림을 설정하세요
- 이제 로그가 ClickStack에 있으므로 보존 기간을 조정하거나 S3에 보관하여 CloudWatch 비용을 줄이세요
- 수집량을 줄이려면 노이즈가 많은 로그 그룹을 collector 구성에서 제거하세요