Documentation
¶
Overview ¶
Package query is the query trace kind: a commons-db query profile, saved or read in place through a provider's typed options, read once over a window, once when the capture stops, or every interval, each row a record.
Index ¶
- Variables
- func Kind(options Options) (*tracing.Handler[Params, Row], error)
- type Options
- type Params
- type ProfileResolver
- type Provider
- type Reads
- func (Reads) Handle(ctx dbcontext.Context, params Params, records tracing.Emitter[Row], ...) error
- func (Reads) Params() Params
- func (r Reads) Prepare(ctx dbcontext.Context, params Params, _ tracing.Emitter[Row]) (dbcontext.Context, func() error, error)
- func (Reads) Schema() recordresults.ResultType[Row]
- type Row
Constants ¶
This section is empty.
Variables ¶
var Capabilities = tracing.Capabilities{Historical: true, Follow: true}
Capabilities are what a query capture can do: read a past window, and follow with Every.
Functions ¶
Types ¶
type Options ¶
type Options struct {
// Profiles resolves a params' saved profile; nil refuses every capture
// that names one.
Profiles ProfileResolver
// BeforeExecute prepares, and may refuse, every read before it runs, as
// every other read of a profile's data is prepared.
BeforeExecute profilestore.BeforeExecuteFunc
}
Options are the host seams the kind reads through.
type Params ¶
type Params struct {
// Profile names a saved query profile, resolved through the host's
// ProfileResolver.
Profile string `json:"profile,omitempty" clicky:"title=Profile,desc=Saved query profile to read,order=0"`
// Provider reads a commons-db query provider in place of a saved profile.
Provider *Provider `json:"provider,omitempty" clicky:"title=Provider,order=1"`
// Params are the profile's declared params by name.
Params map[string]any `json:"params,omitempty" clicky:"title=Params,desc=The profile's params by name,order=2"`
// From and To bound the window read, as a time or date math such as
// now-1h. To is empty for now; a window needs a From.
From string `json:"from,omitempty" clicky:"title=From,desc=Start of the window; a time or date math such as now-1h,order=3"`
To string `json:"to,omitempty" clicky:"title=To,desc=End of the window; empty is now,order=4"`
// Every re-reads the window from the last row kept up to now, at this
// interval, until the capture stops.
Every string `` /* 128-byte string literal not displayed */
// UntilStopped reads once, when the capture stops, over the whole capture.
UntilStopped bool `json:"untilStopped,omitempty" clicky:"title=Until stopped,desc=Read once when the capture stops; up to that moment,order=6"`
// Limit is the most rows one read keeps; 0 keeps every row.
Limit int `json:"limit,omitempty" clicky:"title=Limit,desc=Most rows one read keeps; 0 keeps all,order=7"`
}
Params choose what a capture reads, a saved profile or a provider read in place, and the window and pace it reads at.
type ProfileResolver ¶
type ProfileResolver interface {
Resolve(ctx context.Context, name string) (dbquery.Profile, error)
}
ProfileResolver resolves a saved profile by name, imports applied, as the host's profile store holds it.
type Provider ¶
type Provider struct {
// Type is the registered provider key, such as sql, prometheus or opensearch.
Type string `json:"type" clicky:"required,title=Type"`
Connection string `json:"connection,omitempty" clicky:"title=Connection"`
Query string `json:"query,omitempty" clicky:"title=Query"`
SQL *sqlite.SQLOptions `json:"sql,omitempty"`
Prometheus *providers.PrometheusOptions `json:"prometheus,omitempty"`
OpenSearch *providers.OpenSearchOptions `json:"opensearch,omitempty"`
HTTP *providers.HTTPOptions `json:"http,omitempty"`
PostgREST *providers.PostgRESTOptions `json:"postgrest,omitempty"`
BigQuery *providers.BigQueryOptions `json:"bigquery,omitempty"`
Jaeger *providers.JaegerOptions `json:"jaeger,omitempty"`
OpenTelemetry *providers.OpenTelemetryOptions `json:"opentelemetry,omitempty"`
}
Provider is a provider read in place: the commons-db provider type, its connection and query, and the typed options of that one provider.
type Reads ¶
type Reads struct {
// contains filtered or unexported fields
}
Reads is the kind's trace handler: a host whose tracing runtime is not commons-db's wraps it in its own handler, adapting the emitter it passes.
func (Reads) Handle ¶
func (Reads) Handle(ctx dbcontext.Context, params Params, records tracing.Emitter[Row], _ tracing.Records[Row]) error
Handle reads once and ends; with UntilStopped it reads when the capture stops, and with Every it reads at each interval until it stops.
func (Reads) Prepare ¶
func (r Reads) Prepare(ctx dbcontext.Context, params Params, _ tracing.Emitter[Row]) (dbcontext.Context, func() error, error)
Prepare resolves the profile and checks it can be windowed as the params ask, so a capture that could not read refuses its start.
func (Reads) Schema ¶
func (Reads) Schema() recordresults.ResultType[Row]
type Row ¶
type Row struct {
// Time is the row's time column, time or timestamp; a row of a read that
// has none is timed by the moment it was read.
Time time.Time `json:"time" pretty:"label=Time" sort:"time"`
// Profile is the saved profile read; empty for a provider read in place.
Profile string `json:"profile,omitempty" filter:"terms"`
Provider string `json:"provider" filter:"terms"`
// Row is the provider's row as it returned it.
Row map[string]any `json:"row" pretty:"hide"`
}
Row is one row a read returned.
Source Files