본문으로 건너뛰기

10.3. 문제 해결

설치, 에이전트 연결, 데이터 미표시, 성능 관련 문제를 진단하고 해결하는 방법을 안내합니다.

개요​

OPENMARU Observability 사용 중 문제가 발생하면 이 문서를 참고하여 원인을 파악하고 해결하세요. 문제 유형별로 확인 순서와 조치 방법을 안내합니다.

참고: 이 문서의 kubectl 예시는 네임스페이스로 -n openmaru-observ 를 사용합니다. 다른 네임스페이스에 설치했다면 설치한 네임스페이스 이름으로 바꿔 실행하세요.

설치 관련 문제​

Pod가 시작되지 않거나 재시작을 반복합니다​

증상: kubectl get pods -n openmaru-observ 실행 시 Pod 상태가 Pending, CrashLoopBackOff, Error로 표시됩니다.

원인 및 조치:

  1. 스토리지 클래스 확인

    PersistentVolume 프로비저닝에 실패하면 Pod가 Pending 상태로 멈춥니다.

    kubectl get pvc -n openmaru-observ

    PVC 상태가 Pending이면 Helm 설치 시 지정한 스토리지 클래스가 클러스터에 존재하는지 확인하세요.

    kubectl get storageclass

    사용 가능한 스토리지 클래스 이름을 확인하고, values.yaml에서 스토리지 클래스 설정 값을 올바르게 지정한 뒤 재설치하세요.

    참고: Helm 차트의 기본 스토리지 클래스는 nfs-client입니다. 클러스터 환경에 맞는 스토리지 클래스로 변경해야 합니다.

  2. 리소스 부족 확인

    노드에 CPU 또는 메모리 여유가 없으면 Pod가 스케줄링되지 않습니다.

    kubectl describe pod <pod-name> -n openmaru-observ

    Insufficient cpu 또는 Insufficient memory 메시지가 보이면 클러스터 리소스를 확보하거나, values.yaml에서 각 컴포넌트의 리소스 요청량을 줄여 재설치하세요.

  3. 이미지 풀 실패 확인

    ImagePullBackOff 상태라면 컨테이너 이미지 레지스트리에 접근이 안 되는 것입니다.

    kubectl describe pod <pod-name> -n openmaru-observ

    Events 섹션에서 이미지 관련 오류 메시지를 확인하세요. 레지스트리 주소와 네트워크 연결을 확인합니다. 폐쇄망 환경이라면 이미지가 내부 레지스트리에 올바르게 등록되어 있는지 확인하세요.

    참고: 프라이빗 레지스트리를 사용하는 경우 values.yaml의 imagePullSecrets 설정이 필요합니다. Kubernetes Secret이 올바르게 생성되어 있는지 확인하세요.

  4. 서버 Pod 기동 시간 초과

    서버 Pod는 최초 기동 시 데이터베이스 마이그레이션 등 초기화 작업을 수행합니다. 최대 5분까지 기동 시간이 소요될 수 있으므로 충분히 기다린 후 상태를 확인하세요.

    서버 Pod가 계속 CrashLoopBackOff 상태라면 로그를 확인하세요.

    kubectl logs <server-pod-name> -n openmaru-observ

    PostgreSQL이나 ClickHouse 연결에 실패하는 경우가 대부분입니다. 해당 Pod가 먼저 정상 실행 중인지 확인하세요.

UI에 접속이 안 됩니다​

증상: 브라우저에서 OPENMARU Observability 주소로 접속했을 때 페이지가 열리지 않습니다.

원인 및 조치:

  1. Ingress 또는 Route 설정 확인

    Helm 설치 시 Ingress가 활성화되어 있는지 확인하세요.

    kubectl get ingress -n openmaru-observ

    Ingress 리소스가 없다면 values.yaml에서 Ingress를 활성화하여 재설치하세요.

    OpenShift 환경이라면 Route 리소스를 확인합니다.

    kubectl get route -n openmaru-observ

  2. Pod 상태 확인

    kubectl get pods -n openmaru-observ

    서버 및 UI Pod가 Running 상태인지 확인합니다. 비정상 상태라면 위의 Pod가 시작되지 않거나 재시작을 반복합니다 항목을 참고하세요.

  3. 서비스 연결 확인

    Pod 내부에서 서비스 간 연결이 정상적인지 확인합니다.

    kubectl get svc -n openmaru-observ

    UI Pod는 서버에 연결하여 데이터를 가져옵니다. 서버 서비스가 정상적으로 생성되어 있는지 확인하세요.

  4. 네트워크 연결 확인

    브라우저에서 서버 주소로 네트워크가 연결되는지 확인하세요. 방화벽이나 보안 그룹 설정으로 접속이 차단될 수 있습니다.

