/maple-agent-tracing-eve

name: maple-agent-tracing-eve
description: "Trace eve agents (Vercel's eve framework, npm `eve`) with Maple: add one OpenTelemetry destination file under agent/instrumentation/ so each eve session is one Maple Agent Session with transcript, tool calls, subagent lanes, approvals and tokens. Covers eve dev, eve start, the channel audience that gates message content, and dropping the workflow engine's spans. Triggers on 'trace my eve agent', 'add Maple to eve', 'agent sessions for eve', 'OpenTelemetry for eve'."

Maple agent tracing: eve

Goal

One eve session (`wrun_...`) = one Maple Agent Session. One user message = one turn = one trace rooted at `invoke_agent <agent>`, with `agent.step` spans holding a `chat <model>` span (model, provider, tokens, messages) and `execute_tool <tool>` spans (arguments, result, failures). Subagents nest inside the caller's trace and show as their own lanes.

eve owns the tracer provider and writes `gen_ai.conversation.id` (the root session id) on every agent span. You add a destination; you never start an SDK and never pass a conversation id.

Known gaps (tell the user, don't try to fix):

• Outside `eve dev`, message content is exported only for `public` conversations (Step 4).
• Cost shows as unpriced with a model called directly at its provider. With Vercel AI Gateway, eve writes `gen_ai.usage.cost` on the `agent.step` span; Maple counts it in the session total (the per-model table has tokens, not cost).
• eve does not log failed exports (Step 6).

Step 0: Detect

• `eve` version in `package.json` / lockfile.
• `>= 0.62`: this skill. Exercised on 0.62.0, 0.70.3, 0.72.1, 0.77.0 and 0.78.0 with the Step 2/3 files unchanged; every version produced complete sessions in Maple.
• `0.62` to `0.71`: each tool call is an `agent.action` span wrapping `execute_tool`. Maple shows the wrapper as a structure row and counts one tool call. Expected.
• `< 0.62`: telemetry lives in `agent/instrumentation.ts` (`defineInstrumentation({ setup })` calling `registerOTel`), and eve ignores `agent/instrumentation/` without an error: the Step 2 files export nothing (tested on 0.61.1). With `experimental: { instrumentationProviders: true }` in `agent.ts` they export, but the `exportPolicy` is ignored and every workflow span goes out. Don't use the flag: upgrade (`npm install eve@latest`), delete `agent/instrumentation.ts` (until then `eve build` fails with `Found removed instrumentation file`), remove the flag, then do Steps 2-3. Move every other exporter from the old `setup` into its own `otelIntegration({ traceExporter })` file; `serviceName` becomes `otel({ resource })`, `functionId` becomes `otel({ functionId })`, `events["step.started"]` runtime context becomes `otelIntegration({ runtimeContext })`. See https://eve.dev/docs/observability/instrumentation-migration.
• Tell the user: from 0.35 to 0.61 the old file recorded no content unless `recordInputs`/`recordOutputs` were set (before 0.35 it recorded content by default); after the upgrade, content is recorded during `eve dev` and for `public` conversations (Step 4). The first `eve dev` after the upgrade deletes the local `.eve/.workflow-data` (incompatible storage layout), so open local dev sessions are lost.
• Node.js `>= 24` at runtime; eve enforces it. bun or pnpm as the package manager is fine.
• Layout: one agent in `agent/`, or a workspace with `agents/<name>/agent/`. In a workspace add the files to each member's `agent/instrumentation/` (not exercised; run Step 7 per member).
• Existing files in `agent/instrumentation/`:
• An `otel()` file: add the resource attributes from Step 3 to it. Two `otel()` files are a boot error.
• Other `otelIntegration()` files (Honeycomb, Braintrust, Datadog...): keep them. Maple is one more file; each destination has its own `exportPolicy`.
• `agent-runs.ts`, `local.ts`: leave them.
• Search for `NodeSDK`, `registerOTel(`, `registerTelemetry(`, `@ai-sdk/otel`, `NodeTracerProvider`. eve replaces all of them with `otelIntegration()`; don't add one, and tell the user if one exists.
• `eve` depends on `ai`. Use this skill, not `maple-agent-tracing-vercel-ai-sdk`.
• `agent/skills/maple-agent-tracing-eve/` exists (an `npx skills add` run in an eve project installs into the eve agent's own skills, and `skills-lock.json` records it): it would ship with the agent as a runtime skill. Tell the user and remove both the directory and its `skills-lock.json` entry once setup is done, unless they want it there.
• Models: a string id in `agent.ts` (`model: "openai/gpt-…"`) runs through Vercel AI Gateway; a provider object (`openai()` from `eve/models/openai`, `createOpenRouter(...)`, `anthropic()`) calls the provider directly. This decides the cost line in Step 7.

Step 1: Key and region

• US `https://ingest.maple.dev/v1/traces`, EU `https://ingest.eu.maple.dev/v1/traces`. The exporter takes the full URL. Header `authorization: Bearer <key>`.
• Key in the user's prompt: use it. No key: use the literal `MAPLE_TEST` (ingest accepts and discards it) and tell the user to replace it with their key from Settings → Ingestion.
• Private `maple_sk_` keys never go in browser code. Ingest keys are write-only.
• eve loads `.env.local` for `eve dev` and `eve start`: put `MAPLE_INGEST_KEY=<key>` there (check it is gitignored). Deployments read the host's environment variables.
• Instrumentation files run at server start, not at build: `eve build` works without the key.
• Never let an unset variable become `Bearer undefined`. When the key is missing, log one warning and export `disableInstrumentation()` so the agent runs normally (Step 2 does this).
• A 401 `ingest_unauthorized` with a key you trust usually means the key belongs to the other region: try the other endpoint.

Step 2: Install and add the destination

npm install @vercel/otel

Use the repo's package manager. Create `agent/instrumentation/maple.ts`:

import { OTLPHttpProtoTraceExporter } from "@vercel/o