xetrace

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

type CreateOptions struct {
	// Session attaches to a built-in session instead of creating one. The only
	// supported value is system_health.
	Session string
	// Name of the XE session. Required: there is no default.
	//
	// An Extended Events session is a server-scoped object — it shows up in
	// sys.dm_xe_sessions for every DBA on the instance, alongside sessions
	// created by anything else. A name this package invented would tell them
	// which library made it and nothing about which application, so the name
	// belongs to the caller who can answer that.
	Name string
	// Databases scopes the session by database name using clicky MultiFilter
	// values with collections.MatchItems semantics (case-insensitive exact,
	// prefix/suffix `*`, `!` exclusion, comma lists). Translated into the XE
	// WHERE predicate, as are Users, Apps and Hosts, so the filter runs in SQL
	// Server before the target, not post-capture in Go.
	//
	// Empty scopes to the connection's own database, which Create resolves with
	// DB_NAME(); AllDatabases ("*") captures the whole instance. Instance-wide
	// is the wider, more surprising scope, so it is the one that has to be
	// asked for.
	Databases []string
	// Users scopes the session by SQL login with the same patterns as
	// Databases. Empty captures all users.
	Users []string
	// MinDurationMicros filters out events faster than this threshold.
	// Only applied to duration-bearing events (statement/rpc/batch).
	MinDurationMicros int64
	// Events is the list of XE event names to capture. When empty,
	// DefaultEvents is used.
	Events []string
	// ExcludeSessionID is populated by Create from its dedicated connection.
	ExcludeSessionID int
	// Apps scopes the session by client application name with the same
	// patterns as Databases. Empty captures every application.
	Apps []string
	// Hosts scopes the session by client host name with the same patterns as
	// Databases. Empty captures every host.
	Hosts []string
	// MaxMemoryKB is the ring buffer size. Zero uses the
	// sqltrace.ringBuffer.maxMemoryKb property. Meaningless with File set.
	MaxMemoryKB int
	// MaxEvents caps the ring buffer event count. Zero uses the
	// sqltrace.ringBuffer.maxEvents property. Meaningless with File set.
	MaxEvents int
	// File selects a package0.event_file target instead of the ring buffer:
	// events are written to .xel files on the SQL Server host and read back
	// incrementally, so a high-volume capture cannot lose events to the ring
	// buffer's FIFO eviction. Nil keeps the ring buffer.
	File *FileTarget
	// Filter narrows captured events by statement type / referenced table. XE
	// carries no structured type/object info to predicate on at the session
	// level, so it is recorded here with the rest of the capture's configuration
	// and applied by Drain — pass it as DrainOptions.Filter — which is the first
	// point an sp_execute has been resolved to the statement it re-ran. Zero
	// value matches everything. It does not change the XE events captured.
	Filter EventFilter
}

type DrainOptions struct {
	// Interval is the ring-buffer poll cadence. Defaults to one second.
	Interval time.Duration
	// StartedAt bounds an attached session, whose target holds events from
	// before the capture and keeps receiving them after it: events stamped
	// before StartedAt, or at or after the moment ctx ends, are not delivered.
	// Leave it zero for a session this process created, which only ever holds
	// the capture's own events — comparing the server's timestamps with this
	// host's clock would drop the last ones whenever the server's runs ahead.
	StartedAt time.Time
	// FinalDelay is how long Drain waits after ctx ends before its final read
	// (Session.FinalDelay).
	FinalDelay time.Duration
	// OnEvent receives each new, deduplicated event in delivery order. It is
	// invoked synchronously while dedup state is held — keep it fast (an append
	// or a channel send, never a network round-trip).
	OnEvent func(Event)
	// OnPollBatch fires once after each poll's events have all been delivered,
	// marking a natural batch boundary for a caller that persists in chunks.
	// It does NOT fire for a poll that failed.
	OnPollBatch func()
	// OnPollFailure reports a transient poll failure that is being retried,
	// with the number of consecutive failures so far. xetrace has no logger of
	// its own (DB chatter flows through gormlog), so callers do the logging.
	OnPollFailure func(consecutive int, err error)
	// OnDropped reports that the server dispatched more events to the ring
	// buffer than we read back, or that it truncated/dropped events itself.
	// This is how a tolerated poll failure stays auditable instead of silently
	// losing the events the buffer evicted while we were not reading it.
	//
	// Every delta is additive — the events lost since the previous report — so
	// a caller can sum them into a capture's total loss. A truncated target is
	// reported even when it carries no count of its own.
	OnDropped func(delta int64, stats TargetStats)
	// Filter narrows delivery by every supported event dimension. It is
	// applied here rather than as each ring-buffer read is parsed because only
	// here has an sp_execute been resolved to the statement it re-ran: before
	// that, every re-run of a prepared statement reads as Tables=[sp_execute]
	// and a table pattern would drop it. The zero value delivers everything.
	Filter EventFilter
	// OnUnresolved receives each event Filter excluded only because its text is
	// unknowable — an sp_execute of a handle prepared before the capture
	// started. Its cost is real but cannot be placed, so a caller that sums the
	// delivered events must count these rather than let them vanish.
	OnUnresolved func(Event)
}

