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에 넣어야 합니다.
0.80 이후: trace 정책과 실행 데이터 보존
세션 trace 정책이 input/output을 모두 허용하면 Workflow World의 기본 보존 정책을 사용합니다. trace를 버리거나 어느 한쪽이라도 제외하면 실행 종료 후 payload·stream 삭제를 요청하는 retention 0을 선택합니다. 개발 외 환경에서 private/unknown 대화는 OTel 목적지가 없어도 이 기본 삭제 요청 대상입니다.
experimental.workflow.retention을 0 또는 "default"로 명시하면 보존 정책을 별도로 정할 수 있습니다. 실제 삭제는 선택한 World의 지원에 달려 있습니다. 실행 중 payload, 남는 ID·시각·attribute, 외부 OTel·provider·tool·channel 데이터까지 지우는 옵션은 아닙니다. 삭제된 세션 조회의 410 session_expired를 클라이언트에서 처리합니다.
eve deploy로 만든 새 Vercel 프로젝트는 100% sampling을 설정합니다. 기존 프로젝트는 sampling rule을 별도 확인합니다.
Run-data retention · Agent Runs.
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/ | 외부 observability backend로 span export |
| Runtime hooks | agent/hooks/** | 감사 로그, metric, alert, warehouse 적재 |
이 셋은 대체 관계가 아니라 보완 관계입니다.
instrumentation.ts
단일 instrumentation.ts는 제거된 API입니다. 다음 파일로 교체하고 예전 파일을 삭제합니다.
import { otel } from "eve/instrumentation/otel";
export default otel({
functionId: "support-agent",
traceChannelRequests: true,
tracePolicy: () => ({
emit: true,
recordInputs: false,
recordOutputs: false,
}),
});exporter는 목적지별 파일의 otelIntegration()으로 옮기며 startup registerOTel() 호출을 제거합니다. 새 기본값은 OTel 목적지가 있을 때 개발 환경·공개 대화의 내용을 포함할 수 있으므로 정책을 명시합니다. destination의 exportPolicy와 보존·접근 정책도 함께 검사합니다.
Runtime context enrichment
events["step.started"]의 runtimeContext는 목적지의 otelIntegration({ runtimeContext })로 이전합니다. eve. 접두사는 예약되어 있습니다. channel metadata는 타입을 좁힌 뒤 읽고 secret·개인정보를 넣지 않습니다. tracePolicy가 제외한 내용은 resolver에서도 사용할 수 없습니다.
Eve가 자동으로 남기는 Workflow tags
0.11 소스 분석의 $eve.* tag 목록을 현재 observability 스키마로 고정하지 않습니다. 현재 OTel에서는 invoke_agent → agent.step → chat/execute_tool의 topology와 구조화된 session·turn 식별자를 사용합니다. tool/approval 연계는 gen_ai.tool.call.id, 실패는 error.type을 확인합니다.
Vercel Agent Runs는 별도 destination이며 exportPolicy로 내용을 추가 제한할 수 있습니다. 강제 감사 장부와 trace export의 보존·접근 정책을 각각 관리합니다.
Vercel 배포
Vercel 환경에서 eve build는 .vercel/output을 생성하고, Vercel Workflow와 Vercel Sandbox를 활용합니다.
기본 절차:
eve build
vercel deploy검증:
curl https://your-agent.example.com/eve/v1/health
eve remote connect --url https://your-agent.example.comSelf-host 배포
Eve는 Vercel 외부에서도 Node service로 실행할 수 있습니다.
eve build
PORT=3000 eve start --host 0.0.0.0Self-host에서 명시해야 할 것:
| 항목 | 기준 |
|---|---|
| workflow state | .eve/.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 제거 여부 |
| turn.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이 정책대로 작동한다”까지 검증해야 완료입니다.
현재 self-host 배포 추가 점검
기본 local World의 영속 경로는 .eve/.workflow-data입니다. reverse proxy는 /eve/와 /.well-known/workflow/를 모두 전달해야 callback이 도달합니다. World 패키지는 Eve와 같은 Workflow 5 beta 계열의 호환 버전을 고정하며 환경별 자격 증명은 runtime 환경에서 읽습니다. health 성공만으로 인증·session·stream·재개 검증을 대체하지 않습니다.