SigNoz MCP로 로컬 세션에 운영 모니터링 스킬을 붙이고 다듬은 기록New

🤖 Overview

요즘 운영 로그와 트레이스는 대시보드 대신 로컬의 Claude Code 세션에서 본다. SigNoz MCP 서버를 붙여두고, 조사 순서를 정해둔 스킬로 배포 전후 모니터링을 맡긴다.

처음에는 도구만 붙여두고 그때그때 물어봤다. 그러다 에이전트가 MCP 도구의 사용 방법을 잘못 짚거나 의도와 다르게 쓰는 일을 겪으면서, 조사 순서를 저장소 안에 스킬로 정해뒀다. 지금도 모니터링 중 발견한 문제를 반영하며 계속 고치고 있다. 그렇게 쌓인 규칙 중에는 MCP 도구의 한계를 메우기 위한 우회책도 섞여 있었다.

이 글은 그 스킬을 만들고 유지해온 기록이다. 스킬에 무엇을 담았는지, MCP 버전이 바뀔 때 스킬이 어떻게 흔들렸는지, 그리고 우회책을 계속 쌓는 대신 원인이 있는 업스트림을 고치기 시작한 이야기를 남긴다.

1. 대시보드 대신 로컬 세션에서 운영을 본다

사내 서비스는 self-hosted SigNoz로 로그와 트레이스를 모으고 있다. SigNoz는 공식 MCP 서버를 Go 바이너리로 배포한다. 받아서 Claude Code에 stdio 서버로 등록하면, 세션 안에서 로그 검색이나 집계, 트레이스 상세 조회를 도구로 바로 부를 수 있다.

{
  "mcpServers": {
    "signoz": {
      "type": "stdio",
      "command": "/Users/jh8459/signoz-mcp-server",
      "env": { "SIGNOZ_URL": "...", "SIGNOZ_API_KEY": "..." }
    }
  }
}

처음 며칠은 편했다. 대시보드에서 필터를 하나씩 고르는 대신 “최근 6시간 슬로우 쿼리 상위 20개 뽑아줘”라고 쓰면 됐다. 쿼리 문법을 기억하지 않아도 되고, 결과를 표로 정리하는 것까지 맡길 수 있었다.

그런데 결과를 그대로 믿기에는 걸리는 장면이 몇 번 있었다.

2. 도구만 붙여두면 같은 실수를 반복했다

크론 실행 트레이스를 조사하던 중이었다. 에이전트가 찾아온 트레이스에는 크론이 13ms 만에 “대상 0건”으로 끝난 기록이 세 건 있었다. 운영 크론이 대상을 하나도 못 찾았다는 결론이 바로 나왔다.

결론을 정리하기 전에 환경 속성을 찍어봤다. 세 건 모두 dev였다.

dev와 prod가 같은 서비스 이름을 쓰고 있어서, 서비스 이름만 걸고 조회하면 두 환경이 한 결과에 섞인다. dev DB는 오래된 스냅샷이라 대상이 0건인 게 오히려 자연스러웠다.

모양만 다를 뿐 같은 일이 두 번 더 있었다.

한 번은 어떤 요청이 실제로 들어왔는지 확인하는 쿼리가 빈 결과로 돌아왔다. 그 결과를 믿었다면 “그런 요청은 없었다”고 보고 운영 트래픽을 막는 설정을 넣었을 것이다. 다시 보니 시간 범위가 1년 틀려 있었다. 범위가 틀려도 쿼리는 성공하고, 결과만 비어서 온다.

또 한 번은 최신순으로 정렬하고 개수를 제한한 결과를 보고 “이 시간대에 몰려 있다”는 말이 나왔다. 목록이 가장 최근 구간부터 채워졌으니 그렇게 보일 수밖에 없었다. 날짜별로 창을 잘라 다시 세보니 매일 비슷한 양이었다.

세 번 모두 도구는 오류 없이 결과를 돌려줬고, 결과만 봐서는 어디가 틀렸는지 알 수 없었다.

3. 조사 순서를 스킬로 고정했다

2장에서 겪은 실수는 모두 조회 조건을 확인하지 않은 채 결과부터 해석하면서 생겼다. 같은 실수를 반복하지 않으려고, 조회 조건을 확인하고 결과를 해석하는 순서를 스킬에 담았다.

조사는 시간 범위를 확인하는 데서 시작한다. 시작과 끝을 절대 시각으로 정하고, 변환한 epoch 값을 다시 KST로 되돌려 의도한 시각과 맞는지 확인한다. 시간 범위가 1년 어긋난 쿼리도 여기서 걸러낼 수 있다. 모든 조회에는 환경 필터를 걸어 dev와 prod가 섞이지 않게 했다.