type Event struct {
	Name              string         `json:"name"`
	Timestamp         time.Time      `json:"timestamp"`
	Duration          time.Duration  `json:"duration"`
	CPUTime           time.Duration  `json:"cpu_time"`
	LogicalReads      int64          `json:"logical_reads"`
	PhysicalReads     int64          `json:"physical_reads"`
	Writes            int64          `json:"writes"`
	RowCount          int64          `json:"row_count"`
	DatabaseName      string         `json:"database_name"`
	ClientApp         string         `json:"client_app_name"`
	ClientHost        string         `json:"client_hostname"`
	Username          string         `json:"username"`
	SessionID         int            `json:"session_id"`
	Statement         string         `json:"raw_statement,omitempty"`
	SQL               string         `json:"statement"`
	StatementType     StatementType  `json:"statement_type,omitempty"`
	Tables            []string       `json:"tables,omitempty"`
	ErrorNumber       int            `json:"error_number,omitempty"`
	ErrorMessage      string         `json:"error_message,omitempty"`
	AdditionalFields  map[string]any `json:"additional_fields,omitempty"`
	DeadlockReportXML string         `json:"deadlock_report_xml,omitempty"`
	DeadlockDatabases []string       `json:"deadlock_databases,omitempty"`

	// ObjectName is the procedure an event ran inside, captured whenever the
	// event exposes it — rpc_completed always does; sp_statement_completed
	// reports object_id instead on some server versions, which is kept in
	// ObjectID. Neither is the attribution mechanism for inner statements:
	// that is Nest, keyed on ActivityID. These are for display only.
	ObjectName string `json:"object_name,omitempty"`
	ObjectID   int64  `json:"object_id,omitempty"`

	// ObjectType is what an object event created, altered or deleted, as SQL
	// Server's object_type map names it: USRTAB, INDEX, PROC, VIEW, …. Empty
	// for every other event.
	ObjectType string `json:"object_type,omitempty"`

	// ActivityID and ActivitySeq come from package0.attach_activity_id, which
	// is only attached when TRACK_CAUSALITY is on (see wantsCausality). Every
	// event raised while servicing one request shares an ActivityID, with
	// ActivitySeq increasing in completion order — this is what lets Nest put
	// a procedure's inner statements under the call that ran them.
	ActivityID  string `json:"activity_id,omitempty"`
	ActivitySeq int    `json:"activity_seq,omitempty"`

	// Sequence is package0.event_sequence: the session's running number for this
	// event, unique within one capture. It is what keys an event, because two
	// distinct events can agree on every other field — a connection reset raises
	// 5701 and 5703 in the same millisecond on one session, with no duration and
	// no statement.
	Sequence int64 `json:"sequence,omitempty"`

	// Children are the inner statements attributed to this event by Nest.
	// Always empty until Nest runs.
	Children []Event `json:"children,omitempty"`

	// ParamsUnavailable marks a statement whose parameter values are not
	// recoverable from the trace — a positional `{call p(?,?)}` that the
	// driver did not expand, or an sp_execute whose prepared handle was
	// established before capture started. The placeholders are shown as
	// captured; this flag stops them being read as the literal call.
	ParamsUnavailable bool `json:"params_unavailable,omitempty"`
}

