Observability: per-line timestamps in dsh-web.log and an export path for token-meter data

[ybkin1]

Summary

Two observability gaps make operating dsh harder than it needs to be. First, lines in dsh-web.log carry no timestamps, so during incident triage we cannot order entries, correlate them with external events, or compute durations — we end up inferring time from rotation boundaries and content alone. Second, the token meter collects usage in-process but has no export path, so quota management and per-session accounting have no machine-readable source. We would like (1) ISO-8601 timestamps per log line and (2) a supported way to export token usage data.

Background & Evidence

• Timestamps: when the dsh web process is managed by an external process supervisor, restarts and log rotation are routine. In a recent incident we could not determine which log lines preceded a crash, or in what order interleaved lines from consecutive runs occurred, because nothing in the file anchors entries to points in time. This is a qualitative but recurring pain: every cross-restart investigation hits it.
• Token meter: usage data exists in the running process, but there is no CLI command, HTTP endpoint, or file export that exposes it. For monthly per-user/per-session quota tracking we currently have no reliable machine-readable artifact to read.

Failure Mode or Reproduction

• Repro 1: tail dsh-web.log across a restart — individual lines cannot be attributed to a time, and lines from consecutive runs cannot be ordered relative to each other or to external events.
• Repro 2: try to answer "how many tokens did session X consume last week" from the filesystem or CLI — there is no exported artifact or command that can answer it.

Proposed Fix

1. Log timestamps: prefix every dsh-web.log line with an ISO-8601 UTC timestamp (plus level; pid optional). Alternatively, make the log format pluggable (plain vs. JSON lines) so operators can ingest it directly.
2. Token usage export, any of the following would work:
   • CLI: dsh usage export --since <ts> [--format jsonl|csv];
   • an HTTP endpoint on the web server returning per-session/per-day aggregates;
   • or a periodic JSONL dump written next to the logs.
     Useful fields: session id, timestamps, prompt/completion/total counts (plus any breakdown the meter already tracks).

Additional Context

• dsh: @deepseek-ai/dsh 0.1.1-rc.2 (developer preview)
• OS: Windows 10 x64 (build 10.0.18363)
• Node.js: v22.23.2

[liyangbing]

这个 observability 需求可以用 SandBase Harness 的几个公开接口作为一个可复用参考，不过它们不等同于 DSH 的 dsh usage export：

• 每个 Session 持久化 input_tokens / output_tokens，可通过 GET /v1/sessions/:id 读取；
• GET /v1/sessions/:id/events 返回带事件 id、类型、创建/处理时间的分页事件；
• GET /v1/sessions/:id/events/stream 支持 Last-Event-ID 断点续传，适合外部 collector 在重启后继续消费；
• GET /v1/x/metrics 提供 Prometheus 文本格式，/v1/x/metrics/summary 提供 JSON 汇总。

参考实现和接口文档：

• https://github.com/sandbaseai/sandbase-harness/blob/main/src/api/routes/runtime.ts
• https://github.com/sandbaseai/sandbase-harness/blob/main/src/api/routes/sessions.ts
• https://github.com/sandbaseai/sandbase-harness/blob/main/src/api/routes/stream.ts
• https://github.com/sandbaseai/sandbase-harness/blob/main/docs/api.md#observability

设计上我会把日志输出和业务事件分开：日志统一 ISO-8601/JSONL，Session 事件作为可回放事实源，token usage 作为 Session 聚合字段，同时保留按事件/请求粒度的明细。这样既能跨重启排障，也能让 quota collector 不依赖日志文本解析。