kube-state-metrics 관련 경고가 표시됩니다​

증상: 설정 > 시스템 설정 탭의 프로젝트 상태에서 kube-state-metrics 항목이 비정상으로 표시됩니다.

원인: kube-state-metrics가 클러스터에 설치되어 있지 않거나 접근이 불가한 경우입니다.

조치:

kubectl get pods -A | grep kube-state-metrics

kube-state-metrics가 없으면 먼저 설치하세요. kube-state-metrics는 Kubernetes 리소스 상태를 메트릭으로 노출하는 컴포넌트로, OPENMARU Observability가 애플리케이션 목록을 구성하는 데 필요합니다.

Helm 차트에 포함된 kube-state-metrics가 활성화되어 있는지도 확인하세요. values.yaml에서 해당 컴포넌트가 활성화 상태인지 확인합니다.

이미 설치되어 있는데도 경고가 표시된다면 VictoriaMetrics가 kube-state-metrics의 메트릭을 수집하고 있는지 확인하세요. kube-state-metrics Pod의 컨테이너 이름이 설정과 일치해야 합니다.

데이터베이스 연결 오류가 발생합니다​

증상: 서버 Pod 로그에 데이터베이스 연결 실패 메시지가 표시됩니다.

원인 및 조치:

  1. PostgreSQL Pod 상태 확인

    kubectl get pods -n openmaru-observ | grep postgres

    PostgreSQL Pod가 Running 상태인지 확인합니다. PostgreSQL은 최초 기동 시 초기화에 약 2분이 소요될 수 있습니다.

  2. ClickHouse Pod 상태 확인

    kubectl get pods -n openmaru-observ | grep clickhouse

    ClickHouse Pod가 Running 상태인지 확인합니다.

  3. 스토리지 상태 확인

    데이터베이스 Pod의 PersistentVolume이 정상적으로 바인딩되어 있는지 확인합니다.

    kubectl get pvc -n openmaru-observ

    PVC 상태가 Bound인지 확인하세요. 스토리지가 가득 찼다면 볼륨 크기를 늘리거나 불필요한 데이터를 정리해야 합니다.

  4. 데이터베이스 Pod 로그 확인

    데이터베이스 Pod 자체에 문제가 있을 수 있습니다. 로그를 확인하세요.

    kubectl logs <postgres-pod-name> -n openmaru-observ
    kubectl logs <clickhouse-pod-name> -n openmaru-observ

Helm 업그레이드 후 Pod가 비정상입니다​

증상: helm upgrade 실행 후 일부 Pod가 정상적으로 시작되지 않습니다.

원인 및 조치:

  1. 업그레이드 상태 확인

    helm status openmaru-observ -n openmaru-observ

    배포 상태가 deployed인지 확인합니다.

  2. Pod 이벤트 확인

    kubectl describe pod <pod-name> -n openmaru-observ

    Events 섹션에서 오류 원인을 확인하세요.

  3. 서버 Pod 순서 확인

    서버 Pod는 PostgreSQL과 ClickHouse가 먼저 정상 동작해야 합니다. 데이터베이스 Pod가 모두 Running 상태인지 확인한 후 서버 Pod를 재시작하세요.

    kubectl rollout restart statefulset <server-statefulset-name> -n openmaru-observ

에이전트 연결 문제​

노드 에이전트가 인식되지 않습니다​

증상: 설정 > 시스템 설정 탭의 프로젝트 상태에서 에이전트 항목이 비정상으로 표시됩니다. 노드 메뉴에 노드가 표시되지 않습니다.

원인 및 조치:

  1. API 키 확인

    노드 에이전트는 API 키로 인증합니다. 설정 > 시스템 설정 탭에서 API 키가 발급되어 있는지 확인하세요.

    에이전트 설치 시 올바른 API 키를 사용했는지 확인합니다. API 키를 새로 발급했다면 에이전트를 재배포해야 합니다.

  2. 서버 URL 확인

    에이전트가 OPENMARU Observability 서버에 접근할 수 있는 URL로 설정되어 있는지 확인하세요. 에이전트가 배포된 노드에서 서버 URL로의 네트워크 연결이 가능해야 합니다.

  3. 에이전트 Pod 상태 확인

    노드 에이전트를 DaemonSet으로 배포한 경우, 각 노드에서 에이전트 Pod가 정상 실행 중인지 확인하세요.

    kubectl get pods -n <에이전트가 배포된 네임스페이스> -o wide

    Pod가 비정상 상태라면 로그를 확인하세요.

    kubectl logs <pod-name> -n <네임스페이스>

  4. 커널 버전 확인

    노드 에이전트는 eBPF를 사용하므로 Linux 커널 4.16 이상이 필요합니다. 커널 버전이 이보다 낮으면 에이전트가 시작 시 종료됩니다.

    uname -r

  5. 보안 컨텍스트 확인

    노드 에이전트는 eBPF 프로그램을 로드하기 위해 privileged 모드로 실행되어야 합니다. 클러스터의 보안 정책(PodSecurityPolicy, PodSecurityStandard 등)이 privileged 모드를 허용하는지 확인하세요.

    에이전트 Pod에 필요한 볼륨 마운트가 정상인지도 확인합니다.

    • /host/sys/fs/cgroup (cgroup 파일시스템, 읽기 전용)
    • /sys/kernel/tracing (tracefs)
    • /sys/kernel/debug (debugfs)

  6. 에이전트 설치 후 대기

    에이전트를 처음 설치한 경우, 첫 번째 데이터가 전송되기까지 1~2분이 걸릴 수 있습니다. 잠시 기다린 후 설정 > 시스템 설정 탭을 새로고침하세요.

