[AIOps Agent 3] Grafana·Prometheus·Loki·Tempo 연결하기

About this offer

이 글에서 다룰 주제 Grafana 생태계 : 수집·저장·조회·알림의 역할을 어떻게 나눌까? Agent 연결 : webhook으로 조사를 시작하고 어떤 API로 근거를 모을까? 사용자 경험 : 보고서에서 대시보드·로그·트레이스로 어떻게 돌아갈까? 주요 단어 · Alloy · Prometheus · Mimir · Loki · Tempo · Pyroscope · PromQL · LogQL · TraceQL 읽기 안내 · HTTP와 메트릭·로그·트레이스의 이름을 아는 독자를 위한 연결 실습 설계입니다. 읽고 나면 같은 서비스·환경·시간을 유지하며 세 종류의 근거를 조회하고 해석할 수 있습니다. 결제 서비스의 p95 지연이 증가했다. Grafana 대시보드는 그래프를 보여 주지만, 운영자는 여전히 어떤 로그와 배포를 확인할지 판단해야 한다. 이번 편은 이 사이에 조사 에이전트를 넣는 방법을 다룬다. 그림 1. 텔레메트리 수집 경로와 에이전트의 조회 경로는 다르다. Agent는 제한된 도구를 통해 근거를 읽고, 사용자는 Grafana에서 원본을 확인한다. 1. 생태계 지도: Grafana 하나에 모든 데이터가 저장되는 것은 아니다 구성 요소 역할 에이전트와의 연결 OpenTelemetry 계측과 텔레메트리 전송을 위한 표준·도구 서비스명·환경·trace 문맥 정렬 Grafana Alloy 텔레메트리 수집·처리·전달 에이전트가 읽을 데이터의 수집 경로 Prometheus 메트릭 수집·저장·PromQL 조회 오류율·요청량·지연 조회 Mimir 확장 가능한 메트릭 백엔드 규모·보존 요구에 따라 도입 Loki 로그 저장·LogQL 조회 오류 메시지·패턴·trace ID 확인 Tempo 분산 트레이스 저장·조회 지연된 요청의 구간 조사 Pyroscope 지속적 프로파일링 CPU·메모리 사용 코드 경로 조사 Grafana 데이터 소스 조회·시각화·알림 근거 탐색과 운영 화면 모든 구성 요소를 첫날 설치할 필요는 없다. 기존 Prometheus와 Grafana가 있다면 조회 도구부터 붙이고, 로그·트레이스는 실제 데이터가 준비됐을 때 확장한다. Alloy를 쓴다고 모든 신호가 자동 수집되는 것도 아니다. 수집 대상과 파이프라인 설정이 필요하다. Alloy 소개 · Grafana Data Sources Grafana Agent 는 수집 제품의 이름이며 이 시리즈의 AI Agent와 다르다. 해당 제품은 2025-11-01 EOL에 도달했으므로 신규 수집 설계는 Alloy를 검토한다. Grafana Agent 공식 안내 그림 2. 로고는 제품을 식별하고, 그 아래 설명은 이 구성에서의 역할을 나타낸다. 서로 다른 제품을 동일한 Grafana 로고로 표시하지 않았다. Mimir는 메트릭 저장을 확장할 때, Pyroscope는 코드 수준 프로파일 분석이 필요할 때 선택할 수 있으며 처음부터 모두 설치할 필요는 없다. 예를 들어 요청 p95가 높다는 사실은 메트릭에서, 특정 요청이 DB 응답을 기다렸다는 단서는 트레이스에서 찾는다. CPU 시간이 어느 함수에 집중되는지까지 파고들 때는 프로파일이 다른 질문에 답한다. 따라서 Pyroscope를 붙인다고 Loki나 Tempo가 불필요해지는 것은 아니다. 제품별 역할: Grafana 공식 OSS 안내 1.1 최소 구성과 확장 구성을 나누면 처음부터 과해지지 않는다 첫 실습은 checkout의 /metrics → Prometheus → Grafana , 그리고 Agent → Prometheus 조회 API 면 시작할 수 있다. 여기서 Prometheus가 /metrics를 정기적으로 가져오는 scrape를 수행한다. Agent는 이미 저장된 데이터를 질의한다. 수집 주기와 조사 요청 주기는 다르다. 중앙 수집이 필요하면 Alloy의 선택한 컴포넌트로 메트릭을 scrape하여 remote_write로 Mimir 같은 백엔드에 전달하는 경로를 구성할 수 있다. 로그는 Loki, 트레이스는 Tempo, 프로파일은 Pyroscope에 맞는 수집 경로를 각각 설정한다. “Alloy → 모두”라는 한 줄은 구성해야 할 실제 파이프라인을 생략한 개념 표현일 뿐이다. Grafana에서 데이터 소스를 등록하는 일은 저장소에 질문할 연결을 만드는 일이다. 애플리케이션의 계측과 백엔드 적재는 따로 준비해야 한다. 따라서 Grafana에 Tempo를 추가했는데 trace가 없다면 데이터 소스 설정만 반복하지 말고 SDK 계측·export·수집기·적재 상태를 차례로 확인한다. 2. 첫 통합: Alerting → 수신 API → 큐 → 조사 Worker Grafana Alerting의 webhook contact point를 Agent 수신 API에 연결하는 구성을 생각할 수 있다. webhook payload에는 여러 알림이 묶일 수 있으므로 단일 이벤트라고 가정하지 않는다. 사용 버전에서 제공하는 인증·서명 기능을 확인하고 원문 본문 기준 서명을 검증한다. HMAC와 timestamp가 구성된 경우 timestamp 허용 범위도 검사한다. Webhook notifier 수신 API는 오래 걸리는 LLM 조사를 직접 수행하지 않는다. 요청을 검증하고, 영속적인 이벤트 저장 또는 큐 등록이 끝난 뒤 응답한다. Worker가 run을 만들고 조사한다. HTTP 요청이 끊겨도 조사 상태가 남도록 하기 위해서다. 정규화할 필드는 tenant , service , environment , cluster , alert_fingerprint , startsAt , status , received_at 이다. tenant는 신뢰된 인증 문맥으로 확정한다. label에 적힌 tenant를 그대로 권한으로 사용하지 않는다. 중복 키는 예를 들어 tenant + fingerprint + startsAt + status 로 설계할 수 있다. 그룹의 개별 알림마다 처리하며 firing 반복·resolved·재발의 의미를 나눈다. 단순히 fingerprint만 저장하면 이후 발생한 새 장애까지 중복으로 버릴 수 있다. DB unique 제약과 처리 상태를 이용해 중복 워커 생성을 막는다. 2.1 중복과 유실을 줄이는 수신 시퀀스 수신 API가 TLS·인증·본문 크기를 확인한다. 신뢰된 문맥에서 tenant를 확정하고 payload 안의 개별 알림을 정규화한다. 이벤트와 작업 예정 상태를 영속 저장한다. 저장 성공 후 webhook에 응답한다. Worker가 작업을 점유하고 조사한다. DB에 이벤트를 저장한 뒤 큐 발행이 실패하면 이벤트가 있지만 작업은 시작되지 않는 틈이 생긴다. 이를 줄이려면 같은 DB 트랜잭션에 outbox 레코드를 쓰고 별도 발행기가 큐로 전달하는 방식이나, 처음부터 DB 기반 작업 큐를 검토한다. 어떤 방식을 쓰든 중복 전달을 처리하는 수신 측 멱등성이 필요하다. 알림의 resolved 는 알림 규칙이 더 이상 firing이 아니라는 뜻이다. 근본 원인 해결, 모든 사용자 복구, Agent 보고서 검증 완료와 같은 의미로 합치지 않는다. 3. 백엔드 직접 조회와 Grafana 경유 조회 경로 적합한 상황 확인할 점 Prometheus·Loki·Tempo 직접 조회 백엔드별 계약을 명확히 유지 백엔드 인증·tenant·네트워크 정책 Grafana 데이터 소스 경유 Grafana의 구성된 데이터 소스 활용 플러그인별 쿼리 형식, 서비스 계정 권한 둘 중 하나가 모든 환경의 정답은 아니다. 이 글의 기본 제안은 Agent의 adapters/ 가 백엔드 조회 API를 호출하고 Grafana는 사람이 근거를 확인하는 화면으로 사용하는 것이다. Grafana에서 Viewer 역할을 줬다고 모든 데이터 소스의 행·tenant 격리가 자동 보장되는 것은 아니다. 세밀한 데이터 소스 권한과 RBAC는 OSS·Enterprise·Cloud에서 기능 범위가 다르다. Grafana Roles and permissions 특히 Loki HTTP API 자체는 인가를 제공하지 않으므로 앞단 인증·인가 구성이 필요하다. 멀티테넌트 헤더는 신뢰된 서버가 주입해야 하며 외부 사용자가 임의로 선택하도록 두지 않는다. Loki HTTP API 그림 3. 그림 1과 같은 배치다. 주황 화살표는 조회 요청 방향이다. 결과는 반대로 돌아오며 가독성을 위해 응답 화살표는 생략했다. 3.1 필드 계약을 먼저 맞춰야 서로 같은 서비스를 찾는다 의미 이 글의 예제 필드 확인할 곳 서비스 이름 OTel service.name SDK Resource 설정 메트릭 필터 service="checkout" 실제 metric label Loki 로그 필터 service_name="checkout" 적재 후 label·metadata Tempo 필터 resource.service.name 저장된 span Resource 실행 환경 예제의 environment="staging" 각 백엔드 변환 규칙 Loki의 네이티브 OTLP 적재는 service.name 처럼 점이 있는 속성 이름을 service_name 으로 정규화한다. 그렇다고 모든 속성이 자동으로 인덱스 라벨이 되는 것은 아니다. 적재 설정에 따라 structured metadata 등에 저장될 수 있다. Loki OTLP 적재 이 글의 environment 는 단순화한 예제 라벨이다. 실제 OTel 환경 속성을 무엇으로 쓰고 각 저장소에서 어떻게 조회할지 별도로 매핑한다. tenant 역시 일반 라벨 하나를 붙이는 것만으로 보안 격리가 완성되지 않는다. 4. 세 신호를 같은 시간과 서비스에 맞춘다 아래는 가상 메트릭·라벨을 사용한 질의 예시다. 실제 환경의 metric 이름, HTTP status label, histogram 형태에 맞춰 바꿔야 한다. 1 PromQL: 요청 기준 오류 비율 sum(rate(http_requests_total{ service="checkout", environment="staging", status=~"5.." }[5m])) / sum(rate(http_requests_total{ service="checkout", environment="staging" }[5m])) rate 는 counter의 초당 증가율을 구한다. 결과는 비율이며 0.02는 2%다. 분모가 0이거나 시계열이 누락되면 정상 0%라고 해석하지 않는다. 저트래픽 구간은 최소 요청 수 조건을 함께 둔다. 기간별 시계열은 GET /api/v1/query_range 에 query , start , end , step 을 전달해 조회한다. Prometheus HTTP API 2 PromQL: classic histogram의 p95 histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{ service="checkout", environment="staging" }[5m])) ) 단위는 초다. p95는 요청의 약 95%가 그 시간 이내에 끝난다는 분포 요약이며 평균이 아니다. 위 식은 classic histogram 예시다. bucket 설계, 샘플 수, 수집 형태를 확인하고, 인스턴스별 p95를 단순 평균 내지 않는다. 신규 계측에서는 native histogram 지원도 검토한다. Prometheus Histograms 3 LogQL: 같은 서비스의 timeout 메시지 {service_name="checkout", environment="staging"} |= "timeout" Loki의 GET /loki/api/v1/query_range 에서 같은 시간 범위와 제한된 limit 를 적용한다. 선택된 로그가 전체 로그를 대표한다고 가정하지 말고 반환 상한과 잘림 여부를 표시한다. 민감한 메시지는 모델에 전달하기 전에 마스킹한다. Loki HTTP API 4 TraceQL: 느린 span을 포함한 트레이스 후보 { resource.service.name = "checkout" && duration > 1s } 위 duration 조건은 span 소요 시간을 기준으로 매칭한다. trace 전체 소요 시간과 혼동하지 않는다. 조회 기간·환경·tenant는 도구에서 추가로 제한한다. Tempo 검색으로 후보를 찾고 trace ID로 상세 span을 확인한다. 배포 버전과 지원 검색 API에 맞춰 adapter를 구현한다. Tempo HTTP API · TraceQL 예시 위 예시는 서로 다른 라벨 표기를 의도적으로 보여 준다. OTel의 service.name , Loki의 service_name , Prometheus의 service 가 자동으로 같은 이름이 되는 것은 아니다. 매핑 규칙과 정규화된 서비스 카탈로그가 있어야 교차 조사가 가능하다. 4.1 [5m]과 step=60s는 서로 다른 시간 설정이다 그림 4. 조회 구간은 10분, rate의 계산창은 각 평가 시점 직전 5분, step은 1분이다. 01:00의 계산에도 앞선 데이터가 필요하다. start=01:00 , end=01:10 , step=60s 이면 양 끝을 포함해 11개 평가 시점을 요청한다. 각 시점에서 [5m] 에 해당하는 직전 5분의 counter 샘플을 읽는다. step을 1분에서 10초로 줄인다고 원본 scrape 주기가 10초로 바뀌지 않는다. 이미 저장된 자료를 더 촘촘하게 평가할 뿐이다. Prometheus Querying basics 1분 step 11개 점에서 얻은 p95의 평균은 10분 전체 요청의 p95가 아니다. 질문이 “시간에 따라 얼마나 변했나?”라면 시계열을 보고, “이 기간의 전체 분포는?”이라면 집계 목적에 맞는 질의를 다시 설계한다. 4.2 오류율을 숫자로 풀어 읽기 설명용으로 같은 범위에서 5xx 증가율이 초당 2건, 전체 요청 증가율이 초당 100건이라고 하자. 결과는 2/100=0.02 , 즉 2%다. Grafana에서 비율을 percent(0–1)로 표시할지, 100을 곱해 percent(0–100)로 표시할지 일치시킨다. 이중으로 100을 곱하면 200% 같은 잘못된 값이 나온다. sum(rate(...)) 에서는 각 counter의 reset을 처리한 뒤 합산한다. 서비스 전체 counter를 먼저 합쳐 증가율을 계산하면 인스턴스별 재시작을 잘못 해석할 수 있다. 또한 오류 시계열이 생성되지 않은 것과 실제 오류 0건은 다르므로, 분자 누락을 무조건 0으로 채우기 전에 계측 계약과 수집 상태를 확인한다. 4.3 메트릭에서 로그와 트레이스로 넘어가는 판단 p95만 증가하고 오류율이 유지되면 “느리지만 성공한 요청”을 조사할 수 있다. timeout 로그가 함께 보이면 trace ID가 있는 예시를 골라 호출 경로를 확인한다. 예를 들어 HTTP span 1.4초 중 DB client span이 1.1초라면 DB 호출 경로가 주요 지연 후보가 된다. 이것만으로 DB 서버 CPU가 원인이라고 단정하지 않는다. 연결 풀 대기, 네트워크, 락 대기, 느린 SQL을 나눠 확인한다. 로그에 trace ID가 있다고 자동 클릭 연결이 완성되는 것은 아니다. 로그 파싱 위치와 Grafana의 derived field·데이터 소스 링크 설정이 맞아야 한다. 메트릭 exemplar도 계측·저장·데이터 소스 지원과 설정이 필요하다. 연동하지 않은 상태에서는 trace ID를 복사해 Tempo에서 직접 조회하는 최소 경로부터 검증할 수 있다. 트레이스가 샘플링돼 있다면 느린 요청이 저장될 가능성이 편향될 수 있다. trace 목록의 오류 비중을 전체 HTTP 오류율로 사용하지 않는다. 전체 비율은 분모가 정의된 메트릭으로 확인하고 트레이스는 구체적인 실행 경로를 설명하는 데 사용한다. 그림 5. 메트릭은 영향의 크기, 로그는 구체적 현상, 트레이스는 요청 경로의 대기 구간을 보여준다. 이 설명 순서는 고정된 제품 호출 규칙이 아니며 증거에 따라 앞 단계로 돌아갈 수 있다. 5. 데이터가 안 보이면 정상일까? Agent는 각 조회에 ok , no_data , stale , timeout , denied 를 보존한다. 마지막 샘플 시각, 수집 지연, 조회 step, UTC 범위를 함께 기록한다. 로그·트레이스는 샘플링이나 수집 실패 때문에 일부 요청이 없을 수 있다. “트레이스가 없다”는 사실만으로 해당 문제가 없다고 단정하지 않는다. 배포 직후 지연이 늘었다면 이전 구간과 비교하고, 다른 서비스·리전·버전에서도 같은 변화가 있었는지 확인한다. 공통 의존성 장애와 트래픽 급증을 반증 후보로 둔다. 시간적 상관관계는 원인 확정이 아니다. 에이전트 조회 자체도 운영 부하다. 조회 기간, step의 최소값, 로그 반환량, 동시 조회 수, 재시도 수를 제한한다. 서비스별 큐와 전역 예산을 두면 알림 폭주가 조회 백엔드 장애로 번지는 것을 줄일 수 있다. 6. 사용자에게 제공할 결과: 검증 가능한 조사 카드 가상 보고서는 다음과 같이 구성한다. 상태: 추가 조사 필요 관측: 01:00~01:10 UTC checkout의 p95가 기준 구간보다 증가했다. [ev-001] 관측: 같은 구간에 DB timeout 로그가 확인됐다. 반환 상한에 도달해 전체 건수는 미확인이다. [ev-002] 후보: DB 연결 대기 또는 하위 서비스 지연. 배포와의 시간적 연관성은 있지만 원인은 확정하지 않았다. 다음 확인: DB pool 사용률, 느린 span, 배포 전후 설정 차이. 각 evidence에는 저장된 정확한 기간과 질의, datasource 식별자, 원문 링크를 붙인다. Grafana dashboard data link 또는 Explore 공유 링크를 사용하되 설치 버전의 링크 형식을 확인한다. URL에 토큰이나 비밀을 넣지 않고, 클릭하는 사용자도 해당 데이터 접근 권한이 있어야 한다. 대시보드에는 조사 상태·대기 시간·성공률 같은 집계 메트릭을 표시한다. run ID나 trace ID를 Prometheus label로 넣으면 카디널리티가 커지므로 상세 ID는 로그·트레이스·보고서에 둔다. 요약 저장과 Grafana annotation 작성도 서로 다른 권한의 작업으로 분리한다. 7. 단계별 구현 과제 첫째, 고정된 알림 fixture로 webhook 정규화와 중복 방지를 검증한다. 둘째, 읽기 전용 Prometheus 도구 하나를 붙인다. 셋째, Loki와 Tempo를 연결해 같은 서비스·환경·UTC 구간을 조회한다. 마지막으로 보고서에서 원본 링크가 실제 같은 근거를 여는지 확인한다. No Data, 권한 거부, 백엔드 시간 초과가 발생해도 보고서가 남아야 한다. 알림 규칙과 기존 운영 연락망은 Agent 가용성과 독립적으로 동작하도록 유지한다. 자료 기준 : 2026-10-04, 본문에 연결한 공식 문서의 해당 기능·구문을 확인했다. 모든 버전의 전체 동작을 검증한 것은 아니다. 코드와 아키텍처는 제안 예시이며 실제 클러스터에서 실행하지 않았다. 그림 자산 출처 : Grafana 공식 OSS 제품 페이지 의 제품별 원본 로고를 색·비율을 유지해 사용했다. 연결선·구획·설명은 자체 제작이며 제품의 공식 아키텍처 도면이 아니다. 상표 사용 정책 에 따른 표기: The Grafana Labs Marks are trademarks of Grafana Labs, and are used with Grafana Labs’ permission. We are not affiliated with, endorsed or sponsored by Grafana Labs or its affiliates. AIOps 에이전트 개발 시리즈 [AIOps Agent 1] 에이전트 개발 기본기와 Repository 설계 [AIOps Agent 2] 메모리·도구 권한·승인과 안전한 실행 [AIOps Agent 3] Grafana·Prometheus·Loki·Tempo 연결하기 [AIOps Agent 4] 운영·평가부터 OpenTelemetry와 Langfuse까지