grafana-dashboards

grafana-dashboards 스킬 개요

grafana-dashboards가 하는 일

grafana-dashboards 스킬은 에이전트가 운영 환경에 맞는 Grafana 대시보드를 설계하고 초안을 만드는 데 도움을 줍니다. 관측 목표가 “API 상태를 보여줘”나 “인프라 포화도를 추적해줘”처럼 주어졌을 때, 막연한 프롬프트와 뻔한 차트 아이디어로 끝내지 않고 패널 구성, 메트릭 묶음, 레이아웃 우선순위까지 포함한 현실적인 대시보드 구조로 구체화하는 데 초점이 있습니다.

grafana-dashboards를 써야 하는 사람

이 스킬은 Prometheus 계열 메트릭을 기반으로 Grafana 대시보드를 만드는 플랫폼 엔지니어, SRE, DevOps 팀, 백엔드 엔지니어, 테크니컬 리드에게 가장 잘 맞습니다. 특히 어떤 시스템을 관측해야 하는지는 이미 알고 있지만, 검증된 모니터링 패턴을 바탕으로 더 정돈된 대시보드 설계를 원할 때 유용합니다.

실제로 해결하는 일

대부분의 사용자는 추상적인 의미의 “대시보드 하나”가 필요한 것이 아닙니다. 장애 대응, 리뷰, 일상적인 상태 점검에서 운영자가 빠르게 질문에 답할 수 있는 대시보드가 필요합니다. grafana-dashboards 스킬의 진짜 가치는 메트릭을 운영 판단의 흐름에 맞춰 정리하게 해준다는 점입니다. 즉, 무엇이 망가졌는지, 얼마나 심각한지, 다음에 어디를 봐야 하는지, 상황이 더 나빠지고 있는지를 빠르게 파악할 수 있게 해줍니다.

이 스킬이 다른 점

grafana-dashboards의 가장 큰 차별점은 단순한 UI 생성이 아니라 observability 휴리스틱에 대시보드 설계를 고정한다는 데 있습니다. 소스에서 특히 강조하는 것은 다음과 같습니다.

• 정보의 계층 구조
• 서비스용 RED method
• 인프라와 리소스용 USE method

그래서 단순히 JSON만 뽑아내는 “Grafana 대시보드 만들어줘” 같은 일반 프롬프트보다, 실제로 행동 가능한 레이아웃과 패널 선택이 중요할 때 훨씬 유용합니다.

포함되지 않은 것으로 보이는 것

이 스킬은 가벼운 편입니다. 저장소 기준으로 보면 핵심은 주로 SKILL.md에 있고, helper script, rule file, support asset은 포함되지 않은 것으로 보입니다. 즉 grafana-dashboards는 완전한 대시보드 프로비저닝 툴킷이라기보다, 프롬프팅과 설계를 위한 스캐폴드로 보는 편이 맞습니다.

grafana-dashboards 스킬 사용 방법

grafana-dashboards 설치 맥락

사용 중인 skills runtime이 저장소에서 스킬을 추가하는 방식을 지원한다면, wshobson/agents repo에서 설치한 뒤 observability 중심 워크플로에서 grafana-dashboards 스킬을 호출하면 됩니다. 일반적인 패턴은 다음과 같습니다.

npx skills add https://github.com/wshobson/agents --skill grafana-dashboards

환경에 따라 전체 repo를 로드하거나 다른 방식으로 skills를 동기화할 수도 있지만, 핵심은 에이전트가 아래 경로의 스킬에 접근할 수 있어야 한다는 점입니다.

plugins/observability-monitoring/skills/grafana-dashboards

가장 먼저 읽어야 할 파일

다음 파일부터 확인하세요.

• plugins/observability-monitoring/skills/grafana-dashboards/SKILL.md

이 스킬은 함께 봐야 할 보조 파일이 강하게 드러나지 않기 때문에, 실제로 유용한 가이드는 거의 모두 여기에 들어 있다고 봐도 됩니다. 빠르게 도입하기에는 좋지만, 대신 대시보드 스키마 관례, datasource 세부사항, export/import 워크플로는 직접 준비해야 합니다.

이 스킬이 사용자에게서 필요로 하는 입력

