gopgext/hooks

Observe and instrument the statements a backend runs.

API reference: gopgext/hooks.

Observes the statements a backend processes through PostgreSQL’s query processing hooks (post parse analysis, planner, executor, utility): for statistics, slow query logs, auditing. Decision callbacks choose what to measure; result callbacks get the measurements:

func main() {
	hooks.EnableQueryID() // compute_query_id = auto computes identifiers
	hooks.Register(hooks.Hooks{
		Parsed:   func(s *hooks.Statement) { ... s.Constants() ... }, // normalize the text
		Execute:  func(s *hooks.Statement) bool { return s.Nesting == 0 },
		Executed: func(s *hooks.Statement, u *hooks.Usage) { ... },  // u.Time, u.Rows, buffers, WAL, JIT
		Utility:  func(s *hooks.Statement) bool { return s.Command != "EXECUTE" },
		UtilityDone: func(s *hooks.Statement, u *hooks.Usage) { ... },
	})
}

A Statement has the query identifier, Text() (the statement, out of a multi-statement string), its nesting level (0 for the client’s statements; functions, DO blocks, utility statements and planning add levels) and its command tag. Parsed can change the query identifier, and gets the statement’s constants with their lengths (Constants()), to replace them with $n. PostgreSQL code (planner, executor) only runs in C: Go is called before and after. Load the library with shared_preload_libraries to see every backend’s statements. contrib/pg_stat_statements is built on it.

Statement.ExecutorNesting counts only the executions in progress, as auto_explain does: statements of a DO block or the query of CREATE TABLE AS are at executor level 0. Execute can ask for per-node instrumentation of the execution, and Executed can then get its plan as EXPLAIN prints it (contrib/auto_explain is built on this):

hooks.Register(hooks.Hooks{
	Execute: func(s *hooks.Statement) bool {
		s.Instrument(hooks.InstrumentTimer | hooks.InstrumentBuffers) // or InstrumentRows, InstrumentWAL
		return s.ExecutorNesting == 0
	},
	Executed: func(s *hooks.Statement, u *hooks.Usage) {
		if u.Time > 100 {
			plan := s.Explain(hooks.ExplainOptions{Format: "json", Analyze: true, Buffers: true, QueryText: true})
			(&pg.Message{Level: pg.LevelLog, Text: plan, HideStatement: true}).Report()
		}
	},
})

ExplainOptions has EXPLAIN’s Format (text, xml, json, yaml), Analyze, Timing, Buffers, WAL, Triggers (these need the matching instrumentation; without any, Analyze is ignored, e.g. under EXPLAIN without ANALYZE), Verbose, Settings, NoCosts, QueryText and Parameters (the values of $n parameters: 0 none, -1 in full, n bytes each; PostgreSQL 16+). Instrumentation is requested before the executor starts (the decision callback now runs before ExecutorStart).