참고: 노드 에이전트의 시스템 요구사항은 Linux 운영체제와 커널 4.16 이상입니다. 커널 버전이 낮으면 eBPF 기반 데이터 수집이 동작하지 않습니다.

클러스터 에이전트가 연결되지 않습니다​

증상: 대시보드, 애플리케이션 목록 등 클러스터 수준의 데이터가 표시되지 않습니다.

원인 및 조치:

  1. 클러스터 에이전트 Pod 상태를 확인합니다.

    kubectl get pods -n openmaru-observ | grep cluster-agent

  2. Pod가 비정상 상태라면 로그를 확인합니다.

    kubectl logs <cluster-agent-pod-name> -n openmaru-observ

  3. values.yaml에서 아래 항목이 올바르게 설정되어 있는지 확인하세요.

    항목확인 내용
    클러스터 에이전트 서버 URL서버에 접근 가능한 URL인지 확인
    클러스터 에이전트 API 키유효한 API 키인지 확인

  4. 클러스터 에이전트에는 Kubernetes API에 접근하기 위한 권한이 필요합니다. ClusterRole과 ClusterRoleBinding이 정상적으로 생성되어 있는지 확인하세요.

    kubectl get clusterrole | grep cluster-agent
    kubectl get clusterrolebinding | grep cluster-agent

    클러스터 에이전트에 필요한 권한은 다음과 같습니다.

    • nodes, services, endpoints, pods, secrets (core API)
    • replicasets, deployments, statefulsets, daemonsets (apps API)
    • jobs, cronjobs (batch API)

OpenTelemetry 데이터가 수신되지 않습니다​

증상: OpenTelemetry SDK를 연동한 애플리케이션의 추적(Trace) 또는 로그(Log) 데이터가 분산추적 또는 로그 뷰어 메뉴에 표시되지 않습니다.

확인 순서:

  1. OTel Collector Pod 상태 확인

    kubectl get pods -n openmaru-observ | grep otel-collector

    OTel Collector Pod가 Running 상태인지 확인합니다.

  2. 엔드포인트 설정 확인

    애플리케이션의 OpenTelemetry SDK 설정에서 엔드포인트가 OTel Collector 서비스를 올바르게 가리키고 있는지 확인하세요. 분산추적 페이지 상단의 OpenTelemetry 통합 버튼을 클릭하면 올바른 엔드포인트 설정을 확인할 수 있습니다.

    OTel Collector는 다음 포트로 데이터를 수신합니다.

    • gRPC: 4317
    • HTTP: 4318

  3. API 키 확인

    OTel Collector가 OPENMARU Observability 서버에 데이터를 전송할 때 유효한 API 키가 필요합니다. values.yaml에서 API 키 설정을 확인하세요.

  4. 네트워크 연결 확인

    애플리케이션에서 OTel Collector까지, OTel Collector에서 OPENMARU Observability 서버까지 네트워크 연결이 가능한지 확인하세요.

  5. OTel Collector 로그 확인

    OTel Collector 로그에서 데이터 수신 및 전송 상태를 확인할 수 있습니다.

    kubectl logs <otel-collector-pod-name> -n openmaru-observ

    메모리 제한 초과로 인해 데이터가 유실되는 경우, values.yaml에서 OTel Collector의 메모리 제한을 늘려주세요.

데이터가 표시되지 않을 때​

대시보드에 클러스터 데이터가 없습니다​

증상: 대시보드의 클러스터 리소스 게이지나 상태 카드에 데이터가 표시되지 않습니다.

