SigNoz 해커톤을 위해 구축되었습니다: OpenTelemetry + SigNoz + MCP + 10년 동안 쌓인 엔터프라이즈 통합의 경험적 지식.

Workday 통합이 실패할 때, 에러 메시지는 거의 항상 실제 상황을 알려주지 않습니다. 단순한 403 Forbidden은 "Integration System User의 보안 그룹에 도메인 보안 정책이 누락되었습니다"라고 말해주지 않습니다. 이를 파악하려면 이전에 같은 문제로 고생해 본 경험이 있는 사람이 필요합니다. 저는 수년간 그 역할을 수행해 왔기에, 이번 해커톤을 위해 한 가지 구체적인 질문을 던졌습니다. '텔레메트리 (Telemetry)를 읽고 시니어 컨설턴트처럼 답변하는 에이전트에 이러한 암묵적 지식 (Tribal knowledge)을 담아낼 수 있을까?'

한 주가 끝날 무렵, 대답은 '예'였으며, 그 과정에는 제 코드가 예상치 못한 방식으로 두 번이나 충돌하는 과정도 포함되어 있었습니다.

내가 구축한 것

세 가지 레이어:

1. 모의 (Mock) Workday 테넌트. 통합 패턴을 연습하기 위해 구축한 Python/Flask 시뮬레이터입니다: SOAP 엔드포인트 (Endpoints), RaaS 리포트, 그리고 설정 기반의 다단계 감독 조직 프로비저닝 오케스트레이션 (입력 검증, 존재 여부 확인, SOAP 페이로드 생성, 테넌트 호출, 결과 추출)을 실행하는 Extend 스타일의 캔버스(Canvas)를 포함합니다.
2. SigNoz를 통한 완전한 관측성 (Observability). 모든 오케스트레이션 단계에 OpenTelemetry 인스트루멘테이션 (Instrumentation)을 적용하여, Foundry로 배포된 셀프 호스팅 SigNoz로 트레이스 (Traces), 로그 (Logs), 대시보드를 스트리밍합니다.
3. AI 진단 에이전트. SigNoz의 MCP 서버와 통신하여 가장 최근의 실패한 트레이스를 가져오고, 실패한 단계를 찾아낸 뒤, 이를 해결 단계가 포함된 Workday 특화 근본 원인으로 매핑하는 Python 에이전트입니다.

설정 기반 파이프라인의 인스트루멘테이션 (Instrumenting)

시뮬레이터의 오케스트레이션 엔진은 JSON 저장소에서 단계를 실행하며, 덕분에 인스트루멘테이션 작업이 놀라울 정도로 깔끔했습니다. 단계 실행기 (Step executor)를 한 번 감싸기만 하면 모든 단계에 자동으로 스팬 (Span)이 생성됩니다. 그 핵심은 다음과 같습니다:

def exec_steps(steps, depth=0):
    for i, s in enumerate(steps, start=1):
        typ = s.get("type", "unknown")
...

단 한 번의 수정으로, SigNoz의 워터폴 (Waterfall) 차트는 익명의 GET/POST 스팬 (Span)에서 step-02.send-http-request.CheckExists, step-05.send-http-request.CallHumanResources와 같이 읽기 쉬운 비즈니스 흐름으로 변했습니다. 또한 엔진의 기존 로그 (Log) 함수를 연결하여, 모든 단계의 메시지가 스팬 이벤트 (Span event)이자 트레이스 (Trace)와 연관된 로그 라인이 되도록 했습니다. 제가 예전에 사용하던 "눈에 띄는" 디버그 문자열들에 갑자기 트레이스 ID (Trace ID)가 부여되었습니다.

카오스 인젝션 (Chaos Injection): 의도적으로 고장 내기

에이전트가 진단할 대상을 제공하기 위해, 설정 기반의 실패 인젝션 (Failure injection) 기능을 추가했습니다. 플로우 스토어 (Flow store)의 어떤 단계에든 키 하나를 추가하면 실제와 유사한 Workday 실패 상황을 시뮬레이션할 수 있습니다:

{ "ref": "CallHumanResources", "inject": "403", ... }

