add token profile diagnostics · Entire
add token profile diagnostics
324916d·
peyton-alt·3w ago·3 files·+645 added/-0 removed
Sessions
cdebea3708fdView transcript
Changes
3
cmd/entire/cli
Mroot.go+1
Atokens_profile.go+413
Atokens_profile_test.go+231
83 unmodified lines
84
85
86
87
88
89
90
83 unmodified lines
// Noun groups (canonical homes for subcommands).
cmd.AddCommand(newSessionsCmd()) // 'session' (with 'sessions' as Cobra alias)
cmd.AddCommand(newCheckpointGroupCmd()) // 'checkpoint' / 'cp' / 'checkpoints'
cmd.AddCommand(newTokensGroupCmd()) // 'tokens'
cmd.AddCommand(newAgentGroupCmd()) // 'agent'
cmd.AddCommand(newAuthCmd()) // 'auth'
cmd.AddCommand(newDoctorCmd()) // 'doctor' (group: trace/logs/bundle)
Mcmd/entire/cli/root.go+1
package cli
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"github.com/entireio/cli/cmd/entire/cli/agent"
"github.com/entireio/cli/cmd/entire/cli/checkpoint"
"github.com/entireio/cli/cmd/entire/cli/checkpoint/id"
"github.com/spf13/cobra"
)
type tokensProfileReport struct {
Source string `json:"source"`
CheckpointsAvailable int `json:"checkpoints_available"`
CheckpointsAnalyzed int `json:"checkpoints_analyzed"`
CheckpointsWithTokenData int `json:"checkpoints_with_token_data"`
MissingTokenData int `json:"missing_token_data"`
MetadataReadWarnings int `json:"metadata_read_warnings,omitempty"`
Tokens *sessionTokensUsage `json:"tokens,omitempty"`
Signals []tokensProfileSignal `json:"signals,omitempty"`
Recommendations []sessionTokensRecommendation `json:"recommendations,omitempty"`
Limitations []string `json:"limitations,omitempty"`
}
type tokensProfileSignal struct {
ID string `json:"id"`
Label string `json:"label"`
Count int `json:"count"`
Percent int `json:"percent"`
CheckpointIDs []string `json:"checkpoint_ids,omitempty"`
}
var tokensProfileSignalDefinitions = []tokensProfileSignalDefinition{
{id: "context-replay-hotspot", label: "Cache/context replay hotspot"},
{id: "api-call-amplification", label: "API call amplification"},
{id: "subagent-heavy", label: "Subagent-heavy sessions"},
{id: "missing-token-data", label: "Missing token data"},
}
func newTokensProfileCmd() *cobra.Command {
var jsonFlag bool
var limitFlag int
var allFlag bool
cmd := &cobra.Command{
Use: "profile",
Short: "Aggregate token usage and recommendations across checkpoint history",
Long: `Aggregate token usage and recommendations across committed checkpoint history.
The profile reads committed checkpoint metadata only. It does not inspect
transcripts or source files, so it is deterministic and avoids adding token
cost while diagnosing token usage. By default it scans the latest 50 committed
checkpoints; use --limit or --all to change the scope.`,
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
limit := limitFlag
if allFlag {
limit = 0
} else if limit <= 0 {
return errors.New("--limit must be positive unless --all is used")
}
return runTokensProfile(cmd.Context(), cmd, jsonFlag, limit)
},
}
cmd.Flags().BoolVar(&jsonFlag, "json", false, "Output as JSON")
cmd.Flags().IntVar(&limitFlag, "limit", 50, "Maximum committed checkpoints to analyze")
cmd.Flags().BoolVar(&allFlag, "all", false, "Analyze all committed checkpoints")
return cmd
}
func runTokensProfile(ctx context.Context, cmd *cobra.Command, jsonOutput bool, limit int) error {
repo, err := openRepository(ctx)
if err != nil {
cmd.SilenceUsage = true
fmt.Fprintln(cmd.ErrOrStderr(), "Not a git repository.")
return NewSilentError(err)
}
defer repo.Close()
store := checkpoint.NewCommittedReadStore(ctx, repo)
infos, err := store.ListCommitted(ctx)
if err != nil {
return fmt.Errorf("failed to list checkpoints: %w", err)
}
report, err := buildTokensProfileReport(ctx, store, infos, limit)
if err != nil {
return err
}
if jsonOutput {
return writeTokensProfileJSON(cmd.OutOrStdout(), report)
}
writeTokensProfileText(cmd.OutOrStdout(), report)
return nil
}
func buildTokensProfileReport(ctx context.Context, store *checkpoint.GitStore, infos []checkpoint.CommittedInfo, limit int) (tokensProfileReport, error) {
checkpointsAvailable := len(infos)
infos = limitTokensProfileCheckpoints(infos, limit)
report := tokensProfileReport{
Source: "committed_checkpoints",
CheckpointsAvailable: checkpointsAvailable,
CheckpointsAnalyzed: len(infos),
}
signals := make(map[string]*tokensProfileSignal, len(tokensProfileSignalDefinitions))
var aggregate *agent.TokenUsage
for _, info := range infos {
if err := ctx.Err(); err != nil {
return tokensProfileReport{}, err //nolint:wrapcheck // Propagating context cancellation.
}
summary, err := store.ReadCommitted(ctx, info.CheckpointID)
if err != nil {
return tokensProfileReport{}, fmt.Errorf("failed to read checkpoint %s: %w", info.CheckpointID, err)
}
if summary == nil {
report.MissingTokenData++
addTokensProfileSignal(signals, "missing-token-data", info.CheckpointID, report.CheckpointsAnalyzed)
continue
}
usage, metadataReadWarning, err := tokensProfileCheckpointUsage(ctx, store, info.CheckpointID, summary)
if err != nil {
return tokensProfileReport{}, err
}
if metadataReadWarning {
report.MetadataReadWarnings++
}
tokens := buildSessionTokensUsage(usage)
if tokens == nil {
report.MissingTokenData++
addTokensProfileSignal(signals, "missing-token-data", info.CheckpointID, report.CheckpointsAnalyzed)
continue
}
report.CheckpointsWithTokenData++
aggregate = addCheckpointTokenUsage(aggregate, usage)
addTokensProfileTokenSignals(signals, info.CheckpointID, tokens, report.CheckpointsAnalyzed)
}
report.Tokens = buildSessionTokensUsage(aggregate)
report.Signals = orderedTokensProfileSignals(signals)
report.Recommendations = tokensProfileRecommendations(report)
report.Limitations = tokensProfileLimitations(report)
return report, nil
}
func limitTokensProfileCheckpoints(infos []checkpoint.CommittedInfo, limit int) []checkpoint.CommittedInfo {
if limit <= 0 || len(infos) <= limit {
return infos
}
return infos[:limit]
}
func tokensProfileCheckpointUsage(ctx context.Context, store *checkpoint.GitStore, checkpointID id.CheckpointID, summary *checkpoint.CheckpointSummary) (*agent.TokenUsage, bool, error) {
if summary == nil {
return nil, false, nil
}
metas := make([]*checkpoint.CommittedMetadata, 0, len(summary.Sessions))
metadataReadWarning := false
for i := range len(summary.Sessions) {
meta, err := store.ReadSessionMetadata(ctx, checkpointID, i)
if err != nil {
if ctxErr := ctx.Err(); ctxErr != nil {
return nil, false, ctxErr //nolint:wrapcheck // Propagating context cancellation.
}
metadataReadWarning = true
continue
}
metas = append(metas, meta)
}
sessionUsage := aggregateCheckpointTokenUsage(metas)
if !metadataReadWarning && sessionUsage != nil {
return sessionUsage, false, nil
}
if summary.TokenUsage != nil {
return summary.TokenUsage, metadataReadWarning, nil
}
return sessionUsage, metadataReadWarning, nil
}
func writeTokensProfileJSON(w io.Writer, report tokensProfileReport) error {
enc := json.NewEncoder(w)
enc.SetIndent("", " ")
if err := enc.Encode(report); err != nil {
return fmt.Errorf("failed to encode token profile report: %w", err)
}
return nil
}
func writeTokensProfileText(w io.Writer, report tokensProfileReport) {
fmt.Fprintln(w, "Token profile")
fmt.Fprintln(w)
fmt.Fprintf(w, "Source: %s\n", report.Source)
fmt.Fprintf(w, "Checkpoints available: %d\n", report.CheckpointsAvailable)
fmt.Fprintf(w, "Checkpoints analyzed: %d\n", report.CheckpointsAnalyzed)
fmt.Fprintf(w, "With token data: %d\n", report.CheckpointsWithTokenData)
fmt.Fprintf(w, "Missing token data: %d\n", report.MissingTokenData)
if report.MetadataReadWarnings > 0 {
fmt.Fprintf(w, "Metadata warnings: %d\n", report.MetadataReadWarnings)
}
writeTokenUsageSection(w, report.Tokens)
writeTokensProfileSignals(w, report.Signals)
if len(report.Recommendations) > 0 {
writeTokenRecommendations(w, report.Recommendations)
}
writeTokenLimitations(w, report.Limitations)
}