확인 순서:

  1. 실시간 연결 상태 확인

    대시보드 상단의 실시간 배지가 초록색인지 확인하세요. 회색이거나 오류 상태라면 서버와의 실시간 연결이 끊어진 것입니다. 페이지를 새로고침하면 자동으로 재연결을 시도합니다.

  2. 클러스터 에이전트 상태 확인

    위의 클러스터 에이전트가 연결되지 않습니다 항목을 참고하세요.

  3. kube-state-metrics 확인

    kube-state-metrics가 정상 동작하지 않으면 클러스터 상태 데이터를 수집할 수 없습니다. 위의 kube-state-metrics 관련 경고가 표시됩니다 항목을 참고하세요.

  4. VictoriaMetrics 상태 확인

    대시보드의 클러스터 리소스 데이터는 VictoriaMetrics에서 조회됩니다.

    kubectl get pods -n openmaru-observ | grep victoria-metrics

    VictoriaMetrics Pod가 정상 실행 중인지 확인하세요.

애플리케이션 목록이 비어 있습니다​

증상: 애플리케이션 메뉴를 클릭해도 목록에 아무것도 표시되지 않습니다.

확인 순서:

  1. 필터 확인

    페이지 상단의 필터(네임스페이스, 카테고리, 상태)에서 데이터를 걸러내고 있지 않은지 확인하세요. 필터를 모두 초기화하고 다시 확인하세요.

  2. 시간 범위 확인

    우측 상단의 시간 선택기에서 최근 1시간 또는 3시간으로 설정되어 있는지 확인하세요. 시간 범위가 너무 과거로 설정되어 있으면 데이터가 없을 수 있습니다.

  3. 클러스터 에이전트 및 kube-state-metrics 확인

    클러스터 에이전트와 kube-state-metrics가 정상 동작해야 애플리케이션 목록을 구성할 수 있습니다.

  4. 네임스페이스 확인

    모니터링 대상 네임스페이스에 실행 중인 워크로드가 있는지 확인하세요. 워크로드가 없는 네임스페이스에서는 애플리케이션이 표시되지 않습니다.

메트릭 차트에 데이터가 표시되지 않습니다​

증상: 애플리케이션 상세 페이지의 메트릭 탭이나 노드 상세 페이지에서 차트가 비어 있습니다.

확인 순서:

  1. 시간 범위 확인

    우측 상단의 시간 선택기에서 설정한 시간 범위에 데이터가 없을 수 있습니다. 에이전트를 막 설치한 경우, 최근 1시간 범위를 선택하세요.

  2. 노드 에이전트 상태 확인

    해당 노드에 에이전트가 설치되어 있고 정상 실행 중인지 확인하세요. 노드 메뉴에서 노드 목록과 상태를 확인할 수 있습니다.

  3. VictoriaMetrics(메트릭 저장소) 연결 상태 확인

    설정 > 시스템 설정 탭의 노드 상태 섹션에서 VictoriaMetrics 연결 상태가 정상인지 확인하세요. 메트릭(Metric) 데이터를 저장하는 시계열 데이터베이스(VictoriaMetrics)의 연결 상태를 나타냅니다.

    kubectl get pods -n openmaru-observ | grep victoria-metrics

  4. VictoriaMetrics 스크랩 대상 확인

    VictoriaMetrics가 에이전트 메트릭을 올바르게 수집하고 있는지 확인합니다. 노드 에이전트 Pod에 메트릭 스크랩 어노테이션이 설정되어 있어야 합니다.

로그가 표시되지 않습니다​

증상: 로그 뷰어 메뉴 또는 애플리케이션 상세 페이지의 로그 탭에 결과가 없습니다.

확인 순서:

  1. 필터 초기화

    로그 뷰어 상단의 애플리케이션 필터와 좌측 속성 필터 패널에서 설정된 조건을 확인하고, 의도치 않은 필터가 있으면 해제하세요.

  2. 심각도 필터 확인

    로그 레벨(ERROR, WARN, INFO, DEBUG) 필터에서 원하는 레벨이 선택되어 있는지 확인하세요.

  3. 시간 범위 확인

    우측 상단의 시간 선택기를 최근 1시간으로 설정하고 다시 조회하세요.

  4. 노드 에이전트 로그 수집 확인

    노드 에이전트가 정상 설치되어 있어야 컨테이너 로그가 수집됩니다. 로그 수집이 비활성화된 상태로 에이전트가 설치된 경우, 에이전트 설정을 확인하세요.

  5. ClickHouse 상태 확인

    로그 데이터는 ClickHouse에 저장됩니다. ClickHouse Pod가 정상 동작 중인지 확인하세요.

    kubectl get pods -n openmaru-observ | grep clickhouse

    ClickHouse 스토리지가 가득 찼다면 로그 조회가 실패할 수 있습니다. PVC 상태를 확인하세요.

  6. 로그 소스 확인

    애플리케이션 상세 페이지의 로그 탭에서는 로그 소스를 에이전트(agent) 또는 OpenTelemetry(otel)로 전환할 수 있습니다. 올바른 소스가 선택되어 있는지 확인하세요.