type EventFilter struct {
	Events      []string
	Databases   []string
	Users       []string
	Apps        []string
	Hosts       []string
	Types       []string
	Tables      []string
	MinDuration time.Duration
}

type FileTarget struct {
	// Path is where SQL Server writes the files, on ITS OWN filesystem. AutoPath
	// resolves the instance's log directory (see ResolveEventFilePath); any
	// other value is used exactly as given and must be an absolute path ending
	// in .xel.
	Path string
	// MaxFileSizeMB caps one file before SQL Server rolls over. Zero uses the
	// sqltrace.eventFile.maxFileSizeMb property.
	MaxFileSizeMB int
	// MaxRolloverFiles caps how many rolled files are kept. Zero uses the
	// sqltrace.eventFile.maxRolloverFiles property. Together with MaxFileSizeMB
	// this is the capture's whole disk budget on the server.
	MaxRolloverFiles int
}

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

type PermissionError struct {
	Report PermissionReport
}

type PermissionReport struct {
	Login               string   `json:"login"`
	ProductMajorVersion int      `json:"productMajorVersion"`
	Granted             bool     `json:"granted"`
	MissingPermissions  []string `json:"missingPermissions,omitempty"`
	GrantStatements     []string `json:"grantStatements,omitempty"`
}

type Querier interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

type RPCCall struct {
	Template  string
	ParamDecl string
	Values    []string
}

type ReplayResult struct {
	// EventKey links back to Event.Key() for correlation with the
	// original trace row.
	EventKey string `json:"event_key"`
	// OriginalStatement is the raw statement text as it came out of the
	// trace, kept for display so users can compare what was captured with
	// what was actually replayed.
	OriginalStatement string `json:"original_statement"`
	// Eligible indicates whether the replay actually ran. When false,
	// SkipReason explains why (non-SELECT, INTO/EXEC present, error
	// event, etc.).
	Eligible   bool   `json:"eligible"`
	SkipReason string `json:"skip_reason,omitempty"`
	// SQL and Args are the parameterized form passed to the driver —
	// useful for users who want to re-run the query manually.
	SQL  string `json:"sql,omitempty"`
	Args []any  `json:"args,omitempty"`
	// RowCount is the exact number of rows the replay returned. When
	// RowCountTruncated is true the replay hit the scan cap and the
	// count is a lower bound.
	RowCount          int  `json:"row_count"`
	RowCountTruncated bool `json:"row_count_truncated,omitempty"`
	// FirstRows holds up to 3 column-name-keyed maps for display.
	FirstRows []map[string]any `json:"first_rows,omitempty"`
	// Warnings from type coercion (e.g. unknown SQL type, unparseable
	// datetime) so the user can see where fidelity may have been lost.
	Warnings []coerceWarning `json:"warnings,omitempty"`
	// Error is the driver or scan error, if any. Non-empty means the
	// replay ran but failed partway; Eligible is still true in that case.
	Error string `json:"error,omitempty"`
	// Duration is the wall time spent on this replay.
	Duration time.Duration `json:"duration"`
}

type Session struct {
	Name string
	// Statements are the CREATE EVENT SESSION and START statements Create
	// ran, in order, exactly as it executed them.
	Statements []string
	// FilePath is where an event_file session writes, as resolved on the
	// server. Empty for a ring_buffer session.
	FilePath string
	// contains filtered or unexported fields
}

type StatementType string

type StreamLineOptions struct {
	// ShowDatabase adds a "db=<name>" segment. Only set when the capture can
	// see more than one database (anything but exactly one plain --database);
	// a single-database capture would otherwise repeat the same value on every
	// line.
	ShowDatabase bool
	// Full removes the max-w-[200ch] cap on the statement cell so long
	// statements wrap naturally instead of being elided.
	Full bool
}

