Documentation
¶
Overview ¶
Package turbostats is the document a sqlflow process reports about itself.
One bundle, built by one function, carried by two transports: the HTTP handler in this package serves it to whatever can reach the process, and the reporter posts it outbound to a control plane that cannot. Neither transport computes anything.
Field names are the OTel instrument names in internal/core, not the Prometheus series names those instruments render as. The bundle reads the instrument; the suffixes belong to one exporter.
Index ¶
Constants ¶
const MediaType = "application/vnd.turbolytics.turbostats.v1+json"
MediaType names the version on the wire, so v1 and v2 are distinguishable without parsing.
const Version = 1
Version is the document version, carried in the body so a bundle stored or forwarded without its URL still says what it is.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
Handler serves one bundle per GET. The run command mounts it at /turbostats/v1; the path is the caller's, the media type is this package's.
func HashConfig ¶
HashConfig identifies a rendered config by content.
Hashed after templating and before parsing, so the same file under two environments hashes differently: those are two configs. The prefix names the algorithm so a stored hash stays readable when the algorithm changes.
func ResidentAnonBytes ¶
ResidentAnonBytes is the process's anonymous resident memory.
That is the figure a native leak moves: Go's heap profiler cannot see a buffer DuckDB allocated across the ADBC boundary, and duckdb_memory() does not track it either, so the only honest instrument is the process itself.
Linux reads RssAnon, which excludes file-backed pages and is exact. Other platforms fall back to peak resident size from getrusage, which only ever rises, so it is a weaker signal there; a leak still shows as growth between two readings, since a steady process has a steady peak.
Types ¶
type Bundle ¶
type Bundle struct {
V int `json:"v"`
SentAt time.Time `json:"sent_at"`
Instance Instance `json:"instance"`
Process Process `json:"process"`
Pipeline Pipeline `json:"pipeline"`
// LastMessageAt is when the pipeline last received messages. Absent until
// it receives any. Staleness is sent_at minus this, and because both come
// from the instance's own clock the difference carries no skew.
LastMessageAt *time.Time `json:"last_message_at,omitempty"`
// Exit is present only in the last bundle a clean shutdown sends. A
// bundle without it is an instance still running, or one that died
// without saying so.
Exit *Exit `json:"exit,omitempty"`
}
Bundle is one report. The spec at docs/superpowers/specs/2026-09-10-turbostats-v1-design.md defines every field; the comments here say only what is not obvious from the name.
func Collect ¶
func Collect(ctx context.Context, s Static, r *sdkmetric.ManualReader, stats func() (*core.StateStats, error)) (Bundle, error)
Collect builds one bundle. It is the only function that does.
It allocates one bundle and touches nothing shared, so the HTTP handler and the reporter can call it at once. stats may be nil for a pipeline with no state path; a stats error is the bundle's error, because a document with a field quietly missing reads as healthy.
type Instance ¶
type Instance struct {
// ID is the operator's name for the instance. Empty until the reporter
// config exists, which is why it is omitempty here and required there.
ID string `json:"id,omitempty"`
Pipeline string `json:"pipeline,omitempty"`
Version string `json:"version"`
Commit string `json:"commit"`
Arch string `json:"arch"`
ConfigHash string `json:"config_hash"`
}
Instance is what the operator and the build said this process is.
type Pipeline ¶
type Pipeline struct {
MessageCount int64 `json:"message_count"`
HandlerRowsRead int64 `json:"handler_rows_read"`
ErrorCount int64 `json:"error_count"`
SinkFlushCount int64 `json:"sink_flush_count"`
SinkRowsAccepted int64 `json:"sink_rows_accepted"`
SinkRowsWritten int64 `json:"sink_rows_written"`
StateCommitCount int64 `json:"state_commit_count"`
// A pointer so a pipeline with no state path omits the field: absent
// state and empty state are different facts.
StateDBSizeBytes *int64 `json:"state_db_size_bytes,omitempty"`
}
Pipeline carries the engine's top-line totals since Process.StartedAt.
Every one is read from a dimensionless series, so building this is a lookup. Flushes and commits count successes only, and the row counts exclude the DLQ's, because those choices are made where the measurements are recorded rather than here. Histograms are deliberately absent: they are most of a scrape by bytes and nothing on the first page reads them.
Source Files