Coroot Observability

제로 계측 메트릭, 로그, 트레이스 및 Kubernetes와 Docker 환경을 위한 지속적 프로파일링을 갖춘 오픈소스 eBPF 기반 관찰성 및 APM 도구입니다.

설치

Docker Compose (가장 빠름)

# ClickHouse 및 Prometheus를 포함한 원 커맨드 배포
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-compose.yaml | \
  docker compose -f - up -d

# http://localhost:8080에서 UI 접근

Kubernetes (Helm)

# Coroot Helm 저장소 추가
helm repo add coroot https://coroot.github.io/helm-charts
helm repo update coroot

# Coroot 오퍼레이터 설치
helm install -n coroot --create-namespace coroot-operator coroot/coroot-operator

# Community Edition 배포
helm install -n coroot coroot coroot/coroot-ce

# ClickHouse 복제로 배포
helm install -n coroot coroot coroot/coroot-ce \
  --set "clickhouse.shards=2,clickhouse.replicas=2"

# UI 접근을 위한 포트 포워딩
kubectl port-forward -n coroot service/coroot-coroot 8080:8080

# http://localhost:8080에서 UI 접근

Docker Swarm

# Coroot 스택 배포
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-swarm-stack.yaml | \
  docker stack deploy -c - coroot

Ubuntu/Debian

# Coroot 서버 설치
curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
  BOOTSTRAP_PROMETHEUS_URL="http://PROMETHEUS_IP:9090" \
  BOOTSTRAP_REFRESH_INTERVAL=15s \
  BOOTSTRAP_CLICKHOUSE_ADDRESS=CLICKHOUSE_IP:9000 \
  sh -

RHEL/CentOS

# RHEL 기반 배포에도 동일한 설치 프로그램 작동
curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
  BOOTSTRAP_PROMETHEUS_URL="http://PROMETHEUS_IP:9090" \
  BOOTSTRAP_REFRESH_INTERVAL=15s \
  BOOTSTRAP_CLICKHOUSE_ADDRESS=CLICKHOUSE_IP:9000 \
  sh -

노드 에이전트 설치

Docker

# 권한 있는 컨테이너로 노드 에이전트 실행
docker run --detach --name coroot-node-agent \
  --pull=always --privileged --pid host \
  -v /sys/kernel/tracing:/sys/kernel/tracing:rw \
  -v /sys/kernel/debug:/sys/kernel/debug:rw \
  -v /sys/fs/cgroup:/host/sys/fs/cgroup:ro \
  ghcr.io/coroot/coroot-node-agent \
  --cgroupfs-root=/host/sys/fs/cgroup \
  --collector-endpoint=http://COROOT_IP:8080

Linux (systemd)

# 베어 메탈 또는 VM에 노드 에이전트 설치
curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \
  COLLECTOR_ENDPOINT=http://COROOT_IP:8080 \
  SCRAPE_INTERVAL=15s \
  sh -

Kubernetes (Helm 오퍼레이터 경유)

# 노드 에이전트는 Coroot 오퍼레이터에 의해 자동 배포됨
# Helm 사용 시 별도 설치 필요 없음

기본 명령어

명령어	설명
`docker compose up -d`	Docker Compose로 Coroot 시작
`docker compose down`	모든 Coroot 서비스 중지
`docker compose logs -f`	Coroot 로그 추적
`helm install coroot coroot/coroot-ce`	Kubernetes에 Coroot 설치
`helm upgrade coroot coroot/coroot-ce`	Coroot 업그레이드
`helm uninstall coroot -n coroot`	클러스터에서 Coroot 제거
`kubectl port-forward svc/coroot-coroot 8080:8080 -n coroot`	Coroot UI 접근

구성 매개변수

서버 구성

변수	설명	기본값
`BOOTSTRAP_PROMETHEUS_URL`	Prometheus 서버 엔드포인트	필수
`BOOTSTRAP_REFRESH_INTERVAL`	메트릭 수집 간격	`15s`
`BOOTSTRAP_CLICKHOUSE_ADDRESS`	ClickHouse 서버 주소	필수
`LISTEN_ADDRESS`	HTTP 리스닝 주소	`:8080`
`DATA_DIR`	데이터 디렉토리 경로	`/var/lib/coroot`

노드 에이전트 구성