type Summary struct {
	Events int `json:"events"`
	Errors int `json:"errors,omitempty"`
	// Nested is the count of inner statements whose metrics a parent event
	// already accounts for. Non-zero only when sp_statement_completed is traced.
	Nested int `json:"nested,omitempty"`
	// Window is wall-clock first event → last event, which is what the capture
	// actually spans — not the sum of the durations, which overlaps across
	// concurrent sessions.
	Window        time.Duration `json:"window"`
	Duration      time.Duration `json:"duration"`
	AvgDuration   time.Duration `json:"avg_duration"`
	P95Duration   time.Duration `json:"p95_duration"`
	MaxDuration   time.Duration `json:"max_duration"`
	CPUTime       time.Duration `json:"cpu_time"`
	LogicalReads  int64         `json:"logical_reads"`
	PhysicalReads int64         `json:"physical_reads"`
	// ReadBytes is LogicalReads × 8 KB — every page the capture read. A
	// physical read is a page SQL Server first fetched from disk, and that page
	// is then counted as a logical read too, so adding the two would count
	// every disk read twice.
	ReadBytes int64 `json:"read_bytes"`
	Writes    int64 `json:"writes"`
	RowCount  int64 `json:"row_count"`
	// Lost counts events SQL Server raised that the capture never read: evicted
	// from the ring buffer before a poll reached them, or dropped by the server.
	// Every figure above undercounts while it is non-zero.
	Lost int64 `json:"lost,omitempty"`
	// Unresolved counts re-runs of a statement prepared before the capture
	// started, which a type/table filter could not place: their text is
	// unknowable, so their cost is in no figure above either.
	Unresolved int64 `json:"unresolved,omitempty"`
}

type SystemHealthSource struct {
	CurrentFile     string        `json:"currentFile"`
	FilePattern     string        `json:"filePattern"`
	DispatchLatency time.Duration `json:"dispatchLatency"`
}

type TargetSnapshot struct {
	Events []Event
	// ExcludedKeys are the Event.Keys of events this read DID see but chose not
	// to deliver — driver chatter dropped by ParseRingBuffer, and events removed
	// by the caller's Filter. They exist purely so Drain can tell "we skipped
	// this" apart from "the buffer evicted this before we got to it".
	//
	// Without them the drop metric subtracts a post-filter delivered count from
	// the server's pre-filter totalEventsProcessed, so every deliberately
	// skipped event is reported as lost. That was not hypothetical: on a real
	// intake run it reported ~560 events lost per run, and disabling the noise
	// drop took the same run to zero. The warning was measuring its own filter.
	ExcludedKeys []string
	Stats        TargetStats
}

type TargetStats struct {
	Truncated            bool  `json:"truncated,omitempty"`
	ProcessingTime       int64 `json:"processing_time,omitempty"`
	TotalEventsProcessed int64 `json:"total_events_processed,omitempty"`
	EventCount           int64 `json:"event_count"`
	DroppedCount         int64 `json:"dropped_count,omitempty"`
	MemoryUsed           int64 `json:"memory_used,omitempty"`
}

type TraceResult struct {
	SessionName string           `json:"session_name"`
	Database    string           `json:"database"`
	StartedAt   time.Time        `json:"started_at"`
	StoppedAt   time.Time        `json:"stopped_at"`
	Duration    time.Duration    `json:"duration"`
	Events      []Event          `json:"events,omitempty"`
	Ref         *query.EventsRef `json:"ref,omitempty"`
	Preview     []Event          `json:"-"`
	Replays     []ReplayResult   `json:"replays,omitempty"`
	Error       string           `json:"error,omitempty"`

	// Summary is the IO/CPU/timing aggregate over Events, or over Ref when a
	// profiler persisted the events into the paged trace-result store.
	Summary *Summary `json:"summary,omitempty"`
}