Codex를 사용하여 CTO급 Grafana 대시보드를 구축한 방법

좋은 대시보드는 차트의 벽이 아닙니다. 그것은 질문에 대한 답변입니다.

저희에게 질문은 간단했습니다:

프로덕션(Production)이 건강한가? 만약 그렇지 않다면, 어디를 가장 먼저 살펴봐야 하는가?

저희는 이미 일반적인 관측성 (Observability) 요소들을 갖추고 있었습니다: 애플리케이션 메트릭 (Application metrics), 호스트 메트릭 (Host metrics), 컨테이너 메트릭 (Container metrics), 구조화된 로그 (Structured logs), 트레이스 (Traces), 합성 체크 (Synthetic checks), 그리고 데이터베이스 텔레메트리 (Database telemetry)까지 말이죠. 어려운 점은 더 많은 데이터를 수집하는 것이 아니었습니다. 어려운 점은 그 데이터를 기술 리더가 평상시나 배포 시, 또는 장애 발생 시에 열어보고 시스템의 상태를 빠르게 이해할 수 있는 대시보드로 전환하는 것이었습니다.

Grafana는 저희에게 관측성 플랫폼을 제공했습니다. Codex는 대시보드가 정직하고, 작고, 테스트되었으며, 코드베이스와 일치하도록 유지하는 데 도움을 주었습니다.

이것은 저희가 최종적으로 도달한 플레이북 (Playbook)입니다.

차트가 아닌 결정사항부터 시작하라

거의 모든 대시보드의 첫 번째 버전은 다음과 같이 누적되며 성장합니다:

• CPU 차트
• 메모리 (Memory) 차트
• 요청률 (Request rate) 차트
• 지연 시간 (Latency) 차트
• 에러 (Error) 차트
• 데이터베이스 (Database) 차트
• 워커 (Worker) 차트
• 로그 (Logs) 차트
• 또 다른 지연 시간 (Latency) 차트

이것은 탐색에는 유용하지만, 훌륭한 최상위 운영 뷰 (Top-level operational view)는 아닙니다.

저희의 CTO 대시보드를 위해, 저희는 결정사항부터 시작했습니다:

• 퍼블릭 API (Public API)에 접속 가능한가?
• 트래픽을 중복성 있게 처리할 만큼 충분한 API 노드들이 살아있는가?
• 워커 (Workers)들이 살아있고 유용한 데이터를 생성하고 있는가?
• PostgreSQL이 건강한가?
• 알람 (Alerts)이 울리고 있는가?
• 관측성 (Observability) 자체가 작동하고 있는가?
• 무언가 느리다면, 그것이 API인가, 워커인가, 데이터베이스인가, 로그인가, 아니면 트레이싱 (Tracing)인가?

이러한 질문들을 적어 내려간 후에야 비로소 패널 (Panels)을 선택했습니다.

이 단 한 번의 변화가 대시보드를 훨씬 더 작게 만들었습니다.

제품의 건강 상태와 관측성 커버리지를 분리하라

가장 중요한 설계 선택 중 하나는 이 두 가지 아이디어를 분리하는 것이었습니다:

1. 제품 건강 상태 (Product health): 서비스가 사용자들에게 제대로 작동하고 있는가?
2. 관측성 커버리지 (Observability coverage): 우리가 서비스를 명확하게 볼 수 있는가?

이 둘은 서로 연관되어 있지만, 동일한 것은 아닙니다.

만약 하나의 호스트에서 observability agent (관측성 에이전트)의 보고가 중단된다면, 그것은 좋지 않은 상황입니다. 하지만 그렇다고 해서 제품이 다운된 것처럼 자동으로 표시되어서는 안 됩니다. 마찬가지로, metrics pipeline (메트릭스 파이프라인)이 여전히 정상(green)이라고 해서 API 장애가 숨겨져서는 안 됩니다.

따라서 우리의 최상위 대시보드(top-level dashboard)는 다음과 같이 별도의 영역을 가집니다:

