AI 에이전트(AI agents)는 기존의 모니터링 방식이 놓치는 방식으로 실패합니다. 도구 호출(tool call)이 조용히 재시도되거나, 프롬프트(prompt)가 토큰 비용을 4배로 불리기도 합니다. 판단 단계(judge step)에서 타임아웃이 발생하거나, 에이전트가 조용히 루프(loop)에 빠지기도 합니다. 여러분의 관측성(observability) 플랫폼은 이 모든 것을 가지고 있지만, 새벽 2시에 트레이스 워터폴(trace waterfall)을 뚫어지게 쳐다보는 것은 _무엇이 고장 났는지 아는 것_과는 다릅니다.

그래서 WeMakeDevs의 Agents of SigNoz를 위해 저는 Cerberus를 구축했습니다. 이는 SigNoz에서 에이전트의 텔레메트리(telemetry)를 다시 읽어오고, 트레이스 인용(trace citations)과 함께 사건을 쉬운 영어로 설명하며, 해당 사건을 잡아낼 수 있는 경고 규칙(alert rule)을 작성하는 AI SRE 코파일럿(copilot)입니다. 이 모든 과정은 SigNoz 자체의 MCP 서버를 통해 이루어집니다.

라이브 데모: https://cerberus-sre.vercel.app
코드: https://github.com/CodeMuscle/cerberus

아이디어: 방출(emit)하고 소비(consume)하기

대부분의 관측성 프로젝트는 텔레메트리를 _방출(emit)_하기만 합니다. 스팬(span)을 푸시하고 끝내버리죠. Cerberus는 에이전트 네이티브(agent-native) 방식인, 방출한 뒤 자신의 에이전트 트레이스를 다시 소비(consume)하고 그에 따라 행동하는 것을 수행합니다. 세 개의 머리, 세 가지 역할:

• 관찰(Observe) — 모든 에이전트 실행은 토큰 사용량, 비용, 지연 시간(latency) 및 단계별 오류와 함께 OpenTelemetry 트레이스로 SigNoz에 기록됩니다.
• 설명(Explain) — 코파일럿이 순위가 매겨진 사건들을 읽고, 정확한 trace_id를 인용하며 오직 사실에 기반하여 "방금 무엇이 잘못되었는가?"에 답합니다.
• 예방(Prevent) — 클릭 한 번으로 해당 사건의 근본 원인(root cause)에 대한 SigNoz 경고 규칙(alert rule)을 작성합니다.

왜 REST API가 아니라 MCP인가

흥미로운 결정은 읽기 경로(read path)였습니다. SigNoz는 AI 클라이언트가 사용하는 것과 동일한 도구 인터페이스인 **MCP 서버 (MCP server)**를 제공합니다: signoz_execute_builder_query, signoz_search_traces, signoz_create_alert 및 약 40여 개의 도구들입니다. Cerberus는 REST 엔드포인트(REST endpoint)를 스크래핑하는 대신 MCP를 사용하여 통신합니다. 이는 LLM이 사용하는 정확한 인터페이스가 곧 제품이 구축된 인터페이스라는 것을 의미합니다.

배포는 단 한 번의 명령으로 가능합니다. SigNoz의 Foundry 설치 프로그램이 단일 캐스팅 파일(casting file)을 통해 전체 스택과 MCP 서버를 모두 실행하기 때문입니다:

curl -fsSL https://signoz.io/foundry.sh | bash
foundryctl cast -f casting.yaml     # :8080에서 SigNoz 실행, :8000에서 MCP 실행

casting.yaml과 그 락파일(lockfile)이 커밋되어 있으므로 배포는 재현 가능하며, 누구나 다시 실행할 수 있습니다.

아무도 말해주지 않는 부분: 페이로드(payload)는 문서와 다릅니다

이 부분이 실제로 저의 하루를 잡아먹었던 부분이며, 다른 개발자분들이 꼭 알았으면 하는 내용입니다.

1. signoz_search_traces는 gen_ai.* 속성(attributes)이 없는 고정된 컬럼 프로젝션(column projection)을 반환합니다. "스팬(spans)을 가져와줘"라고 요청할 때 사용하는 당연한 도구가 고정된 컬럼 세트만을 돌려줍니다. 저의 토큰 및 비용 데이터인 gen_ai.usage.input_tokens, gen_ai.usage.cost_usd는 매번 빈 값으로 돌아왔습니다. 제품의 핵심은 토큰 및 비용 급증을 다루는 것인데, 데이터가 0으로 나왔던 것입니다.

해결책은 Query Builder v5 도구로 내려가서 해당 컬럼들을 명시적으로 선택하는 것이었습니다:

{"name": "gen_ai.usage.input_tokens", "fieldDataType": "number",
 "signal": "traces", "fieldContext": "tag"}

signoz_execute_builder_query를 사용하면 원하는 속성을 정확하게 지정할 수 있습니다. 제가 수동으로 gen_ai.* 태그를 선택하고 나니 실제 수치들이 나타나기 시작했습니다.

2. 응답이 JSON 뒤에 사람이 읽을 수 있는 노트를 포함합니다. 페이로드는 다음과 같은 형태입니다:

{ ...유효한 JSON... }
note: returned 3 rows (limit 3) — more results likely exist (hasMore=true).

순진한 json.loads()는 후행 텍스트가 있으면 오류를 발생시키는데, 이를 광범위하게 처리하면 스팬(span)이 0개이고 오류도 없는 상태가 됩니다. 해결책은 전체 문자열을 파싱하는 대신 접두사(JSONDecoder().raw_decode)를 디코딩하는 것입니다.

3. 행(row)들이 한 단계 아래에 중첩되어 있고, 빈 시간 창(empty window)이 null을 반환합니다. 각 행은 timestamp와 함께 필드를 data 하위 객체로 묶으며, 비어 있는 시간 범위는 리스트([])가 아닌 `

• MCP 서버는 에이전트(Agent)를 구축하기 위한 SigNoz의 가장 핵심적인 부분입니다 — 하지만 그 페이로드(Payload)를 문서에 명시된 대로 신뢰하기보다는, 직접 발견해야 할 대상으로 취급하세요. 실제 응답을 캡처하여 테스트 코드에 고정(Pin)해 두는 것이 좋습니다.
• Query Builder v5는 탈출구(Escape hatch) 역할을 합니다. 편의 도구가 필요한 필드를 반환하지 않을 때 언제든 사용할 수 있습니다.
• LLM 이전에 결정론(Determinism)을 확보하는 것이 답변의 신뢰성을 만드는 핵심입니다. 모델은 자신이 조작할 수 없는 사실만을 설명하게 됩니다.

Cerberus는 MIT 라이선스를 따르며, 단 한 번의 Foundry 명령어로 재현 가능합니다. 해커톤 규정에 따라 AI 코딩 어시스턴트(Claude)의 도움을 받아 제작되었습니다.

라이브 데모: https://cerberus-sre.vercel.app
코드: https://github.com/CodeMuscle/cerberus