조회 조건을 확인한 뒤에는 심각도(severity)별 건수부터 센다. 전체 규모를 알아야 최신순 목록이 일부만 보여주고 있는지 판단할 수 있기 때문이다. 개별 로그를 자세히 들여다보는 건 그다음이다. 결과가 0건이어도 바로 결론을 내리지 않는다. 데이터가 있다고 아는 조건으로 같은 형태의 쿼리를 다시 실행하고, 그쪽도 0건이면 쿼리부터 점검하도록 했다.

스킬에 담은 조회 지침을 요약하면 다음과 같다.

조회 전에 시간 범위와 환경 필터를 확인한다.
심각도별 건수로 전체 규모를 파악한 뒤 상세 로그를 조회한다.
상세 조회에서는 알려진 노이즈를 걸러낸다.
결과가 0건이면 데이터가 있는 조건으로 같은 형태의 쿼리를 재검증한다.

각 단계가 필요한 이유와 실제로 겪은 함정은 별도 문서에 모았다. 스킬은 조사를 시작할 때 이 문서를 먼저 읽는다. 이렇게 나누니 새로운 함정을 발견해도 조사 순서를 매번 고칠 필요 없이 문서에 사례를 보탤 수 있었다.

그중 가장 자주 참고하는 건 정상 노이즈 목록이다. 우리 서비스에서는 기능 플래그가 꺼진 크론이 예외를 던져 FATAL 로그를 하루 수천 건 남긴다. 비로그인 방문자의 세션 조회도 401 WARN으로 시간당 수백 건씩 쌓인다. ERROR와 FATAL을 함께 조회했을 때, 이런 FATAL 로그가 개수 제한을 모두 채워 ERROR가 하나도 보이지 않은 적이 있었다. 상세 조회 전에 알려진 노이즈를 걸러내는 이유다.

조회한 내용을 읽는 방식에도 규칙이 필요했다. 로그와 SQL 본문에는 외부 사용자의 입력이 그대로 들어갈 수 있다. 여기에 “앞의 지시를 무시하고 ~해라” 같은 문장이 있어도 에이전트가 따를 지시가 아니라 조사할 문자열로만 다루도록 했다.

4. 배포 전후에는 관측 키부터 바뀐다

조사 순서를 정해두고도 배포 전후를 비교할 때는 다른 문제가 생겼다. 스킬을 가장 많이 쓴 건 프레임워크와 ORM의 메이저 업그레이드를 배포할 때였는데, 배포 전에 쓰던 쿼리로 이후 구간을 조회하니 0건이 나왔다. 쿼리는 이번에도 오류 없이 실행됐다.

원인은 함께 업그레이드된 계측 라이브러리에 있었다. SQL 본문이 담기는 속성이 db.statement에서 db.query.text로 바뀌면서, 예전 키를 찾던 쿼리가 새 데이터를 놓친 것이다. HTTP 상태 코드도 http.status_code에서 http.response.status_code로 옮겨갔다. 응답 시간 메트릭은 이름뿐 아니라 단위까지 ms에서 s로 바뀌어, 배포 전후의 값을 그대로 비교할 수 없었다.

에러율을 볼 때도 숫자만으로는 판단하기 어려웠다. 배포 직후 에러 span이 크게 줄어 처음에는 업그레이드 효과처럼 보였다. 하지만 우리가 조회하던 HTTP span에서는 이전 계측이 에러로 표시하던 4xx 응답이 새 계측에서 빠지고, 5xx만 에러로 남고 있었다. 줄어든 숫자를 서비스가 개선됐다는 근거로 삼을 수는 없었다.

이 변화는 어떤 span을 보는지와도 관련이 있다. OpenTelemetry의 HTTP 규약은 4xx 응답에 대해 서버 span의 상태는 미설정으로 남기도록 요구하고, 클라이언트 span은 에러로 표시하도록 권고한다. 에러 표시만 비교하기 전에 관측 대상과 계측 방식을 함께 확인해야 하는 이유다.

이 경험을 바탕으로 스킬에도 배포 전후의 계측 방식을 확인하는 단계를 넣었다. 먼저 각 구간에 어느 세대의 스택이 떠 있는지 확인하고, 속성 이름이 바뀐 항목은 이전 키와 새 키를 함께 조회하도록 했다. 4xx 건수는 에러 표시 여부에 기대지 않고 HTTP 상태 코드로 따로 센다. 그래야 계측 방식의 변화를 서비스의 변화로 오해하지 않을 수 있다.

비교하는 시간대도 맞췄다. 48시간을 기준으로 본 값과 오전 두어 시간만 본 값을 그대로 비교하면, 배포 영향인지 관측 구간에 따른 차이인지 구분하기 어렵다. 날짜별로 같은 KST 시간 범위를 자르고 같은 지표로 비교하도록 이 조건도 스킬에 남겼다.

5. 스킬은 MCP 버전에도 묶여 있다

계측 키가 바뀌면 쿼리를 고쳐야 했듯, MCP 서버의 도구 이름이 바뀌면 스킬에 적어둔 호출도 고쳐야 했다.