• production health (운영 상태)
• observability coverage (관측성 커버리지)
• API node readiness (API 노드 준비 상태)
• worker health (워커 상태)
• database health (데이터베이스 상태)
• alerts and drill-down links (알림 및 상세 분석 링크)

이를 통해 장애(incident) 발생 시 원인을 파악하기가 더 쉬워집니다. 모니터링 경로가 고장 난 것은 가시적으로 드러나지만, 그것이 제품 장애인 것처럼 위장하지는 않습니다.

Grafana 자산을 코드처럼 관리하기

가장 큰 품질의 도약은 우리가 Grafana를 브라우저 전용 편집 도구로 취급하는 것을 그만두었을 때 찾아왔습니다.

우리의 대시보드, alert rules (알림 규칙), synthetic checks (합성 체크), collector configs (수집기 설정)는 git에 저장됩니다:

ops/grafana/
  dashboards/
  alerts/
...

이를 통해 우리는 일반적인 엔지니어링 제어 기능을 사용할 수 있습니다:

• pull requests (풀 리퀘스트)
• code review (코드 리뷰)
• CI checks (CI 체크)
• repeatable sync (반복 가능한 동기화)
• history (이력)
• rollback (롤백)

대시보드 JSON은 보기 좋지 않지만, 엄연한 운영 동작(production behavior)입니다. 만약 이것이 장애 발생 시 엔지니어가 보는 내용을 결정한다면, 애플리케이션 코드와 동일한 수준의 리뷰 규율을 적용받아야 마땅합니다.

Grafana의 MCP는 실제로 유용합니다

긍정적인 의미에서 우리를 놀라게 했던 한 가지는 Grafana의 MCP 통합이 단순한 장난감이 아니었다는 점입니다.

이는 실제 대시보드 작업에 도움이 될 만큼 충분히 실용적이었습니다:

• 대시보드 및 패널 찾기
• datasource-backed queries (데이터 소스 기반 쿼리) 조사
• alerting (알림) 및 대시보드 구조 확인
• Grafana 컨텍스트와 리포지토리(repository) 컨텍스트 간의 이동
• 운영상의 질문을 구체적인 대시보드 변경 사항으로 전환

이것이 중요한 이유는 AI 보조 도구가 단순히 내보내진 JSON만을 보고 추측하는 대신, 실제 observability system (관측성 시스템)을 조사할 수 있을 때 훨씬 더 나아지기 때문입니다. Grafana MCP는 Codex가 실행 중인 운영 환경과 연결되어 있다는 느낌을 주는 동시에, 리포지토리는 여전히 신뢰할 수 있는 단일 원천(source of truth)으로 유지되게 했습니다.

우리는 또한 다른 관측성 (observability) 벤더들의 유사한 MCP 스타일 통합 방식도 시도해 보았습니다. 평가 결과, Grafana의 방식이 일상적인 엔지니어링 작업에 가장 유용하고 신뢰할 수 있었습니다. New Relic을 포함한 일부 대안들은 우리의 워크플로우에 적용하기에는 아직 충분히 성숙하지 않다고 느껴졌기에, 현재 시점에서 이를 주요 AI-관측성 (AI-observability) 인터페이스로 채택하는 것은 추천하지 않습니다.

상황은 변할 수 있겠지만, 만약 제가 지금 이 시스템을 다시 구축한다면 Grafana로 시작할 것입니다.

수집 레이어로 Grafana Alloy 사용하기

Grafana Alloy는 우리 프로덕션 텔레메트리 (telemetry)를 위한 에지 수집기 (edge collector)가 되었습니다.

대략적인 파이프라인 구조는 다음과 같습니다:

application metrics
host metrics
container metrics
...

Alloy를 사용하면 수집 프로필을 명시적으로 유지할 수 있습니다:

• 호스트 및 컨테이너 메트릭 (metrics) 스크래핑 (scrape)
• 커스텀 워커 상태를 위한 텍스트 파일 메트릭 수집
• 구조화된 로그 (structured logs) 전달
• OTLP 트레이스 (traces) 수신
• 메트릭 원격 쓰기 (remote-write)
• 데이터가 호스트를 떠나기 전 리레이블링 (relabeling) 및 카디널리티 (cardinality) 제어 적용

