Logging and Usage

How to record AI calls by user, city, and model.

Applications choose where to store business usage records; hooks provide a consistent integration point.

Agent Session diagnostics

Agent runtime logs use daily JSONL files under the Agent's private data root at logs/YYYY-MM-DD.jsonl. City defaults to ~/.downcity/agents/<agent_id>/logs/. Model execution, delegation, and [session.storage.worker] diagnostics can be correlated through Agent and Session/Turn identifiers, delegation phases, and Worker pool, slot, and request identifiers.

Runtime exception trees retain allowlisted types and codes with bounded original and secondary causes. Worker and delegation diagnostics exclude message bodies, SQL parameters, credentials, raw exception messages, and stacks. Log persistence is best effort and never changes transaction outcomes. See Session failure troubleshooting for correlation fields, recovery boundaries, and interpretation limits.

  • user_id
  • city_id (optional source)
  • model
  • started_at
  • ended_at
  • status
  • error

Where to record

ai.hook.after(async (ctx) => {
  await logService.write({
    user_id: ctx.user?.user_id,
    model: ctx.variant?.id,
    model_meta: ctx.variant?.meta,
    started_at: ctx.started_at,
    ended_at: ctx.ended_at,
  });
});

Once many products share one runtime, usage data becomes centralized by default, which makes cost analysis and business decisions much easier later.