counters

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 6, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package counters exposes the cumulative drop / overflow counters surfaced on /healthz per ARCHITECTURE § 6.5.

Counters are process-wide and atomic. The writer goroutine, the trace finalize path, and any future drop site all bump them; the /healthz handler reads them.

Index

Constants

This section is empty.

Variables

View Source 
var DefaultTimingBounds = []float64{1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 10000, math.Inf(1)}

DefaultTimingBounds covers the operating range we expect for per-trace work: drain typically <100ms, parse <50ms, sqlite <100ms. Tail bounds (1s, 10s) catch path-blocked traces so the diag is still honest about p99 even when something stalls upstream.

Functions

This section is empty.

Types

type Counters 

type Counters struct {

	// Per-stage timing histograms. Drain = sink-close → drainer-join.
	// Parse = JSON unmarshal + SSE event walk + decompression. SQLite =
	// AppendTrace (one tx covering JSONL append + UPSERT + session-
	// inference IN-clause + UPDATE).
	DrainHist  *Histogram
	ParseHist  *Histogram
	SQLiteHist *Histogram
	// contains filtered or unexported fields
}

Counters is the shared atomic counter set.

func New 

func New() *Counters

func (*Counters) AddBytes 

func (c *Counters) AddBytes(n int64)

AddBytes records the size of a single JSONL line append. Used to expose total recorded bytes on /healthz without walking the data dir.

func (*Counters) AddCacheCreationTokens 

func (c *Counters) AddCacheCreationTokens(n int64)

AddCacheCreationTokens records the cache-creation-token count for a single trace (T3). n may be 0, which is a no-op.

func (*Counters) AddCachedTokens 

func (c *Counters) AddCachedTokens(n int64)

AddCachedTokens records the cached-prompt-token count for a single trace (T3). n may be 0, which is a no-op.

func (*Counters) AddCompletionTokens 

func (c *Counters) AddCompletionTokens(n int64)

AddCompletionTokens records the completion-token count for a single trace (T3). n may be 0, which is a no-op.

func (*Counters) AddEvictedBytes added in v0.1.1 

func (c *Counters) AddEvictedBytes(n int64)

AddEvictedBytes bumps the cumulative on-disk bytes reclaimed by the storage coordinator's eviction loop (JSONL + media). Matches what /healthz.storage reports.

func (*Counters) AddEvictedTraces added in v0.1.1 

func (c *Counters) AddEvictedTraces(n int64)

AddEvictedTraces bumps the cumulative count of trace rows removed by the storage coordinator's eviction loop (v0.1.1). One eviction pass typically deletes N traces and N media subtrees in one call.

func (*Counters) AddMediaFiles 

func (c *Counters) AddMediaFiles(n int64)

AddMediaFiles records the number of media files extracted from a single trace. Called once per finalize when media extraction is on, with the count of files written for that trace (zero is a valid value but is skipped by callers to avoid a no-op atomic add).

func (*Counters) AddPromptTokens 

func (c *Counters) AddPromptTokens(n int64)

AddPromptTokens records the prompt-token count for a single trace (T3). n may be 0, which is a no-op.

func (*Counters) AddReasoningTokens 

func (c *Counters) AddReasoningTokens(n int64)

AddReasoningTokens records the reasoning-token count for a single trace (T3). n may be 0, which is a no-op.

func (*Counters) IncAppended 

func (c *Counters) IncAppended()

IncAppended is bumped on each successful JSONL append.

func (*Counters) IncAppendedByStatus 

func (c *Counters) IncAppendedByStatus(status int)

IncAppendedByStatus bumps the right status-bucketed counter. status==0 or a sentinel (-1) lands nowhere; only 200/4xx/5xx are tallied — those are the buckets that map cleanly to upstream-health questions.

func (*Counters) IncDropJSONLFail 

func (c *Counters) IncDropJSONLFail()

IncDropJSONLFail is bumped when JSONL append fails (disk full, EIO).

func (*Counters) IncDropSQLiteFail 

func (c *Counters) IncDropSQLiteFail()

IncDropSQLiteFail is bumped when SQLite upsert fails after JSONL succeeds.

func (*Counters) IncDropWriterFull 

func (c *Counters) IncDropWriterFull()

IncDropWriterFull is bumped when the writer channel was full and a trace's metadata was dropped (writer.Writer.TrySend returns false).

func (*Counters) IncIndexed 

func (c *Counters) IncIndexed()

IncIndexed is bumped on each successful SQLite mirror upsert.

func (*Counters) IncSlowTrace 

func (c *Counters) IncSlowTrace()

IncSlowTrace is bumped when finalize sees an end-to-end duration over the operator-configured slow-trace threshold.

func (*Counters) IncTracesDroppedCaptureFilter added in v0.1.2 

func (c *Counters) IncTracesDroppedCaptureFilter()

IncTracesDroppedCaptureFilter is bumped by the proxy handler when the capture_filter rejects a request path before a trace is started. Counterpart to the existing drop_* counters but pre-trace — the request still forwards upstream, just without recording.

