Documentation
¶
Overview ¶
Package hooks plugs the framework's existing instrumentation points (HTTP middleware, SQL observer, session manager) into the observability.Bus so the agent (and direct subscribers) can receive strongly typed events.
Each hook is independent: import only the ones you need. All hooks gate event construction on observability.Bus.HasSubscribers(kind) so they are safe to mount unconditionally — when nobody is watching, the gate short-circuits to a single atomic load.
Sanitization is the hook's responsibility. By the time the event reaches the bus, sensitive request body bytes, raw SQL argument values, and full session tokens have been replaced with redacted summaries. The bus itself makes no judgement about content.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewHTTPMiddleware ¶
func NewHTTPMiddleware(cfg HTTPMiddlewareConfig) func(http.Handler) http.Handler
NewHTTPMiddleware returns an http.Handler middleware that emits a HTTPRequestEvent for every request that passes the configured exclude list, but only when at least one subscriber wants HTTPRequest events.
The middleware is a no-op (just `next.ServeHTTP`) when:
- cfg.Bus is nil
- cfg.Bus has no HTTPRequest subscribers
- the request path matches an ExcludePaths entry
- the request is a WebSocket upgrade (status code is meaningless and mutating the request is intrusive)
The "no subscribers" gate is the critical hot-path optimization. It resolves to a single atomic load on the read side; the event allocation, response-writer wrapping, and time-of-day call all happen lazily.
func NewSQLObserver ¶
func NewSQLObserver(cfg SQLObserverConfig) model.SQLQueryObserver
NewSQLObserver returns a model.SQLQueryObserver that emits a SQLStatementEvent for every observed CRUD query, gated on HasSubscribers(KindSQLStatement).
The observer pre-sanitizes argument values: strings and bytes become "type(len):***" markers; primitives are formatted "type:value"; times are RFC3339; nils are "null". The raw argument values are NEVER shipped.
Types ¶
type HTTPMiddlewareConfig ¶
type HTTPMiddlewareConfig struct {
// Bus is the observability bus events are emitted to. Required. If nil,
// the returned middleware is a pass-through.
Bus *observability.Bus
// NodeID identifies this framework process. Empty during local dev is OK.
NodeID string
// ExcludePaths is a list of glob/prefix patterns that suppress
// instrumentation. Patterns may end in "/*" for prefix match, contain
// "*"/"?" for path.Match globs, or be plain prefixes. The default empty
// list means everything is observed. Note: when no subscriber wants
// HTTP events, the entire middleware is a single atomic load anyway —
// ExcludePaths is for when you have observers but want to filter noise
// (e.g. /healthz hits flooding the panel).
ExcludePaths []string
// MaxPayloadPreviewBytes caps the redacted body summary size. Default
// 240 bytes when zero.
MaxPayloadPreviewBytes int
// MaxUserAgentBytes caps the User-Agent string. Default 320 bytes.
MaxUserAgentBytes int
// MaxPathBytes caps the URL path. Default 240 bytes.
MaxPathBytes int
}
HTTPMiddlewareConfig configures NewHTTPMiddleware. Zero value is illegal: at minimum a *Bus must be set.
type SQLObserverConfig ¶
type SQLObserverConfig struct {
// Bus is the observability bus events are emitted to. Required.
Bus *observability.Bus
// NodeID identifies this framework process.
NodeID string
}
SQLObserverConfig configures NewSQLObserver.
type SessionInfo ¶
type SessionInfo struct {
TokenShort string
UserID string
IP string
UserAgent string
LastRoute string
TraceID string
}
SessionInfo is the minimal cross-cutting info every session-change event needs. The caller is responsible for sanitizing the token (TokenShort must already be truncated to a non-reversible prefix).
type SessionRecorder ¶
type SessionRecorder struct {
// contains filtered or unexported fields
}
SessionRecorder is a small façade the framework's session manager calls at the three lifecycle points: created, touched, destroyed. It is a helper rather than middleware because session lifecycle is driven by pkg/auth (which doesn't itself know about HTTP) and we want a typed, minimal API surface.
Hooks gate event construction on HasSubscribers(KindSessionChange).
func NewSessionRecorder ¶
func NewSessionRecorder(cfg SessionRecorderConfig) *SessionRecorder
NewSessionRecorder returns a recorder. If cfg.Bus is nil the recorder is a no-op (every method returns immediately).
func (*SessionRecorder) Created ¶
func (s *SessionRecorder) Created(info SessionInfo)
Created records that a new session was just created.
func (*SessionRecorder) Destroyed ¶
func (s *SessionRecorder) Destroyed(info SessionInfo)
Destroyed records that a session was destroyed (logout, expiration, admin revocation).
func (*SessionRecorder) Touched ¶
func (s *SessionRecorder) Touched(info SessionInfo)
Touched records that an existing session was observed (request landed, session metadata refreshed).
type SessionRecorderConfig ¶
type SessionRecorderConfig struct {
Bus *observability.Bus
NodeID string
}
SessionRecorderConfig configures NewSessionRecorder.
Source Files