분산추적 데이터가 없습니다​

증상: 분산추적 메뉴에서 히트맵이나 추적(Trace) 목록이 비어 있습니다.

확인 순서:

  1. eBPF 자동 수집 확인

    노드 에이전트는 eBPF를 사용하여 HTTP 및 gRPC 트래픽을 자동으로 수집합니다. 커널 버전이 4.16 이상인 서버에서만 동작합니다. 서버의 커널 버전을 확인하세요.

    uname -r

  2. OpenTelemetry 연동 여부 확인

    보다 상세한 추적(Trace) 데이터를 수집하려면 OpenTelemetry SDK를 사용한 애플리케이션 계측이 필요합니다. 분산추적 페이지 상단의 OpenTelemetry 통합 버튼을 클릭하여 연동 방법을 확인하세요.

  3. 시간 범위 및 필터 확인

    시간 선택기와 필터 조건을 초기화하고 다시 조회하세요. 분산추적 화면에서는 서비스명, 스팬(Span)명, 상태 코드 등 다양한 필터를 사용할 수 있으므로, 필터가 적용되어 결과가 없는 것은 아닌지 확인하세요.

  4. ClickHouse 상태 확인

    추적(Trace) 데이터는 ClickHouse에 저장됩니다. ClickHouse가 정상 동작하지 않으면 분산추적 데이터를 조회할 수 없습니다.

참고: eBPF 기반 자동 수집은 애플리케이션 코드 수정 없이 동작합니다. OpenTelemetry 연동을 추가하면 함수 단위의 상세 스팬(Span) 데이터를 확인할 수 있습니다.

프로파일링 데이터가 없습니다​

증상: 애플리케이션 상세 페이지의 프로파일링 탭에서 플레임 그래프(Flame Graph)가 표시되지 않습니다.

확인 순서:

  1. 프로파일링 활성화 확인

    프로파일링은 기본적으로 활성화되어 있습니다. 애플리케이션 상세 페이지에서 프로파일링 설정을 확인하세요.

  2. 노드(서버) 에이전트 확인

    프로파일링 데이터는 각 노드의 노드 에이전트가 eBPF로 수집합니다. 노드 에이전트가 정상 동작 중인지 확인하세요. (특정 애플리케이션의 pprof 프로파일은 openmaru.io/profile-scrape: "true" 어노테이션을 붙인 경우 클러스터 에이전트가 추가로 스크랩합니다.)

  3. 시간 범위 확인

    시간 선택기에서 최근 1시간 범위를 선택하고 다시 조회하세요.

  4. 프로파일링 대상 확인

    프로파일링은 지원되는 런타임(Java, Go, Python, .NET, Node.js 등)에서 동작합니다. 모니터링 대상 애플리케이션이 프로파일링을 지원하는 런타임인지 확인하세요.

토폴로지 맵에 서비스가 표시되지 않습니다​

증상: 토폴로지 맵 메뉴에서 서비스 간 연결 그래프가 비어 있습니다.

확인 순서:

  1. 실시간 연결 상태 확인

    토폴로지 맵 상단의 실시간 배지가 초록색인지 확인하세요.

  2. 노드 에이전트 확인

    서비스 간 연결 정보는 노드 에이전트의 eBPF 기반 TCP 연결 추적으로 수집됩니다. 노드 에이전트가 모든 노드에 정상 설치되어 있는지 확인하세요.

  3. 트래픽 발생 여부 확인

    서비스 간 트래픽이 발생하지 않으면 토폴로지 맵에 연결이 표시되지 않습니다. 애플리케이션에 실제 요청이 발생하고 있는지 확인하세요.

성능 관련 문제​

대시보드 로딩이 느립니다​

증상: 대시보드 또는 각 메뉴 화면이 로드되는 데 오래 걸립니다.

