MoonshotAI / MoonshotAI/kimi-code
fix(telemetry): make CloudAppender shutdown durable
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 7.5k
- Forks
- 1.2k
- Avg merge
- 11h 53m
- Merged PRs (30d)
- 350
Description
Context
PR #2230 intentionally kept kap-server cloud telemetry wiring narrow. Its server-local close path is bounded and best-effort, but the shared CloudAppender still does not provide durable ownership of flush work across threshold, periodic, and shutdown triggers.
Problem
- A shutdown caller cannot wait for or cancel all flush work already in flight through a single lifecycle contract.
- Timeout races can leave remote work running after the caller has given up, without making ownership explicit.
- Buffered/spooled payloads need a defined recovery path so a bounded shutdown does not silently strand them forever.
This belongs in the shared telemetry implementation, not in kap-server-specific wrappers.
Scope
- Give
CloudAppenderone owner for queued and in-flight flush work. - Define deadline/cancellation semantics at the shared telemetry boundary: cancel network and retry work, then hand unsent events to the local durable spool.
- Make explicit flush and shutdown idempotent under concurrent periodic/threshold flushes.
- Replay recoverable v2 spool data before new payloads, while leaving the legacy telemetry pipeline's spool namespace untouched.
- Keep telemetry failures non-fatal to the host application.
Acceptance criteria
- Concurrent local flush triggers neither duplicate nor lose ownership of a batch.
- A shutdown deadline cancels remote requests and retry waits; shutdown completes after each unsent batch is either delivered or handed to local durable storage. Hosts may retain an outer hard cap around non-cancellable local storage I/O.
- Delivery is at-least-once across an ambiguous remote cancellation boundary; stable event IDs preserve the server's deduplication key instead of claiming client-side exactly-once delivery.
- A later appender instance replays recoverable v2 spool data, and legacy spool files remain owned by the legacy pipeline.
- Tests cover in-flight shutdown, deadline expiry, retry/replay, and repeated shutdown.
Follow-up to #2230.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the shared telemetry implementation and the CloudAppender entry point, then inspect how threshold, periodic, shutdown, and v2 spool handling currently interact. Use the existing telemetry tests as a baseline and add coverage for in-flight shutdown, deadline expiry, retry/replay, and repeated shutdown. Done means ownership is unambiguous, unsent batches reach durable storage, v2 replay works, and legacy spool files remain untouched.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- observability
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100