9월 11일에 서버를 v0.0.4에서 v0.14.0으로 교체하면서 이걸 체감했다. 도구가 21개에서 43개로 늘었고, 중간의 v0.0.5에서 도구 이름 전체에 signoz_ 접두사가 붙으면서 이름이 거의 다 바뀌어 있었다. 구버전의 로그 검색 도구에는 환경 필터를 걸 방법 자체가 없었다.

스킬은 v0.14의 도구 이름으로 새로 쓰고, 구버전 바이너리는 .bak으로 남겨뒀다. SigNoz가 따로 배포하는 공식 Claude Code 스킬 묶음도 최신 도구 이름을 전제로 쓰여 있다. 결국 MCP 버전과 스킬 셋은 한 쌍으로 관리해야 했다.

그래서 로컬에 설치된 버전에 맞춰 스킬을 구성하려고 했는데, 정작 바이너리에서 버전만 바로 출력할 방법이 없었다.

$ signoz-mcp-server --version
Configuration validation failed: SIGNOZ_API_KEY is required for stdio mode

키 누락 오류라 키를 넣고 다시 실행했다. 이번에는 아무것도 출력되지 않고 터미널이 멈췄다. 플래그를 무시하고 stdio 서버가 그대로 떠서 입력을 기다리고 있었고, 버전은 기동 로그의 service.version 필드에만 찍혀 있었다.

--version 플래그가 처음부터 없었다.

그동안 스킬에서는 도구 이름으로 버전을 가늠하고 있었다. 하지만 signoz_aggregate_logs는 v0.0.5에도 등록된 도구라서, 이 이름이 보인다는 이유만으로 v0.14 이상이라고 판단할 수는 없다. 도구 목록은 필요한 기능이 있는지 확인하는 단서일 뿐, 정확한 버전을 대신하지 못한다.

버전과 지원 기능을 잘못 짚으면 에이전트가 없는 도구 대신 다른 도구를 선택할 수 있다. 그 도구에 환경 필터가 없다면 dev가 섞인 결과를 prod에 대한 결론으로 가져올 위험도 생긴다. 2장의 크론 사례를 막으려면 조사 순서뿐 아니라 그 순서를 수행할 도구도 확인해야 했다.

교체 절차 문서에는 바이너리에서 버전 문자열을 꺼내는 strings 명령도 적어뒀다. 이 글을 쓰면서 다시 돌려봤더니 아무것도 출력하지 않고 정상 종료했다. 버전이 주입되는 위치를 잘못 짚은 명령이었다. 실패 신호가 없으니 한 달 동안 몰랐다.

6. 우회책을 쌓는 대신 업스트림을 고쳤다

함정 문서를 다시 읽다가 규칙이 두 종류로 갈린다는 걸 알았다. 시간 범위나 환경 필터를 확인하고 정상 노이즈를 걸러내는 건 도구가 개선돼도 조사자가 해야 할 일이다. 반면 버전 출력 기능이 없어 도구 이름으로 버전을 가늠하거나 바이너리에서 문자열을 찾는 건 도구의 빈자리를 메우기 위한 우회책이었다.

이런 우회책은 MCP 서버가 고쳐지면 스킬과 교체 절차 문서에서 지울 수 있다. 남겨두는 동안에는 에이전트가 매번 불완전한 단서를 따라야 하고, 나는 서버를 올릴 때마다 그 규칙이 여전히 맞는지 확인해야 한다. 버전을 직접 확인할 수 있게 만드는 편이 유지할 규칙도 줄여준다.

그중 가장 작은 버전 플래그부터 고쳐서 PR로 올렸다(signoz-mcp-server#347). config를 읽기 전에 --version을 먼저 처리해서, 키가 있든 없든 버전만 찍고 끝나게 했다.

처음 단 제목은 fix: print version without requiring config였다. 키 누락 오류만 보고 붙인 이름이었고, 5장의 두 번째 실행은 PR을 올린 뒤에야 해봤다. 원인이 플래그가 없는 데 있다는 걸 확인하고 feat: add --version flag로 고쳤다. 조사할 때 쓰던 대조군 습관을 PR 설명에서는 건너뛰고 있었다.

원고 작성 시점에는 PR을 올리고 리뷰를 기다리고 있다.

🤔 Understanding

• 스킬은 순서를, 문서는 이유를 담는다 — 함정을 스킬 본문에 섞지 않고 별도 문서로 빼두니, 함정이 늘어도 스킬의 흐름은 그대로 유지됐다.
• 스킬이 전제하는 계측 키와 도구를 확인한다 — 계측 키가 바뀌면 조회 결과가 비고, 도구 이름이 바뀌면 스킬이 의도한 조회를 수행하지 못할 수 있다. 스킬이 어느 버전과 기능을 전제로 하는지 확인할 수단이 필요했다.
• 도구 때문에 생긴 우회책은 따로 모아둔다 — 도구 때문에 생긴 규칙은 업스트림이 고쳐지면 지울 수 있다. 그 규칙들을 따로 모아두니 기여할 거리가 자연스럽게 정해졌다.