Skip to content

docs: explain what Cortex shows and why it is worth running — interpreting the metrics and the value case #963

Description

@huang195

Feature Description

The docs will say how to install Cortex and how to drive it, but not what to do with what you
see. Someone looking at a session's token counts, its cache-read versus cache-write split, a cost
figure and latency percentiles has no page telling them what any of it means, which numbers
matter, or why leaving Cortex running is worth it.

This backs exit criterion 5 of the v0.9.0 release: a new user can self-serve on a typical
workstation, using the docs alone.

Proposed Solution

  • What Cortex is for, readable before installing: what it shows you that you cannot
    otherwise see
  • The value case in concrete terms — what decisions the numbers support: spotting an
    expensive prompt, seeing whether caching is working, catching a runaway session, deciding
    whether pruning is worth enabling
  • How to read a session: what each token category means, and why cache-read and cache-write
    are priced differently rather than being one number
  • How to read cost: what is included, what is estimated, and where the rates come from
  • How to read latency: time to first token versus total response time, and what the
    percentiles actually tell you
  • How to read the tool-pruning savings figure, including what a zero means for an agent with
    no tool inventory
  • A worked example on a real session, with real output rather than paraphrase
  • Verified by someone outside the team reading only the docs

Additional Context

Part of the Cortex v0.9.0 release. Complements #959 (the first-run path — how to get there) and
#960 (troubleshooting — what to do when it breaks); this issue is what the results mean once you
are there, and why they are worth having.

Depends on the metrics work landing: #950, #951, #952.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationhigh priorityMust be address ASAP

Type

No type

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions