Documentation
¶
Overview ¶
Package sqlstatements is the sql_statements trace kind: it records the SQL statements commons-db runs on chosen connections, as the SQL statement tap publishes them, and summarizes them as it goes.
Index ¶
- Constants
- func Kind() *tracing.Handler[Params, StatementRow]
- func NormalizeSQL(statement string) string
- func RepeatKey(statement string) string
- func ResultType() recordresults.ResultType[StatementRow]
- func WindowVars(rows iter.Seq[StatementRow]) map[string]any
- type Accumulator
- type Params
- type Repeat
- type StatementRow
- type Summary
Constants ¶
const RowKind = "sql_statements"
RowKind is the record kind a capture's stream holds, and the kind a host registers Kind as: one StatementRow per statement.
Variables ¶
This section is empty.
Functions ¶
func Kind ¶
func Kind() *tracing.Handler[Params, StatementRow]
Kind is the sql_statements kind: statements masked and capped at 64KiB a value. A host registers it as RowKind.
func NormalizeSQL ¶
NormalizeSQL is statement with each string and number literal replaced by ?, its comments dropped and each run of whitespace collapsed to one space. Identifiers, quoted ones included, and bind placeholders ($1, @p1, ?) are kept, so two statements normalize alike exactly when they differ only by the values written into them.
func RepeatKey ¶
RepeatKey keys statement by its normalized text (NormalizeSQL), so the statements that differ only by their values or spacing share it: 16 hex digits of its FNV-1a hash, short enough to store with every row.
func ResultType ¶
func ResultType() recordresults.ResultType[StatementRow]
ResultType is the RowKind result type: it follows a capture's stream while it runs, searches the text a reader remembers of a statement, or of its error, and serves the repeats view. A host that registers result types itself rather than through traces.Kinds registers this one.
func WindowVars ¶
func WindowVars(rows iter.Seq[StatementRow]) map[string]any
WindowVars are a window's statements as the variables a fixture asserts on: their count, failures, total duration, ops and tables, and the first maxSummaryQueries of them. Every kind storing StatementRows summarizes with it.
Types ¶
type Accumulator ¶
type Accumulator struct {
// contains filtered or unexported fields
}
Accumulator folds statements into a Summary, so a capture keeps a running total rather than re-reading its stream. Not safe for concurrent use.
func NewAccumulator ¶
func NewAccumulator() *Accumulator
func (*Accumulator) Result ¶
func (a *Accumulator) Result() Summary
Result is the running totals, with the figures only every statement decides: the average, the percentile, the window and the repeats.
type Params ¶
type Params struct {
// Connections name the connections to observe, as profiles reference
// them, "*" for every connection, or "self" for the server's own
// database, which "*" does not include.
Connections []string `json:"connections" clicky:"required,title=Connections"`
// MinDuration, a duration such as 100ms, records only statements that ran
// at least that long.
MinDuration string `json:"minDuration,omitempty" clicky:"title=Minimum duration"`
}
Params choose the statements a capture records.
type Repeat ¶
type Repeat struct {
Key string `json:"key"`
SQL string `json:"sql"`
Count int `json:"count"`
DurationMs float64 `json:"durationMs"`
}
Repeat is one statement text that ran more than once: the first SQL seen with its key, how often it ran and what all of its runs took.
type StatementRow ¶
type StatementRow struct {
tracing.Truncation
StartedAt time.Time `json:"startedAt" pretty:"label=Started" sort:"startedAt"`
Connection string `json:"connection" filter:"terms"`
Driver string `json:"driver" filter:"terms"`
Op string `json:"op" pretty:"label=Op" filter:"terms"`
Tables []string `json:"tables" filter:"terms"`
SQL string `json:"sql" pretty:"label=SQL" filter:"text"`
RepeatKey string `json:"repeatKey" pretty:"hide" filter:"exact"`
Args []any `json:"args,omitempty" pretty:"hide"`
DurationMs float64 `json:"durationMs" pretty:"label=Duration,type=duration,unit=ms" sort:"durationMs"`
// Rows is how many rows the statement returned, or -1 when its driver
// could not tell.
Rows int64 `json:"rows" sort:"rows"`
Error string `json:"error,omitempty" filter:"text"`
}
StatementRow is one statement as a capture stores it. Op and Tables are derived from its text as xetrace classifies a captured event's, and RepeatKey keys the statements that differ only by their values.
func FromStatement ¶
func FromStatement(statement connection.Statement) StatementRow
FromStatement is the row a capture stores for statement. A statement naming no table has an empty list of them, never none.
func (StatementRow) Columns ¶
func (StatementRow) Columns() []api.ColumnDef
func (StatementRow) Row ¶
func (r StatementRow) Row() map[string]any
type Summary ¶
type Summary struct {
Statements int `json:"statements"`
Errors int `json:"errors,omitempty"`
// DurationMs sums every statement's duration; statements on concurrent
// connections overlap, so it can exceed WindowMs.
DurationMs float64 `json:"durationMs"`
AvgDurationMs float64 `json:"avgDurationMs"`
P95DurationMs float64 `json:"p95DurationMs"`
MaxDurationMs float64 `json:"maxDurationMs"`
// Rows sums the rows the statements returned, leaving out the statements
// whose driver could not count them.
Rows int64 `json:"rows"`
// WindowMs is wall clock from the first statement's start to the last
// statement's end.
WindowMs float64 `json:"windowMs"`
// Repeated counts the statements whose normalized text (RepeatKey) ran
// more than once: an N+1 shows here. Repeats lists those groups, the most
// run first, at most maxRepeats of them.
Repeated int `json:"repeated,omitempty"`
Repeats []Repeat `json:"repeats,omitempty"`
// Tables are the distinct tables the statements named, sorted.
Tables []string `json:"tables"`
// ByOp counts the statements by op.
ByOp map[string]int `json:"byOp"`
}
Summary is the aggregate over a capture's statements, as xetrace.Summary is over an XE capture's events. Durations are milliseconds, as a row's are.
Source Files