func (*Counters) IncTruncatedReq 

func (c *Counters) IncTruncatedReq()

IncTruncatedReq is bumped when a trace's request capture lost bytes (either ring overflow or max_body_bytes cap).

func (*Counters) IncTruncatedResp 

func (c *Counters) IncTruncatedResp()

IncTruncatedResp is bumped when a trace's response capture lost bytes.

func (*Counters) IncUpstreamDialErr 

func (c *Counters) IncUpstreamDialErr()

IncUpstreamDialErr is bumped from the CaptureTransport when the inner transport returned a non-HTTP error (DNS / TLS / connect refused).

func (*Counters) ObserveWriterChanLen 

func (c *Counters) ObserveWriterChanLen(n int)

ObserveWriterChanLen records the current writer channel length; keeps the running max in writerChanHighWater.

func (*Counters) Snapshot 

func (c *Counters) Snapshot() Snapshot

type Histogram 

type Histogram struct {
	// contains filtered or unexported fields
}

Histogram is a fixed-bucket cumulative histogram used for diagnostic timings (drain / parse / sqlite per-trace ms). Buckets are upper- inclusive: an observation of v lands in the first bucket where v <= bounds[i].

Picked over sketch / digest approaches because (a) we know the expected operating range a priori (single-digit ms to tens of seconds) and (b) the cost of an Observe is one atomic compare + one atomic add, matching ARCHITECTURE § 2 "capture must not interfere."

Sum and Count are tracked separately so the mean is exact, even though per-bucket percentile reads are approximate to the bucket boundary.

func NewHistogram 

func NewHistogram(bounds []float64) *Histogram

func (*Histogram) Observe 

func (h *Histogram) Observe(v int64)

Observe records v (in the unit of the bounds — ms for the default). Safe for concurrent callers.

func (*Histogram) Snapshot 

func (h *Histogram) Snapshot() HistogramSnapshot

type HistogramSnapshot 

type HistogramSnapshot struct {
	Count  int64   `json:"count"`
	MeanMs float64 `json:"mean_ms"`
	P50Ms  int64   `json:"p50_ms"`
	P95Ms  int64   `json:"p95_ms"`
	P99Ms  int64   `json:"p99_ms"`
}

HistogramSnapshot is the /healthz-friendly view. p50/p95/p99 are upper-bucket-boundary approximations; mean is exact.

type Snapshot 

type Snapshot struct {
	DropWriterFull      int64 `json:"drop_writer_full"`
	DropJSONLFail       int64 `json:"drop_jsonl_fail"`
	DropSQLiteFail      int64 `json:"drop_sqlite_fail"`
	TruncatedReqTotal   int64 `json:"truncated_req_total"`
	TruncatedRespTotal  int64 `json:"truncated_resp_total"`
	WriterChanHighWater int64 `json:"writer_chan_high_water"`
	Appended            int64 `json:"appended"`
	Indexed             int64 `json:"indexed"`
	Appended2xx         int64 `json:"appended_2xx"`
	Appended4xx         int64 `json:"appended_4xx"`
	Appended5xx         int64 `json:"appended_5xx"`
	UpstreamDialErr     int64 `json:"upstream_dial_err"`
	SlowTraces          int64 `json:"slow_traces"`

	// Cumulative on-disk resource total (since process start).
	TotalBytes int64 `json:"total_bytes"`

	// Cumulative count of extracted media files (since process start).
	// Phase K. Zero when media extraction is disabled or has never run.
	TotalMediaFiles int64 `json:"total_media_files"`

	// Cumulative token totals. Sum across all appended traces of the usage
	// fields extracted by parser.ExtractUsage. Zero for protocols without usage
	// or traces where extraction failed.
	TotalPromptTokens        int64 `json:"total_prompt_tokens"`
	TotalCompletionTokens    int64 `json:"total_completion_tokens"`
	TotalCachedTokens        int64 `json:"total_cached_tokens"`
	TotalCacheCreationTokens int64 `json:"total_cache_creation_tokens"`
	TotalReasoningTokens     int64 `json:"total_reasoning_tokens"`

	// Storage retention counters (v0.1.1). Cumulative since process
	// start; zero when retention is disabled or has never fired.
	EvictedTraces int64 `json:"evicted_traces"`
	EvictedBytes  int64 `json:"evicted_bytes"`

	// Capture-filter drop counter (v0.1.2). Cumulative count of
	// requests skipped by the pre-trace capture_filter; zero when
	// no capture_filter is configured.
	TracesDroppedCaptureFilter int64 `json:"traces_dropped_capture_filter"`

	Timings struct {
		DrainMs  HistogramSnapshot `json:"drain_ms"`
		ParseMs  HistogramSnapshot `json:"parse_ms"`
		SqliteMs HistogramSnapshot `json:"sqlite_ms"`
	} `json:"timings"`
}

Snapshot returns a point-in-time view of all counters. Marshaled directly into the /healthz response body.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.