중요한 교훈은 다음과 같습니다: 수집기 설정을 제품의 일부로 취급하십시오. 이 설정이 장애 발생 시 당신이 무엇을 볼 수 있고 무엇을 볼 수 없는지를 정의합니다.

SLI를 위한 메트릭, 조사를 위한 로그 및 트레이스

우리는 로그 파싱 (log parsing)을 통해 핵심 서비스 수준 지표 (SLI, service-level indicators)를 구축하지 않으려 노력합니다.

최상위 API 상태 확인에는 메트릭이 적절한 소스입니다:

rate(api_requests_total[5m])
rate(api_request_duration_seconds_bucket[5m])

로그는 여전히 중요하지만, 다음과 같은 질문에 답하는 데 더 적합합니다:

• 어떤 요청이 실패했는가?
• 어떤 워커 사이클이 실패했는가?
• 어떤 트레이스 ID (trace ID)가 API, 워커, 데이터베이스의 동작을 연결하는가?
• 당시 애플리케이션은 무엇이라고 말했는가?

트레이스는 메트릭과 로그 다음 단계입니다:

• 어떤 경로 (route)가 느렸는가?
• 시간이 어디에서 소모되었는가?
• 데이터베이스가 요청 시간을 지배했는가?
• 문제가 하나의 워커 또는 하나의 의존성 (dependency)에 국한되었는가?

최상위 대시보드는 이러한 도구들을 가리켜야 합니다. 도구들을 대체하려고 해서는 안 됩니다.

인프라 메트릭뿐만 아니라 도메인 메트릭 추가하기

인프라 메트릭 (Infrastructure metrics)은 머신이 살아있는지 여부를 알려줍니다.

하지만 비즈니스 프로세스가 유용한지를 항상 알려주는 것은 아닙니다.

워커 시스템 (worker systems)을 위해 우리는 다음과 같은 도메인 특화 메트릭 (domain-specific metrics)을 추가했습니다:

• 워커 생존 여부 (worker alive)
• 하트비트 연령 (heartbeat age)
• 마지막 사이클 상태 (last cycle status)
• 마지막 사이클 지속 시간 (last cycle duration)
• 최신 사이클에서 생산된 항목 (items produced in the latest cycle)
• 최근 윈도우 동안 관찰된 항목 (items observed over recent windows)
• 연속 실패 횟수 (consecutive failures)

이것이 중요한 이유는 워커가 기술적으로는 살아있더라도 여전히 유용한 출력을 생성하지 않을 수 있기 때문입니다.

이러한 구분은 우리 알림 (alerts)의 품질을 변화시켰습니다. 우리는 다음과 같은 상황에 대해 알림을 보낼 수 있었습니다:

워커는 살아있지만

assert "worker_type" in query
assert "analytics_rollup" not in mention_panel_series

실제로 적용되는 테스트는 이보다 조금 더 견고하지만, 핵심 아이디어는 간단합니다. 바로 의도(intent)를 인코딩하는 것입니다.

Codex가 가장 큰 도움이 되었던 부분

Codex는 단일 파일 내부뿐만 아니라 리포지토리(repo) 전체를 가로질러 작업할 수 있었기에 유용했습니다.

대시보드 변경은 종종 여러 곳을 건드립니다:

• 대시보드 JSON (dashboard JSON)
• 알림 YAML (alert YAML)
• 수집기 설정 (collector config)
• 메트릭 작성 스크립트 (metric writer script)
• 테스트 (tests)
• 문서 (docs)
• 배포 동기화 로직 (deployment sync logic)

Codex는 이러한 관계를 조사하여, 겉보기에는 올바르지만 전체 시스템을 망가뜨릴 수 있는 국소적인 수정(local-only fixes)을 피할 수 있었습니다.

가장 효과적인 워크플로우는 다음과 같습니다:

1. 운영상의 문제를 평이한 언어로 기술합니다.
2. Codex에게 관련 리포지토리 경로를 조사하도록 요청합니다.
3. 범위가 좁은 작은 차이(diff)를 요구합니다.
4. 테스트를 요구합니다.
5. 프로덕션 코드처럼 PromQL 및 대시보드 의미론(semantics)을 검토합니다.

Codex는 운영적 판단(operational judgment)을 대체하는 것이 아닙니다. 그 판단을 일관되게 적용할 수 있도록 돕는 매우 빠른 조수입니다.

우리가 권장하는 대시보드 아키텍처

프로덕션 서비스의 경우, 저는 Grafana를 다음과 같이 구성하겠습니다:

1. CTO 개요 (CTO Overview)

최상위 대시보드는 다음 질문에 답할 수 있어야 합니다:

• 프로덕션이 건강한가?
• 사용자가 영향을 받고 있는가?
• 알림(alerts)이 발생하고 있는가?
• 트래픽을 처리하는 노드가 충분한가?
• 워커(workers)가 유용한 출력을 생성하고 있는가?
• 데이터베이스가 건강한가?
• 관측성(observability) 커버리지가 온전한가?

이 대시보드는 짧게 유지하십시오.

2. 프로덕션 인프라 (Production Infrastructure)

여기에 다음 항목을 배치합니다:

• 호스트 CPU 및 메모리 (host CPU and memory)
• 컨테이너 CPU 및 메모리 (container CPU and memory)
• 디스크 사용량 (disk usage)
• 프로세스 신선도 (process freshness)
• 컨테이너 신선도 (container freshness)
• 에이전트 상태 (agent health)

3. 데이터베이스 성능 (Database Performance)

여기에 다음 항목을 배치합니다:

• 연결 사용량 (connection usage)
• 캐시 히트율 (cache hit ratio)
• 락 압박 (lock pressure)
• 트랜잭션 비율 (transaction rate)
• 임시 파일 변동 (temp file churn)
• 느린 쿼리 그룹 (slow query groups)
• 테이블 압박 (table pressure)
• 상위 쿼리 지문 (top query fingerprints)

4. 트레이싱 (Tracing)

여기에 다음 항목을 배치합니다:

• 수락된 스팬 (accepted spans)
• 실패한 내보내기 (failed exports)
• 느린 API 트레이스 (slow API traces)
• 최근 워커 트레이스 (recent worker traces)
• 데이터베이스 스팬 (database spans)

5. 합성 모니터링 (Synthetic Monitoring)

여기에 다음 항목들을 포함합니다:

• 공개 생존 여부 (public liveness)
• 준비 상태 (readiness)
• 심층 상태 확인 (deeper health checks)
• 멀티 리전 지연 시간 (multi-region latency)

개요(overview)는 진단 대시보드(diagnostic dashboards)로 연결됩니다. 개요가 모든 대시보드의 역할을 대신하려고 해서는 안 됩니다.

보안 및 카디널리티 규칙 (Security And Cardinality Rules)

공개적인 글이라면 다음과 같이 명확히 말해야 합니다: 주의를 기울이지 않으면 관찰 가능성 (observability) 도구가 데이터를 유출할 수 있습니다.

우리의 규칙:

• 레이블 (labels)에 API 키를 절대 넣지 마십시오.
• 레이블에 고객 식별자 (customer identifiers)를 절대 넣지 마십시오.
• 쿼리 문자열이 포함된 원시 URL (raw URLs)을 레이블에 절대 넣지 마십시오.
• Prometheus 레이블에 요청 ID (request IDs)나 트레이스 ID (trace IDs)를 절대 넣지 마십시오.
• 대시보드 JSON에 비밀 정보 (secrets)를 포함하지 마십시오.
• 수집기 자격 증명 (collector credentials)을 git 외부에 유지하십시오.
• 원시 경로 (raw paths) 대신 라우트 템플릿 (route templates)을 사용하십시오.
• 제한된 열거형 레이블 (bounded enum labels)을 선호하십시오.
• 원격 쓰기 (remote write) 전에 고카디널리티 (high-cardinality) 메트릭을 삭제하거나 피하십시오.