플래그	설명	기본값
`--collector-endpoint`	Coroot 서버 엔드포인트	필수
`--cgroupfs-root`	Cgroup 파일시스템 루트 경로	`/sys/fs/cgroup`
`--scrape-interval`	메트릭 스크레이프 간격	`15s`
`--log-level`	로깅 상세도	`info`

아키텍처 구성 요소

구성 요소	역할
Coroot Server	중앙 대시보드, 분석 엔진, 알림
Node Agent	각 노드의 eBPF 기반 메트릭/로그 수집
Cluster Agent	데이터베이스 모니터링 (MySQL, PostgreSQL, Redis)
ClickHouse	메트릭, 로그, 트레이스 및 프로파일 저장
Prometheus	메트릭 스크레이프 및 원격 쓰기

주요 기능

제로 계측 관찰성

기능	설명
Automatic Discovery	eBPF를 통한 자동 서비스 발견 — 코드 변경 필요 없음
Service Map	모든 서비스 의존성을 보여주는 라이브 토폴로지 맵
Distributed Tracing	SDK 없이 마이크로서비스 간 요청 추적
Log Collection	자동 로그 수집 및 패턴 클러스터링
Continuous Profiling	원 클릭 활성화로 CPU/메모리 프로파일링

모니터링 기능

기능	설명
SLO Tracking	Service Level Objectives 정의 및 모니터링
Issue Detection	80%+ 문제의 자동 식별
Deployment Tracking	Kubernetes 배포 및 롤백 추적
Cost Monitoring	AWS, GCP, Azure 리소스 비용 분석
Network Analysis	TCP 연결 메트릭, DNS 지연, 재전송

지원되는 프로토콜 (eBPF)

프로토콜	수집된 메트릭
HTTP/HTTPS	지연, 오류율, 처리량
gRPC	메서드 수준 지연 및 오류
PostgreSQL	쿼리 지연, 연결, 오류
MySQL	쿼리 성능, 느린 쿼리
Redis	명령 지연, 히트/미스 비율
MongoDB	작업 지연, 연결
Kafka	프로듀서/컨슈머 지연, 처리량
DNS	해석 지연, 실패율

Helm 차트 값

일반적인 오버라이드

# 사용자 정의 ClickHouse 크기 조정
helm install coroot coroot/coroot-ce \
  --set clickhouse.shards=3 \
  --set clickhouse.replicas=2 \
  --set clickhouse.storage=100Gi

# 사용자 정의 Prometheus 설정
helm install coroot coroot/coroot-ce \
  --set prometheus.storage=50Gi \
  --set prometheus.retention=30d

# Ingress 활성화
helm install coroot coroot/coroot-ce \
  --set ingress.enabled=true \
  --set ingress.host=coroot.example.com

알림 구성

알림 유형	설명
SLO Breach	SLO 목표가 위험할 때 트리거됨
Latency Spike	p99 지연이 임계값 초과
Error Rate	오류 비율이 임계값 초과
Resource	CPU, 메모리 또는 디스크 사용 이상
Deployment	실패했거나 성능 저하된 배포 감지

알림 채널

채널	설정
Slack	웹훅 URL
PagerDuty	통합 키
Opsgenie	API 키
Email	SMTP 설정
Webhook	사용자 정의 HTTP 엔드포인트

문제 해결

문제	솔루션
데이터 표시 안 됨	노드 에이전트 `--collector-endpoint`가 Coroot 서버를 가리키는지 확인
누락된 서비스	노드 에이전트가 `--privileged` 및 `--pid host`로 실행되는지 확인
eBPF 로드 안 됨	커널 버전 4.16 이상 및 BTF 지원 확인
높은 메모리 사용	`--scrape-interval` 감소 또는 모니터링되는 네임스페이스 제한
ClickHouse 연결	ClickHouse가 실행 중이고 포트 9000에서 접근 가능한지 확인

모범 사례

완전한 가시성을 위해 클러스터의 모든 노드에 노드 에이전트 배포하세요
프로덕션 배포를 위해 ClickHouse 복제 사용 (최소 2개 복제본)
자동 알림에 의존하기 전에 의미 있는 SLO 목표 설정하세요
평가를 위해 Docker Compose로 시작하고 프로덕션을 위해 Helm으로 마이그레이션하세요
포드 재시작을 넘어 메트릭을 유지하려면 Prometheus 원격 쓰기 설정하세요
스케일링 전에 CPU/메모리 핫스팟을 식별하려면 내장 프로파일러를 사용하세요
배포 추적을 활성화하여 성능 변경과 릴리스 상관 관계를 파악하세요