원인 및 조치:

  1. 서버 리소스 확인

    OPENMARU Observability 서버 Pod의 CPU, 메모리 사용률을 확인하세요.

    kubectl top pods -n openmaru-observ

    리소스 사용률이 높다면 values.yaml에서 서버의 리소스 요청량을 늘리거나, 서버 복제본 수를 늘려 재설치하세요.

  2. ClickHouse 상태 확인

    로그, 추적(Trace), 프로파일링 데이터를 저장하는 ClickHouse의 스토리지 사용량이 높으면 조회 성능이 저하될 수 있습니다.

    kubectl get pvc -n openmaru-observ | grep clickhouse

    스토리지 사용량이 높다면 values.yaml에서 ClickHouse 볼륨 크기를 늘려 재설치하거나, 데이터 저장기간을 조정하여 오래된 데이터가 자동 삭제되도록 설정하세요.

  3. VictoriaMetrics 스토리지 확인

    메트릭(Metric) 데이터를 저장하는 VictoriaMetrics의 스토리지도 확인하세요. 스토리지가 부족하면 메트릭 조회 성능이 저하됩니다.

    kubectl get pvc -n openmaru-observ | grep victoria-metrics

  4. 조회 시간 범위 조정

    한 번에 조회하는 시간 범위가 넓을수록 처리량이 늘어납니다. 시간 선택기에서 조회 범위를 좁혀 성능을 개선할 수 있습니다.

참고: 애플리케이션 상세 페이지에서 3일을 초과하는 범위를 선택하더라도 3일 데이터까지만 표시되며('3일 제한' 배지가 함께 표시됩니다), 이는 원시 메트릭 보관 기간(VictoriaMetrics 기본 3일) 때문입니다.

에이전트가 서버 리소스를 과도하게 사용합니다​

증상: 노드 에이전트가 설치된 노드의 CPU 또는 메모리 사용률이 높아집니다.

원인 및 조치:

  1. 수집 주기 조정

    메트릭 수집 주기를 늘리면 에이전트 리소스 사용량을 줄일 수 있습니다. Helm 설치 시 메트릭 수집 간격 값을 기본값(15s)보다 크게 설정하세요.

  2. L7 추적 비활성화

    네트워크 트래픽이 많은 환경에서는 eBPF 기반 L7 추적이 상당한 리소스를 사용할 수 있습니다. 추적이 불필요한 경우 에이전트 설정에서 L7 추적을 비활성화할 수 있습니다.

  3. 로그 파싱 비활성화

    컨테이너 로그가 매우 많은 환경에서는 로그 파싱을 비활성화하여 에이전트 부하를 줄일 수 있습니다.

  4. 리소스 제한 설정

    노드 에이전트의 리소스 제한이 적절한지 확인하세요. values.yaml에서 에이전트의 CPU 및 메모리 제한량을 환경에 맞게 조정할 수 있습니다. 기본 설정은 요청(request) CPU 500m·메모리 500Mi, 제한(limit) 메모리 4Gi입니다(CPU 제한은 없음).

  5. 버퍼 디스크 사용량 확인

    노드 에이전트는 데이터 전송에 실패할 경우 로컬 디스크에 임시로 버퍼링합니다. 서버 연결 문제가 지속되면 디스크 사용량이 증가할 수 있습니다. 서버 연결 상태를 먼저 확인하세요.

ClickHouse 스토리지가 빠르게 증가합니다​

증상: ClickHouse PVC의 스토리지 사용량이 예상보다 빠르게 증가합니다.

원인 및 조치:

  1. 데이터 저장기간 확인

    로그, 추적(Trace), 프로파일링 데이터의 저장기간(TTL) 설정을 확인하세요. 저장기간을 줄이면 오래된 데이터가 자동으로 삭제됩니다.

  2. 로그 발생량 확인

    애플리케이션에서 과도한 로그를 생성하고 있는지 확인하세요. 로그 뷰어에서 로그 패턴을 분석하여 불필요하게 많은 로그를 생성하는 애플리케이션을 식별할 수 있습니다.

  3. 스토리지 용량 증가

    values.yaml의 openmaruObservClickhouse.persistentVolume.size로 볼륨 크기를 조정합니다. 기본값은 300Gi이며, 로그와 추적 데이터가 많은 환경에서는 더 큰 용량이 필요합니다. 규모별 권장값은 설치 장의 용량 산정 표를 참고하세요.

커스텀 대시보드 로그 패널이 비어 있거나 경고가 뜹니다​

증상: 커스텀 대시보드의 로그 패널에 데이터가 없거나, "고유값이 많다"는 경고가 표시됩니다.

원인 및 조치:

  1. ClickHouse 구성 확인

    로그·감사 로그 데이터소스는 ClickHouse가 있어야 동작합니다. 템플릿 갤러리에서는 ClickHouse가 없으면 로그 템플릿이 아예 보이지 않지만, 패널 편집기에서는 고를 수 있습니다. 골랐는데 계속 비어 있다면 구성 여부를 먼저 확인하세요.

  2. 집계 기준 좁히기

    고유값이 아주 많은 항목(예: 요청 ID)을 집계 기준으로 고르면 경고가 표시됩니다. 막대가 수천 개로 늘어나 읽을 수 없으므로 기준을 바꾸거나 필터로 범위를 좁히세요.

  3. 조회 범위 확인

    조회 범위가 넓으면 서버가 최대 24시간으로 줄여서 집계합니다. 그보다 긴 기간은 표시되지 않습니다.