grafana-dashboards 스킬은 대시보드 제목만 주는 것보다 운영 맥락을 함께 줄 때 훨씬 잘 작동합니다. 에이전트에게 다음을 알려주세요.

• 모니터링 대상 시스템
• 대시보드의 대상 사용자
• datasource와 메트릭 네이밍 방식
• 가장 중요한 장애 유형
• 필요한 시간 범위와 새로고침 주기
• 서비스, 인프라, SLO, 비즈니스 KPI 중 어떤 관점을 원하는지

이 정보가 없더라도 구조 제안은 가능하지만, 패널 정의는 훨씬 더 일반론적으로 흐를 가능성이 큽니다.

grafana-dashboards에 잘 맞는 대시보드 요청

grafana-dashboards는 다음과 같은 요청에 잘 맞습니다.

• API 또는 마이크로서비스 상태 대시보드
• Prometheus 기반 RED 대시보드
• USE 방식의 인프라 대시보드
• SLO 및 지연 시간 중심 observability 보드
• drill-down 섹션이 있는 운영 개요 대시보드

반대로, 일회성 ad hoc 그래프 작성, custom plugin 비중이 큰 Grafana 작업, 또는 대시보드 구조보다 특정 datasource의 쿼리 언어 정확도가 더 중요한 환경에는 덜 적합합니다.

거친 요청을 강한 프롬프트로 바꾸기

약한 프롬프트:

• “Create a Grafana dashboard for my app.”

더 나은 프롬프트:

• “Use the grafana-dashboards skill to design a production Grafana dashboard for a customer-facing API. Datasource is Prometheus. Focus on RED metrics, 30s refresh, last 6h by default, and an on-call audience. Include top-row stat panels for traffic, error rate, p95 latency, and saturation signals. Then propose panel titles, layout order, and example PromQL queries.”

이 프롬프트가 잘 작동하는 이유:

• 시스템을 명시합니다
• 설계 방법을 지정합니다
• 대상 사용자와 시간 범위를 정합니다
• 구조와 쿼리를 함께 요청합니다
• 에이전트가 일반적인 출력으로 흐르지 않도록 충분한 제약을 줍니다

grafana-dashboards 사용을 위한 프롬프트 템플릿

다음 템플릿을 상황에 맞게 바꿔 쓸 수 있습니다.

• “Use the grafana-dashboards skill to design a Grafana dashboard for [service/system].
• Audience: [on-call / engineering managers / platform team]
• Datasource: [Prometheus / other]
• Dashboard goal: [incident response / daily health review / SLO tracking]
• Key metrics: [request rate, error rate, p95 latency, CPU saturation, queue depth]
• Default time range: [1h / 6h / 24h]
• Refresh interval: [15s / 30s / 1m]
• Constraints: [must fit single screen / include variables / separate business KPIs from infra]
• Output wanted: [panel plan / Grafana JSON draft / PromQL suggestions / layout rationale]”

실무에서 추천하는 grafana-dashboards 워크플로

좋은 grafana-dashboards 사용 흐름은 다음과 같습니다.

1. 대시보드 목적을 한 문장으로 정의합니다.
2. RED, USE, SLO, KPI 중심 중 어떤 관점으로 볼지 정합니다.
3. datasource에 실제로 있는 메트릭을 정확히 나열합니다.
4. 먼저 패널 계층 구조를 요청합니다.
5. 그다음 예시 쿼리를 요청합니다.
6. 실제 label과 metric name 기준으로 빈틈을 검토합니다.
7. 그 후에야 Grafana JSON 또는 provisioning 출력을 요청합니다.

이 순서를 따르면, 메트릭 모델 검증도 되기 전에 보기만 번듯하고 실제로는 못 쓰는 대시보드 JSON을 에이전트가 지어내는 흔한 실패를 피할 수 있습니다.

grafana-dashboards가 드러내는 설계 패턴

소스 자료에는 유지할 가치가 큰 실무 패턴이 몇 가지 강조되어 있습니다.

• 가장 중요한 메트릭을 big-number 또는 stat 패널로 맨 앞에 둡니다
• 추세를 보기 위해 time series를 사용합니다
• 상세 진단 패널은 대시보드 아래쪽으로 내립니다
• 서비스 동작에는 RED를 씁니다
• 호스트, 노드, 디스크, 큐 같은 리소스에는 USE를 씁니다

