AI Slack 봇에 Honeycomb 트레이스(Traces)를 추가하는 방법

Pipa는 Lunch Pail Labs의 스튜디오 운영을 담당하는 우리의 에이전트입니다. Pipa는 Slack에서 동작하며, E2B 샌드박스(sandboxes)를 기반으로 구동되고, 하네스(harness)로는 OpenCode를 사용합니다.

정상적으로 작동할 때는 정말 멋집니다. 도움을 요청하면 Pipa가 작동하여 도구(tools)를 실행하고, 작업을 수행한 뒤 답변을 가지고 돌아옵니다.

하지만 문제가 발생하면 완전히 블랙박스(black box)가 되어 버립니다. 터미널에서는 도구 호출(tool calls), 권한 프롬프트(permission prompts), 지연(stalls)

처음 몇 개의 스팬(spans)은 백엔드 경로를 설명합니다. invoke_agent 스팬은 에이전트 세션(agent session)을 설명합니다. 해당 스팬 내부에서 Pipa는 사용자 메시지, 어시스턴트 응답, 도구 호출(tool calls), 재시도(retries), 그리고 실행 요약(run summary)에 대한 이벤트(events)를 부착합니다.

이제 지루한 인프라 관련 사항과 에이전트의 실제 동작이 동일한 트레이스(trace) 내에 존재하게 됩니다.

트레이스 추가하기

1. OpenTelemetry 트레이스를 Honeycomb으로 전송하기

OpenTelemetry는 트레이스 데이터를 생성하고 전송합니다. Honeycomb은 제가 이를 검사하는 곳입니다. Pipa에서는 HONEYCOMB_API_KEY가 존재할 때 게이트웨이(gateway)가 Honeycomb으로 트레이스를 전송합니다.

Slack 이벤트 -> 게이트웨이 실행 -> 샌드박스 준비 -> OpenCode 명령 -> Slack 응답

2. 에이전트 실행을 위한 하나의 최상위 스팬 생성하기

Pipa의 경우, 최상위 실행 스팬은 pipa.run.execute입니다. 이것은 누군가 “봇이 멈췄어요” 또는 “Slack에 제대로 된 답변이 오지 않아요”라고 말할 때 제가 검색하는 스팬입니다.

3. 주요 인프라 단계에 대한 스팬 추가하기

이 스팬들은 기본적인 배관(plumbing) 작업이 제대로 작동했는지 알려줍니다:

pipa.e2b.sandbox.prepare
pipa.opencode.command

이 스팬들은 초기 질문들에 대한 답을 제공합니다. 샌드박스(sandbox)가 시작되었는가? OpenCode가 실행되었는가? 각 단계에 얼마나 걸렸는가? 에이전트가 본격적으로 작동하기 전에 실패가 발생했는가?

4. Honeycomb Agent Timeline을 위한 에이전트 호출 스팬 추가하기

처음에 제가 놓쳤던 한 가지는, 트레이스만으로는 에이전트 타임라인(agent timeline)을 얻을 수 없다는 점입니다.

수많은 스팬을 방출(emit)하면 Honeycomb은 일반적인 백엔드 트레이스를 보여줍니다. 유용하긴 하지만, 여전히 인프라처럼 읽힙니다: Slack 이벤트 수신, 샌드박스 시작, 명령 실행, 응답 전송. 어떤 서비스가 실행되었고 얼마나 걸렸는지는 볼 수 있습니다. 하지만 에이전트가 무엇을 했는지는 여전히 볼 수 없습니다.

이를 위해서는 Honeycomb의 Agent Timeline이 필요합니다.

제가 이해한 바로는, Honeycomb이 에이전트 호출 스팬 (agent invocation span)을 인식하고 해당 스팬 내부의 이벤트를 통해 에이전트의 활동을 읽을 수 있을 때 Agent Timeline이 작동합니다. 백엔드 작업만을 보여주는 대신, 트레이스 (trace)가 세션 자체를 보여줄 수 있습니다. 즉, 사용자 프롬프트 (user prompt), 어시스턴트 메시지 (assistant messages), 도구 호출 (tool calls), 도구 결과 (tool results), 재시도 (retries), 그리고 최종 출력 (final output)을 보여줍니다.

일반적인 트레이스는 다음과 같이 보일 수 있습니다:

slack.event.received -> sandbox.prepare -> opencode.command -> slack.reply.sent

