Ch13. Observability와 Deployment
Eve의 OpenTelemetry, Workflow tags, Vercel/self-host 배포, 운영 점검 절차를 정리한다.
핵심 요약
- Eve 운영 관측성은 HTTP 로그만으로 부족하며 session, turn, step, tool, sandbox, model usage를 함께 봐야 합니다.
- OpenTelemetry, Workflow tags, runtime hooks는 각기 다른 관측 표면이라 한곳에만 의존하면 안 됩니다.
- Vercel 배포와 self-host 배포 모두
.eve/산출물, health endpoint, stream endpoint를 release checklist에 넣어야 합니다.
Eve는 durable agent framework이라 일반 HTTP request 로그만으로는 관측성이 부족합니다. session, turn, step, tool call, subagent run, approval park, sandbox backend, model usage를 함께 봐야 합니다.
세 가지 관측 표면
| 표면 | 설정 위치 | 용도 |
|---|---|---|
| Workflow run tags | framework 자동 | Vercel Workflow/Agent Runs에서 session tree와 usage 파악 |
| OpenTelemetry | agent/instrumentation.ts | 외부 observability backend로 span export |
| Runtime hooks | agent/hooks/** | 감사 로그, metric, alert, warehouse 적재 |
이 셋은 대체 관계가 아니라 보완 관계입니다.
instrumentation.ts
import { defineInstrumentation } from "eve/instrumentation";
import { registerOTel } from "@vercel/otel";
export default defineInstrumentation({
setup: ({ agentName }) =>
registerOTel({
serviceName: agentName,
}),
recordInputs: false,
recordOutputs: false,
});기본값으로 inputs/outputs recording이 켜질 수 있으니 민감 데이터가 오가는 production에서는 명시적으로 false를 검토합니다. exporter destination, retention, access control도 privacy/security review 대상입니다.
Runtime context enrichment
events["step.started"]에서 AI SDK span runtimeContext를 추가할 수 있습니다.
export default defineInstrumentation({
events: {
"step.started"(input) {
return {
runtimeContext: {
"tenant.id": input.session.auth.current?.attributes.tenantId ?? "unknown",
"channel.kind": input.channel.kind,
},
};
},
},
});규칙:
- cardinality가 너무 높은 값을 남발하지 않는다.
- secret/PII를 넣지 않는다.
- tenant/user id는 hashing 또는 internal id 정책을 따른다.
- channel metadata는 channel이 project한 값만 신뢰한다.
Eve가 자동으로 남기는 Workflow tags
Eve는 $eve.* 예약 attribute를 Workflow run에 남깁니다.
| Tag | 의미 |
|---|---|
$eve.type | session, turn, subagent |
$eve.parent | immediate parent session |
$eve.root | root session |
$eve.subagent | subagent node id |
$eve.trigger | channel kind |
$eve.title | 첫 사용자 메시지 기반 title |
$eve.model | turn model id |
$eve.input_tokens | 누적 input tokens |
$eve.output_tokens | 누적 output tokens |
$eve.tool_count | tool count |
이 tag들은 best-effort라, 기록에 실패해도 session을 깨지 않도록 설계했습니다. 그래서 감사의 단일 source of truth로 삼지 말고, 필요하면 hook 기반 audit log를 따로 남깁니다.
Vercel 배포
Vercel 환경에서 eve build는 .vercel/output을 생성하고, Vercel Workflow와 Vercel Sandbox를 활용합니다.
기본 절차:
eve build
vercel deploy검증:
curl https://<deployment>/eve/v1/health
curl -X POST https://<deployment>/eve/v1/session \
-H 'content-type: application/json' \
-d '{"message":"Hello from production"}'
curl https://<deployment>/eve/v1/session/<sessionId>/streamSelf-host 배포
Eve는 Vercel 외부에서도 Node service로 실행할 수 있습니다.
eve build
PORT=3000 eve start --host 0.0.0.0Self-host에서 명시해야 할 것:
| 항목 | 기준 |
|---|---|
| workflow state | .workflow-data persistent storage |
| model auth | direct provider key 또는 AI Gateway API key |
| route auth | Vercel OIDC 대신 자체 auth |
| sandbox | Docker/microsandbox/custom backend |
| schedules | eve start가 Nitro schedule runner 실행 |
| logs | process manager/collector |
| TLS/routing | reverse proxy 또는 platform |
Build artifact 점검
배포 전 반드시 .eve/를 확인합니다.
| Artifact | 체크 |
|---|---|
diagnostics.json | error/warning 없음 |
agent-discovery-manifest.json | 예상 파일만 포함 |
compiled-agent-manifest.json | tools/connections/channels/schedules/subagents 확인 |
module-map.mjs | compiled module resolution 가능 |
이 artifact는 security review와 release evidence에 함께 넣어도 됩니다.
Runtime runbook
| 증상 | 확인 |
|---|---|
| production 401 | route auth policy, placeholderAuth 제거 여부 |
| session.waiting에서 멈춤 | pending approval/question/OAuth |
| tool이 안 보임 | eve info, dynamic resolver event, disabled default |
| subagent 결과 없음 | child session stream, parent proxy input request |
| sandbox command 실패 | backend availability, network policy, bootstrap |
| 비용 급증 | token tags, tool count, compaction threshold |
| trace 누락 | instrumentation setup, exporter config, record flags |
프로덕션 SLO 후보
| SLO | 측정 |
|---|---|
| session start success | POST /session 2xx ratio |
| turn completion | turn.completed / started |
| no failed step | step.failed rate |
| approval latency | input.requested to response |
| model latency | step.started to step.completed |
| cost per task | token usage + tool infra |
| sandbox setup latency | first sandbox use duration |
| eval pass rate | CI and scheduled eval |
배포 체크리스트
| Gate | 기준 |
|---|---|
| build | eve build 성공 |
| diagnostics | .eve/diagnostics.json clean |
| auth | production route auth fail-closed 확인 |
| secrets | env/secret manager, artifact에 없음 |
| sandbox | backend/network policy 명시 |
| eval | eve eval --strict 통과 |
| smoke | health/session/stream live check |
| observability | OTel 또는 hook audit path 동작 |
| rollback | model/prompt/tool rollback 절차 |
Eve 배포는 “서버가 뜬다”가 아니라 “장기 workflow가 재개되고, stream이 복구되고, sandbox와 tool이 정책대로 작동한다”까지 검증해야 완료입니다.