observability 팀 관점에서 grafana-dashboards의 핵심 가치는 차트 개수를 늘리는 것이 아니라, 의사결정 흐름을 더 좋게 만드는 데 있습니다.

결과물은 대체로 어떤 형태인가

저장소를 기준으로 보면, 이 스킬은 대체로 다음과 같은 결과를 만드는 데 도움을 줄 가능성이 높습니다.

• 대시보드 섹션 설계안
• 패널 배치 순서 추천
• 메트릭 카테고리 제안
• JSON 형태의 대시보드 예시
• 모니터링 방법론에 기반한 패널 선택

다만 정확한 label, recording rule, folder structure, permissions, Grafana provisioning setup까지 자동으로 맞아떨어지는 결과를 기대하면 안 됩니다. 그런 세부사항은 직접 명시해줘야 합니다.

출력 품질을 실제로 바꾸는 실전 팁

더 나은 grafana-dashboards 결과를 원한다면 항상 다음을 포함하세요.

• 실제 metric name이 있다면 그것
• percentile 사용 가능 여부
• cardinality 제약
• cluster, namespace, service 같은 환경 필터
• 대시보드가 overview용인지 deep debugging용인지

이 정보들은 에이전트가 유용한 상단 패널을 제안하는지, 현실적인 변수를 잡는지, 무리 없는 쿼리 범위를 설정하는지에 직접적인 영향을 줍니다.

grafana-dashboards 스킬 FAQ

grafana-dashboards는 초보자에게도 괜찮은가?

네, Grafana와 메트릭의 기본 개념을 이미 알고 있다면 괜찮습니다. grafana-dashboards 스킬은 무엇을 먼저 보여줄지, 패널을 어떻게 묶을지에 대해 좋은 구조를 제공합니다. 다만 Prometheus 입문, Grafana provisioning, 쿼리 언어 기초까지 포함한 완전한 초심자용 튜토리얼로 기대하면 맞지 않습니다.

grafana-dashboards가 실제 Grafana JSON을 만들어주나?

JSON 형태의 결과를 안내하거나 초안을 만들 수는 있지만, 최종 결과물이라기보다 출발점으로 보는 것이 맞습니다. 패널 타입, datasource UID, 쿼리 문법, 변수, Grafana 버전 호환성은 결국 각자 환경에서 검증해야 합니다.

일반 프롬프트보다 더 나은가?

observability 작업이라면 보통은 그렇습니다. grafana-dashboards의 가치는 RED, USE, 정보 계층 같은 검증된 대시보드 설계 패턴으로 에이전트를 좁혀준다는 데 있습니다. 일반 프롬프트는 보기엔 복잡하지만 운영자가 빠르게 읽기 어려운 대시보드를 만드는 경우가 많습니다.

어떤 경우에는 grafana-dashboards를 쓰지 말아야 하나?

문제의 핵심이 아래와 같다면 건너뛰는 편이 낫습니다.

• 깨진 PromQL 수정
• Grafana provisioning 파이프라인 관리
• custom panel 또는 plugin 개발
• export된 대시보드 역분석
• 표준 observability 레이아웃 문제가 아니라 datasource별 특수 동작 처리

이런 경우에는 더 전문화된 스킬이나, 해당 저장소를 직접 겨냥한 프롬프트가 대체로 더 적합합니다.

grafana-dashboards는 Prometheus에서만 동작하나?

아니요. 다만 Prometheus 스타일의 observability 개념에 가장 자연스럽게 맞춰져 있습니다. 다른 datasource를 쓴다면, 에이전트가 PromQL 관례를 당연하게 가정하지 않도록 쿼리 언어, 지원되는 패널 타입, 필드 이름을 명확히 알려줘야 합니다.

grafana-dashboards는 Observability 팀 전용인가?

아니요. 구조화된 운영 가시성이 목표라면 비즈니스 KPI나 서비스 상태 대시보드가 필요한 제품팀과 엔지니어링 팀에도 잘 맞습니다. 다만 이 스킬의 강점은 경영진 보고용 미관보다, 명확한 모니터링 논리가 필요한 대시보드에서 더 잘 드러납니다.