에이전트 타임라인 (agent timeline)은 다음과 더 유사합니다:

invoke_agent -> user_message -> assistant_response -> tool_call -> tool_result -> assistant_response -> run_summary

이 차이는 중요합니다. Honeycomb은 일반적인 서비스 스팬 (service spans)을 자동으로 보여줄 수 있지만, 여러분의 에이전트 내부에서 무슨 일이 일어났는지 마법처럼 알 수는 없습니다. 여러분이 직접 해당 이벤트들을 방출 (emit)해야 합니다.

제가 이해하기로, "Agent Timeline"은 이를 위한 Honeycomb의 제품 뷰 (product view)입니다. 다른 관찰성 (observability) 도구들도 GenAI 트레이싱 (tracing), 스팬 이벤트 (span events), 또는 커스텀 트레이스 뷰 (custom trace views)를 지원할 수 있습니다. Honeycomb의 Agent Timeline은 제가 여기서 목표로 했던 기능입니다.

Pipa는 Honeycomb Agent Timeline과 호환되는 스팬을 방출합니다:

invoke_agent pipa.standard_opencode

해당 스팬은 Honeycomb이 실행 (run)을 그룹화하고 표시하는 데 필요한 속성 (attributes)들을 가져옵니다:

gen_ai.conversation.id
gen_ai.agent.name
gen_ai.operation.name
gen_ai.request.model
app.run_id

이것이 Honeycomb이 에이전트 세션을 관련 없는 이벤트의 더미가 아닌 타임라인으로 보여줄 수 있게 해주는 핵심입니다.

5. 에이전트의 활동을 이벤트로 첨부하기

Honeycomb은 서비스 호출을 보여줄 수 있지만, 여러분이 알려주지 않으면 에이전트가 무엇을 했는지 알 수 없습니다. 게이트웨이 (gateway)는 제가 실제로 관심을 갖는 순간들, 즉 사용자 메시지, 도구 호출, 에이전트 응답, 그리고 실행 요약 (run summary)을 전송합니다.

Pipa의 경우, 게이트웨이는 구조화된 opencode run --format json 출력을 파싱하여 다음과 같은 이벤트들을 방출합니다:

opencode.user_message
opencode.tool_call
opencode.agent_response
opencode.run_summary
opencode.parser_skipped

이를 통해 숨겨진 중간 과정, 즉 프롬프트 (prompt), 어시스턴트 가시적 텍스트 (assistant-visible text), 도구 이름 (tool names), 도구 상태 (tool status), 토큰 및 비용 데이터 (token and cost data), 재시도 마커 (retry markers), 그리고 실패 요약 (failure summaries)을 확인할 수 있습니다.

6. 실제 실패한 실행으로 검증하기

트레이스 (traces)를 추가한 후, Slack에서 봇을 실행하고 Honeycomb에서 트레이스를 조사하십시오. 트레이스는 다음 질문들에 답할 수 있어야 합니다:

Slack이 게이트웨이 (gateway)에 도달했는가?
실행 (run)이 생성되었는가?
E2B가 샌드박스 (sandbox)를 준비했는가?
OpenCode가 시작되었는가?
에이전트 (agent)가 어떤 프롬프트를 받았는가?
어떤 도구 (tools)를 호출했는가?
어떤 어시스턴트 가시적 텍스트 (assistant-visible text)를 생성했는가?
재시도 (retry)를 했는가?
실행이 실패했는가, 아니면 완료되었는가?
Slack 답장이 전송되었는가?
민감한 정보가 유출되고 있지는 않은가?

만약 트레이스가 이 질문들에 답할 수 없다면, 누락된 컨텍스트 (context)를 볼 수 있는 계층 (layer)에 스팬 (span) 또는 이벤트 (event)를 추가하십시오.

결론

AI 봇이 Slack 내부에서 실행된다면, 트레이스는 프롬프트와 최종 답장 사이에서 어떤 일이 일어났는지 확인할 수 있는 방법입니다.

봇이 제대로 응답하지 않을 때 던지는 질문들부터 시작하십시오. 그런 순간들을 중심으로 스팬 (spans)과 이벤트 (events)를 방출 (emit)하십시오. 하나의 Slack 요청은 Honeycomb에서 실제로 조사할 수 있는 하나의 실행 (run)이 되어야 합니다.

원문은 Lunch Pail Labs에 처음 게시되었습니다.