커스텀 대시보드 실시간 위젯이 움직이지 않습니다​

증상: 커스텀 대시보드에 올린 요청 뷰어나 실시간 요청 모니터가 정지해 보입니다.

원인 및 조치:

  1. 패널 크기 확인

    가로 160px·세로 72px보다 작으면 애니메이션이 멈춥니다. 패널을 키워 보세요.

  2. 트래픽 확인

    실시간 위젯은 지금 흐르는 요청을 그립니다. 해당 네임스페이스에 트래픽이 없으면 비어 있는 것이 정상입니다.

  3. 대시보드당 상한 확인

    한 대시보드에 놓을 수 있는 실시간 위젯은 서로 다른 필터 조합 3개까지입니다. 상한을 넘기면 새 패널을 만들 때 데이터소스 목록에서 비활성으로 표시되고 사유가 함께 나옵니다.

VictoriaMetrics 스토리지 부족​

증상: VictoriaMetrics Pod가 재시작되거나, 메트릭 차트에서 데이터가 누락됩니다.

원인 및 조치:

  1. PVC 용량 확인

    kubectl get pvc -n openmaru-observ | grep victoria-metrics

  2. 보존 기간 확인

    VictoriaMetrics의 기본 데이터 보존 기간은 3일입니다(--retentionPeriod=3d). 보존 기간을 늘리거나 스토리지가 부족하면 PVC 용량을 조정하세요. 기본 크기는 10Gi입니다.

  3. 메트릭 수집 대상 확인

    불필요한 메트릭을 수집하고 있는지 확인하세요. 모니터링 대상이 아닌 애플리케이션이 메트릭을 과도하게 노출하는 경우 스토리지 사용량이 증가할 수 있습니다.

화면 관련 문제​

실시간 연결(Live) 상태가 유지되지 않습니다​

증상: 대시보드 또는 토폴로지 맵 상단의 실시간 배지가 회색으로 표시되거나 계속 재연결을 시도합니다.