grafana-dashboards 스킬 개선 방법

먼저 메트릭 인벤토리를 에이전트에 주세요

grafana-dashboards 결과를 가장 빠르게 개선하는 방법은 대시보드를 요청하기 전에 짧은 메트릭 인벤토리를 제공하는 것입니다. 실제 메트릭 10~15개만 있어도 에이전트가 이름을 지어내는 일을 크게 줄일 수 있고, 패널 설계도 훨씬 배포 가능한 수준으로 가까워집니다.

대시보드가 답해야 할 운영 질문을 분명히 하세요

좋은 대시보드는 차트 목록에서 나오지 않고 질문에서 나옵니다. 예:

• “Can on-call tell in 30 seconds whether the API is broken?”
• “Can we detect CPU saturation before latency rises?”
• “Can product and ops review revenue-impacting errors in one view?”

이렇게 질문을 명확히 하면 무엇이 top row에 있어야 하고 무엇이 하단 진단 섹션으로 내려가야 하는지가 훨씬 선명해집니다.

개요 패널과 디버깅 패널을 분리하세요

grafana-dashboards 사용에서 흔한 실패 중 하나는 첫 화면에 너무 많은 것을 욱여넣는 것입니다. 에이전트에게 다음처럼 출력을 나누라고 요청하세요.

• executive 또는 on-call 요약
• 추세 섹션
• drill-down 또는 상세 진단

이렇게 해야 실제로 압박 상황에서도 훑어볼 수 있는 대시보드가 됩니다.

어떤 방법론을 쓸지 직접 지정하세요

에이전트가 올바른 모니터링 모델을 알아서 고를 거라고 가정하지 마세요. 명시적으로 이렇게 말하는 편이 좋습니다.

• request 중심 서비스에는 RED 사용
• compute 또는 인프라에는 USE 사용
• 고객 대상 API에는 SLO 패널과 RED를 함께 사용

이 한 줄 지시가 막연하게 “best practices”를 요청하는 것보다 패널 적합도를 훨씬 크게 올리는 경우가 많습니다.

결과물만이 아니라 근거도 요청하세요

첫 초안이 그럴듯하지만 너무 일반적이라면, 다음을 물어보세요.

• 각 상단 패널이 왜 그 위치를 차지했는지
• 화면 공간이 부족하면 어떤 패널을 제거해야 하는지
• 어떤 메트릭이 선행 지표이고 어떤 메트릭이 후행 지표인지

이렇게 해야 grafana-dashboards 스킬이 장식적인 완결성보다, 설명 가능한 설계를 내놓게 됩니다.

첫 초안은 구체적인 제약으로 수정하세요

반복 개선은 피드백이 구체적일 때 가장 잘 됩니다.

• “We do not have histogram buckets.”
• “Use namespace and pod variables.”
• “This dashboard is for mobile backend only.”
• “Remove business KPIs; this is strictly incident response.”
• “Keep it to one screen for a NOC display.”

이런 식의 구체적인 제약은 대개 두 번째 결과물을 극적으로 개선합니다.

흔한 약한 출력 신호를 경계하세요

초안에 다음 문제가 보이면 주의해야 합니다.

• 실제로 없는 generic metric name을 사용함
• table을 time series보다 너무 위에 많이 배치함
• 서비스와 인프라 관심사를 분리 없이 섞음
• 명확한 top-row 요약이 없음
• 대상 사용자와 기본 시간 범위를 무시함

이런 신호는 보통 스킬 호출 시 맥락이 너무 적었거나 요청 범위가 너무 넓었다는 뜻입니다.

저장소 맥락을 반영해 grafana-dashboards를 더 잘 쓰기

이 스킬은 사실상 SKILL.md에 주로 의존하는 것으로 보이므로, 실무 결과를 높이려면 내부 표준과 함께 쓰는 것이 좋습니다.

• 팀의 Grafana JSON schema 예시
• 팀의 네이밍 컨벤션
• 팀의 PromQL snippet
• 팀의 folder 및 templating 규칙

실제로 grafana-dashboards는 설계 두뇌 역할을 가장 잘하고, 구현 세부사항은 각자 환경이 채워주는 방식일 때 가장 강합니다.