문제 해결

일반적인 문제와 해결 방법을 안내합니다.

데이터 수집 문제

메트릭이 수집되지 않음

증상: Infrastructure 또는 Services 대시보드에 데이터 없음

진단:

# OTel Collector 상태 확인
kubectl logs -n skuber-observability -l app.kubernetes.io/name=k8s-infra \
  --context <agent-context> | grep -i error

# 메트릭 전송 확인
kubectl logs -n skuber-observability -l app.kubernetes.io/name=k8s-infra \
  --context <agent-context> | grep "otel"

해결:

OTLP 엔드포인트 확인

# Host LB IP 확인
kubectl get svc -n signoz | grep LoadBalancer

네트워크 연결 확인

# Agent 클러스터에서 Host로 연결 테스트
kubectl run test-connection --rm -it --image=busybox \
  --context <agent-context> -- \
  wget -O- http://<host-lb-ip>:4317

방화벽 규칙 확인
- 포트 4317 (gRPC OTLP) 허용 확인

로그가 수집되지 않음

증상: Logs Explorer에 데이터 없음

진단:

# filelog receiver 로그 확인
kubectl logs -n skuber-observability -l app.kubernetes.io/name=k8s-infra \
  --context <agent-context> | grep "filelog"

해결:

로그 경로 확인

# 로그 수집 경로
/var/log/pods/*/*/*.log

hostPath 마운트 확인

kubectl describe pod -n skuber-observability -l app.kubernetes.io/name=k8s-infra \
  --context <agent-context> | grep -A 5 "Mounts"

트레이스가 수집되지 않음

증상: Traces 페이지에 데이터 없음

진단:

# APM Agent 상태 확인
kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent \
  --context <agent-context> | grep -i "discovered\|error"

해결:

커널 버전 확인 (5.8 이상 필요)
```
uname -r
```

APM Agent privileged 모드 확인

kubectl get pod -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent \
  --context <agent-context> -o yaml | grep privileged

애플리케이션 트래픽 확인
- HTTP/gRPC 트래픽이 있는지 확인

쿼리 성능 문제

느린 대시보드

증상: 대시보드 로딩이 느림

해결:

시간 범위 축소
- 24시간 → 1시간

쿼리 최적화

# 나쁜 예: 모든 시계열
http_server_request_total

# 좋은 예: 필터링 및 집계
sum(rate(http_server_request_total[5m])) by (service_name)

ClickHouse 리소스 증가

clickhouse:
  resources:
    limits:
      memory: 16Gi

쿼리 타임아웃

증상: "Query timeout" 에러

해결:

시간 범위 축소
쿼리 복잡도 감소
ClickHouse 설정 조정
```
SET max_execution_time = 60;
```

ClickHouse 문제

아래 명령어는 ClickHouse VM 서버에서 실행합니다.

디스크 공간 부족

증상: 데이터 저장 실패

진단:

# ClickHouse VM에 SSH 접속
ssh <user>@<clickhouse-vm-ip>

# 디스크 사용량 확인
df -h /var/lib/clickhouse

# 테이블별 용량 확인
clickhouse-client --password '<password>' --query="
  SELECT
    database,
    table,
    formatReadableSize(sum(bytes_on_disk)) as size
  FROM system.parts
  GROUP BY database, table
  ORDER BY sum(bytes_on_disk) DESC
"

해결:

TTL 단축

clickhouse-client --password '<password>' --query="
  ALTER TABLE signoz_metrics.samples_v4
  MODIFY TTL toDateTime(unix_milli / 1000) + INTERVAL 3 DAY
"

오래된 데이터 삭제

clickhouse-client --password '<password>' --query="
  ALTER TABLE signoz_metrics.samples_v4
  DELETE WHERE toDateTime(unix_milli / 1000) < now() - INTERVAL 7 DAY
"

디스크 확장
- VM 디스크 볼륨 확장
- 파일시스템 리사이즈: resize2fs /dev/sdX

ClickHouse 연결 실패

증상: "Connection refused" 에러

진단:

# ClickHouse 프로세스 상태 확인
ssh <user>@<clickhouse-vm-ip>
systemctl status clickhouse-server

# ClickHouse 로그 확인
tail -100 /var/log/clickhouse-server/clickhouse-server.log
tail -100 /var/log/clickhouse-server/clickhouse-server.err.log

해결:

서비스 재시작

sudo systemctl restart clickhouse-server

리소스 확인

# 메모리 사용량
free -h

# OOM 로그 확인
dmesg | grep -i "out of memory"

포트 확인

# 9000 (TCP), 8123 (HTTP) 포트 리스닝 확인
ss -tlnp | grep -E "9000|8123"

네트워크 문제

Agent-Host 연결 실패

증상: Agent 클러스터 데이터가 수집되지 않음

진단:

# Agent에서 Host로 연결 테스트
kubectl run test --rm -it --image=curlimages/curl \
  --context <agent-context> -- \
  curl -v http://<host-lb-ip>:4317

해결:

LoadBalancer IP 확인
```
kubectl get svc -n signoz -o wide
```
방화벽 규칙
- 인바운드: 4317 (OTLP gRPC)
- 클러스터 간 네트워크 정책 확인

DNS 해결 확인

kubectl run test --rm -it --image=busybox \
  --context <agent-context> -- nslookup <host-lb-ip>

APM Agent 문제

프로세스가 감지되지 않음

증상: Services 목록이 비어있음

진단:

kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent \
  --context <agent-context> | grep "discovered"

해결:

지원 언어/프레임워크 확인
- Go, Java, Python, Node.js, .NET 등
포트 확인
- 표준 HTTP/gRPC 포트 사용

네임스페이스 필터 확인

# APM Agent 설정에서 제외된 네임스페이스
discovery:
  kubernetes:
    namespaces:
      - my-app-namespace

eBPF 로딩 실패

증상: APM Agent 시작 실패

진단:

kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent \
  --context <agent-context> | grep -i "ebpf\|btf"

해결:

커널 버전 확인
```
uname -r  # 5.8 이상 필요
```
BTF 지원 확인
```
ls /sys/kernel/btf/vmlinux
```
privileged 모드 확인

알림 문제

알림이 발생하지 않음

진단:

규칙 상태 확인 (활성화 여부)
쿼리가 데이터를 반환하는지 확인
임계값 설정 확인

알림이 전송되지 않음

진단:

알림 채널 설정 확인
테스트 메시지 전송

AlertManager 로그 확인:

kubectl logs -n signoz -l app.kubernetes.io/name=alertmanager

로그 수집

지원 요청 시 수집할 정보

# 클러스터 정보
kubectl version
kubectl get nodes

# 파드 상태
kubectl get pods -n signoz -o wide
kubectl get pods -n skuber-observability --context <agent-context> -o wide

# 이벤트
kubectl get events -n signoz --sort-by='.lastTimestamp'

# 로그
kubectl logs -n signoz -l app.kubernetes.io/name=signoz --tail=500 > signoz-logs.txt
kubectl logs -n skuber-observability -l app.kubernetes.io/name=k8s-infra \
  --context <agent-context> --tail=500 > otel-collector-logs.txt

문제 해결