로그 (logs)와 트레이스 (traces)는 더 풍부한 컨텍스트를 포함할 수 있지만, 그 경우에도 신중해야 합니다. 모든 필드를 레이블로 승격시키는 것보다 쿼리 시점 파싱 (Query-time parsing)이 종종 더 안전합니다.

실무 팁 (Practical Tips)

어떤 팀에서든 재사용할 수 있는 규칙들입니다.

대시보드의 목표를 먼저 작성하십시오

패널 (panels)을 추가하기 전에, 한 문장을 작성하십시오:

이 대시보드는 우리가 ...를 결정하는 데 도움을 주기 위해 존재한다.

이 문장을 완성할 수 없다면, 당신은 대시보드가 아니라 차트 모음집을 만들고 있는 것일 가능성이 높습니다.

지루한 이름을 사용하십시오

패널 이름은 운영상 명확해야 합니다:

• API 5xx 에러율 (API 5xx Error Rate)
• API 노드 준비 완료 (API Nodes Ready)
• 워커 생존 (Workers Alive)
• PostgreSQL 연결 (PostgreSQL Connections)
• 워커 하트비트 경과 시간 (Worker Heartbeat Age)

기발한 이름은 피하십시오. 장애 상황 (incidents) 중에 아무도 시를 해독하고 싶어 하지 않습니다.

적은 수의 패널을 선호하십시오

최고의 개요 대시보드는 사람들이 실제로 사용하는 대시보드입니다.

만약 특정 패널이 의사결정을 바꾸지 못한다면, 이를 상세 분석 대시보드 (drill-down dashboard)로 옮기십시오.

링크를 추가하십시오

모든 최상위 패널에는 명확한 다음 이동 경로가 있어야 합니다:

• 운영 개요 (production overview)
• 데이터베이스 대시보드 (database dashboard)
• 트레이싱 대시보드 (tracing dashboard)
• 로그 탐색 (logs exploration)
• 런북 (runbook)

의도를 테스트하십시오

JSON 유효성만 테스트하지 마십시오.

그 의미를 테스트하십시오:

• 이 패널은 API 메트릭 (API metrics) 데이터 소스를 사용합니다
• 이 알람 (alert)은 고정된 UID를 가집니다
• 이 워커 (worker)는 이 비즈니스 메트릭 (business metric)에서 제외됩니다
• 이 지연 시간 (latency) 알람은 트래픽 하한선 (traffic floor)을 가집니다
• 이 대시보드는 더 이상 사용되지 않는 (deprecated) 메트릭에 의존하지 않습니다

수동 편집은 임시로 유지하십시오

Grafana를 수동으로 편집하는 것은 탐색을 위해 매우 유용합니다. 하지만 그것은 신뢰할 수 있는 단일 원천 (source of truth)이 아닙니다.

패널이 중요해지면, 이를 내보내고 (export), 커밋 (commit)하고, 리뷰 (review)한 뒤, 코드로부터 동기화하십시오.

"완벽함"의 의미

완벽한 대시보드는 가장 거대한 대시보드가 아닙니다.

모든 패널이 그 자리에 있을 가치를 증명하는 대시보드입니다.

저희에게 그것은 다음과 같은 의미였습니다:

• 상태 확인을 위한 메트릭 (metrics)
• 상세 내용을 위한 로그 (logs)
• 인과 관계를 위한 트레이스 (traces)
• 실행(action)과 연결된 알람 (alerts)
• git에 저장된 대시보드
• 대시보드의 의미를 보호하는 테스트
• 변경 사항을 작고 일관되게 유지하도록 돕는 Codex

Grafana는 시스템을 가시화했습니다. Codex는 그 가시성을 유지 가능하게(maintainable) 만들도록 도왔습니다. 이 결합을 통해 관측성 (observability)은 단순한 차트의 모음에서 운영 제품 (operational product)으로 탈바꿈했습니다.