모드 (Modes)는 제가 통합 작업 중에 실제로 마주치는 실패들을 다룹니다: 400 (잘못된 WQL, 보통 이름 필터 내의 이스케이프 처리되지 않은 아포스트로피), 401 (만료된 ISU 토큰), 403 (누락된 ISSG 도메인 권한), 404 (잘못된 참조), 타임아웃 (Timeout), 그리고 빈 결과 세트 (Empty result sets)입니다.

튜토리얼에서는 알려주지 않는 부분이 있습니다: 제가 처음으로 주입한 실패가 제 애플리케이션 자체를 충돌시켰다는 점입니다. 오케스트레이션 (Orchestration) 뒤에 있는 화면 핸들러 (Screen handler)는 성공 상황만을 렌더링하도록 설계되어 있었습니다. 플로우가 에러 결과를 반환했을 때, 196번 라인에서 NoneType 오류로 중단되었고, 해당 라인을 방어 코드로 보호한 후에는 197번 라인에서 다시 중단되었습니다. 카오스 엔지니어링 (Chaos engineering)이 다른 무엇보다도 저의 처리되지 않은 에러 경로를 먼저 찾아낸 것입니다. 적절하게도, 트레이스백 (Traceback)은 SigNoz의 예외 (Exceptions) 뷰에서 그룹화되어 정확한 트레이스에 연결된 채 저를 기다리고 있었습니다.

에이전트: 텔레메트리 (Telemetry) 입력, Workday 답변 출력

SigNoz는 MCP (Model Context Protocol) 서버를 제공하며 (Foundry의 casting.yaml 내 한 블록을 통해 활성화됨), 41개의 도구 (tools)를 노출합니다. 제 에이전트는 그중 세 가지를 사용합니다: 서비스의 가장 최신 ERROR 트레이스 (trace)를 찾기 위한 signoz_search_traces, 스팬 트리 (span tree)를 위한 signoz_get_trace_details, 그리고 증거로서의 스팬 속성 (span attributes) 및 상태 메시지입니다.

진단 자체는 경험을 바탕으로 구축된 규칙 테이블 (rule table)이며, 이는 제가 지원 티켓 (support ticket)에서 수동으로 적용했을 매핑 (mapping)과 같습니다. 예를 들어, 403 항목은 다음과 같습니다:

(re.compile(r"HTTP 403|Forbidden|lacks domain security", re.I),
 "ISSG missing domain security policy permission",
 "The ISU authenticated successfully but its security group lacks "
...

실행이 실패하면, 에이전트는 실패한 단계, Workday 언어로 된 근본 원인 (root cause), 수정 단계, 그리고 실패 지점이 표시된 파이프라인 맵 (pipeline map)을 출력합니다. 또한 chaos.injected가 존재할 경우, 실패가 주입되었는지 여부도 밝힙니다. 의도적으로 설정된 실패를 자연스러운 실패인 것처럼 조용히 제시하는 에이전트는 도구가 아니라 데모용 속임수에 불과할 것입니다.

이 섹션에 포함되어야 할 고백이 하나 있습니다: 에이전트의 아주 첫 번째 실행은 에이전트 스스로 403 오류를 내며 실패했습니다. 제가 SigNoz 서비스 계정 (service account)은 생성했지만 역할 할당 (role assignment) 단계를 건너뛰었기 때문에, MCP 서버는

수식 패널(formula panel)은 즉시 설계 결함을 드러냈습니다. 주입된 실패(injected failures)가 명확히 발생하고 있음에도 불구하고 **100% 성공(100% success)**이라고 표시되었습니다. 그 이유는 다음과 같습니다: 제가 만든 카오스 훅(chaos hook)이 step 스팬(span)은 실패시켰지만 흐름(flow)은 정상적으로 완료되도록 두었기 때문에, 루트 orchestration.run 스팬은 깨끗한 상태를 유지했습니다. 즉, 단계(step)가 실패한 실행이 성공한 실행으로 카운트되고 있었던 것입니다. 루트 래퍼(root wrapper)에 코드 한 줄을 추가하여, 트레이스 로그(trace log)의 어떤 단계라도 실패하면 루트로 ERROR를 전파(propagate)하도록 수정하자, 패널의 수치는 정직하게 92.5%로 떨어졌습니다.

저는 실패 횟수에 대한 알림 규칙(0 초과, 최소 1회, 5분 이동 창(rolling window))을 설정하며 마무리했습니다. 이후 실패를 주입한 실행을 한 번 더 수행한 결과입니다:

내가 배운 것

1. 혼돈(Chaos)이 버그를 먼저 찾아냅니다. 이번 주에 발생한 두 번의 충돌 모두 제가 주입한 실패가 아니라, 제 코드의 에러 경로(error paths)에서 발생했습니다. 만약 당신의 시스템이 한 번도 실패를 경험한 적이 없다면, 당신의 에러 핸들링(error handling)은 정의상 테스트되지 않은 상태입니다.
2. 로그 우선(log-first)보다 트레이스 우선(trace-first) 디버깅이 승리합니다. 이 프로젝트가 존재하게 된 이유 중 하나는, 해커톤 전주에 SigNoz가 동일한 시뮬레이터에서 93배의 속도 저하를 발견했기 때문입니다. 이는 localhost에서의 Windows IPv6 폴백(fallback) 문제였으며, 로그(logs)로는 절대 확인할 수 없었던 문제였습니다(이 이야기는 별도로 작성했습니다). 워터폴(waterfall)은 어디서 발생했는지를 답해주고, 스팬 속성(span attributes)은 왜 발생했는지를 답해줍니다.
3. 도메인 지식(Domain knowledge)은 에이전트의 해자(moat)입니다. MCP 배관(plumbing) 작업은 오후 한나절이면 끝났습니다. 하지만 에이전트를 유용하게 만드는 부분, 즉 SOAP 호출에서의 403 에러가 보통 ISSG 정책 격차를 의미하며 어떻게 대처해야 하는지를 아는 데는 수년이 걸렸으며, 그 어떤 텔레메트리(telemetry)도 이를 대체할 수 없습니다. 텔레메트리는 단지 이를 더 빠르게 전달할 뿐입니다.
4. 정직한 지표(metrics)를 위해서는 설계가 필요합니다. 제 대시보드는 문제가 발생하고 있는 동안에도 100% 성공을 보여주었습니다. 지표는 당신이 의도한 것이 아니라, 당신이 측정하는 것을 보고합니다.

다음에 할 일

에이전트 상단의 채팅 인터페이스, 더 풍부한 WQL 수준의 진단(결과 없음 드리프트(empty-result drift)는 리포팅 통합에서 소리 없는 살인자입니다), 그리고 동일한 패턴을 실제 통합 플랫폼에 적용하는 것입니다. 원칙적으로 여기서 다루는 내용은 Workday에 특화된 것이 아닙니다. 이름이 지정된 비즈니스 단계 스팬(named business-step spans), 도메인 규칙 테이블, 그리고 서사를 구성할 LLM을 결합하면 어떤 엔터프라이즈 파이프라인에서도 작동할 것입니다.

마무리

일주일, 하나의 시뮬레이터, 그리고 완전한 관측성 루프(observability loop): 이름이 지정된 트레이스(traces), 상관관계가 있는 로그(logs), 라이브 대시보드, 발송되는 알림, 그리고 MCP를 통해 이 모든 것을 읽고 동료처럼 답변하는 에이전트. (한 번의 명령으로 재현할 수 있도록 Foundry의 casting.yaml과 락 파일(lock file)이 포함된) 리포지토리는 여기 있습니다: https://github.com/ManjuVasanth/signoz-workday-agent

WeMakeDevs와 SigNoz가 주최한 Agents of SigNoz 해커톤을 위해 제작되었습니다.

AI 공개: 저는 디버깅 가이드, 코드 초안 작성 및 이 포스트의 편집을 위한 보조 도구로 Claude (Anthropic)를 사용했습니다. 시스템 설계, Workday 도메인 지식, 테스트 및 모든 스크린샷은 저의 개인 환경과 경험을 바탕으로 작성되었습니다.