원인 및 조치:

  1. 인증서 경고를 넘기고 접속한 환경인지 확인하세요. 사내 인증 기관(CA) 인증서를 브라우저 신뢰 목록에 등록하지 않고 고급 > 계속 진행으로 접속했다면, 그 허용은 7일 후 사라집니다. 허용이 사라지면 실시간 연결만 조용히 끊어집니다. 아래 인증서 경고 화면이 표시됩니다 항목을 참고하세요.
  2. 서버와 UI 사이에 Ingress 또는 프록시가 있는 경우, WebSocket 연결(ws:// 또는 wss://)을 허용하는지 확인하세요.
  3. 프록시의 연결 타임아웃 설정이 너무 짧으면 WebSocket 연결이 자주 끊어질 수 있습니다. 타임아웃 시간을 늘려주세요.
  4. 방화벽이 WebSocket 연결을 차단하고 있지 않은지 확인하세요.

페이지에 재연결 버튼이 표시된 경우, 버튼을 클릭하여 즉시 재연결을 시도할 수 있습니다. 새로고침으로도 재연결이 가능합니다.

인증서 경고 화면이 표시됩니다​

증상: 접속할 때 "연결이 비공개로 설정되어 있지 않습니다" 경고 화면과 함께 NET::ERR_CERT_AUTHORITY_INVALID 오류가 표시됩니다. 며칠 잘 쓰다가 다시 나타나기도 합니다.

원인: 사내 인증 기관(CA)이 발급한 인증서를 접속 PC가 신뢰 목록에 가지고 있지 않습니다. 인증서 자체에는 문제가 없으며, PC가 그 발급 기관을 모르는 상태입니다.

경고 화면에서 고급 > 계속 진행을 누르면 접속은 되지만, 이는 7일간만 유지되는 임시 허용입니다. 7일이 지나면 다시 경고가 표시되고, 그 사이에 실시간 연결이 먼저 끊어집니다. 페이지를 다시 열거나 새로고침해도 허용 기간은 연장되지 않습니다.

조치: 사내 루트 CA 인증서를 PC의 신뢰 목록에 등록하면 재발하지 않습니다. Windows·macOS별 상세 절차는 설치의 브라우저 인증서 신뢰 설정 절을 참고하세요.

접속 PC가 많다면 Windows 그룹 정책으로 일괄 배포할 수 있습니다. 같은 절에 절차가 있습니다.

참고: 접속하는 클러스터가 여러 개면 클러스터마다 인증서가 다릅니다. 한 환경에 등록했어도 다른 환경에서는 경고가 그대로 표시됩니다.

알림이 발송되지 않습니다​

증상: 인시던트가 발생해도 Slack, Teams 등으로 알림이 오지 않습니다.

확인 순서:

  1. 알림 채널 설정 확인

    설정 > 알림채널 연결 탭에서 알림 채널이 연결되어 있는지 확인하세요. 채널 연결 상태가 체크 표시로 표시되어 있어야 합니다.

  2. Base URL 설정 확인

    설정 > 알림채널 연결 탭의 Base URL 필드에 외부에서 접근 가능한 OPENMARU Observability URL이 입력되어 있는지 확인하세요. 이 값이 없으면 알림 메시지의 링크가 정상적으로 생성되지 않을 수 있습니다.

  3. Webhook URL 유효성 확인

    Slack 또는 Teams Webhook URL이 유효한지 확인하세요. Webhook URL이 변경되었다면 설정 > 알림채널 연결 탭에서 다시 설정하세요.

  4. 알림 대상 이벤트 확인

    알림 채널 설정에서 인시던트 알림 및 배포 알림 옵션이 활성화되어 있는지 확인하세요.

  5. 테스트 알림 발송

    설정 > 알림채널 연결 탭에서 테스트 알림을 발송하여 채널 연동이 정상인지 확인할 수 있습니다.

  6. 서버 네트워크 확인

    OPENMARU Observability 서버에서 외부 Webhook URL로의 네트워크 연결이 가능한지 확인하세요. 폐쇄망 환경에서는 외부 Webhook 서비스로의 아웃바운드 연결이 차단될 수 있습니다.

인시던트가 생성되지 않습니다​

증상: 애플리케이션에 오류가 발생하고 있지만 인시던트 메뉴에 인시던트가 표시되지 않습니다.

확인 순서:

  1. 검사 조건 설정 확인

    설정 > 검사 조건 설정 탭에서 검사 조건이 활성화되어 있는지 확인하세요. 검사 조건의 임계값이 적절하게 설정되어 있어야 인시던트가 생성됩니다.

  2. 해결됨 토글 확인

    인시던트 메뉴에서 해결됨 토글이 꺼져 있으면 이미 해결된 인시던트가 숨겨집니다. 토글을 켜서 전체 인시던트를 확인하세요.

  3. 에이전트 상태 확인

    노드 에이전트가 정상 동작해야 메트릭 데이터를 기반으로 검사 조건을 평가할 수 있습니다. 에이전트 연결 상태를 확인하세요.

  4. SLO 설정 확인

    인시던트는 SLO 위반을 기반으로 생성됩니다. 애플리케이션 상세 페이지에서 SLO 설정(가용성 목표, 응답 시간 목표)이 올바르게 설정되어 있는지 확인하세요.

진단 명령어 모음​

자주 사용하는 진단 명령어를 정리합니다.

전체 Pod 상태 확인​

kubectl get pods -n openmaru-observ

특정 Pod 상세 정보 확인​

kubectl describe pod <pod-name> -n openmaru-observ

Pod 로그 확인​

# 최근 로그
kubectl logs <pod-name> -n openmaru-observ

# 이전 Pod 로그 (재시작된 경우)
kubectl logs <pod-name> -n openmaru-observ --previous

PVC 상태 확인​

kubectl get pvc -n openmaru-observ

서비스 상태 확인​

kubectl get svc -n openmaru-observ

리소스 사용량 확인​

kubectl top pods -n openmaru-observ

Ingress 또는 Route 확인​

# Kubernetes Ingress
kubectl get ingress -n openmaru-observ

# OpenShift Route
kubectl get route -n openmaru-observ

RBAC 리소스 확인​

kubectl get clusterrole | grep openmaru
kubectl get clusterrolebinding | grep openmaru

그래도 해결되지 않는 경우​

위의 방법으로 해결되지 않는 경우, 아래 정보를 수집하여 OPENMARU 기술 지원팀에 문의하세요.

  • OPENMARU Observability 버전 (화면 좌측 하단의 버전 정보 확인)
  • Kubernetes 버전 (kubectl version)
  • 문제가 발생하는 메뉴 및 재현 방법
  • 관련 Pod 로그 (kubectl logs <pod-name> -n openmaru-observ)
  • 관련 Pod 이벤트 (kubectl describe pod <pod-name> -n openmaru-observ)

관련 문서​

  • 빠른 시작 - 처음 설치 및 설정
  • 설치 - 시스템 요구사항 및 설치 옵션
  • 설정 - API 키 관리, 알림 채널, 사용자 관리
  • 노드 - 노드 상태 및 에이전트 확인
  • 분산추적 - OpenTelemetry 연동 및 추적 데이터 분석
  • 로그 뷰어 - 로그 검색 및 필터링