Ch13. Observability와 Deployment

Eve는 durable agent framework이라 일반 HTTP request 로그만으로는 관측성이 부족합니다. session, turn, step, tool call, subagent run, approval park, sandbox backend, model usage를 함께 봐야 합니다.

세 가지 관측 표면

이 셋은 대체 관계가 아니라 보완 관계입니다.

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들은 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>/stream

Self-host 배포

Eve는 Vercel 외부에서도 Node service로 실행할 수 있습니다.

eve build
PORT=3000 eve start --host 0.0.0.0

Self-host에서 명시해야 할 것:

Build artifact 점검

배포 전 반드시 .eve/를 확인합니다.

이 artifact는 security review와 release evidence에 함께 넣어도 됩니다.

Runtime runbook

프로덕션 SLO 후보

배포 체크리스트

Eve 배포는 “서버가 뜬다”가 아니라 “장기 workflow가 재개되고, stream이 복구되고, sandbox와 tool이 정책대로 작동한다”까지 검증해야 완료입니다.