obsquery

type Agg int

type Anomaly struct {
	Service string
	// Signal is an AnomalySignal* value.
	Signal string
	// Observed, Baseline (the median) and Spread (the MAD) are in Unit:
	// "fraction" for the error rate, "s" for p95, "requests" for throughput.
	Observed, Baseline, Spread float64
	Unit                       string
	// Limit is the nearest value of the signal that would not have fired,
	// on the side the observation is on.
	Limit float64
	// Up is whether the signal rose; throughput can also fall.
	Up bool
	// Requests is the window's request count.
	Requests float64
	// BaselineSamples is how many slots the baseline had.
	BaselineSamples int
	HistoryDays     int
}

type AnomalyParams struct {
	// Window is the span the observed value covers, and the width of one
	// baseline slot, so a slot is directly comparable to the window.
	Window time.Duration
	// Delay is how far the window's end lags now: the metric exporters'
	// interval, so a sample that has not landed does not read as a drop.
	Delay time.Duration
	// Weeks is how many previous weeks make the baseline (1 to 4: metrics are
	// kept 30 days).
	Weeks int
	// K is the multiple of the baseline's MAD the observed value must leave.
	K float64

	// MinRequests: a window with fewer requests never fires an error-rate or
	// latency finding, and a baseline whose median slot has fewer never fires
	// a throughput one.
	MinRequests float64
	// MinErrors is the fewest server errors in the window that fire an
	// error-rate finding, and MinErrorDelta the least rise in the error ratio
	// (0..1) that does.
	MinErrors     float64
	MinErrorDelta float64
	// P95Ratio and MinLatencyDelta (seconds): the p95 must be at least this
	// multiple of the baseline's AND this much above it.
	P95Ratio        float64
	MinLatencyDelta float64
	// ThroughputRatio: requests must be at least this multiple of the
	// baseline's, or at most its reciprocal.
	ThroughputRatio float64

	// MinHistory is how much history a service must have to be judged.
	MinHistory time.Duration
	// MinBaselineSamples is the fewest baseline slots a signal needs.
	MinBaselineSamples int
}

type AnomalyQuery struct {
	Scope  Scope
	Params AnomalyParams
	// Now is the evaluation time; zero is time.Now().
	Now time.Time
}

type AnomalyResult struct {
	// Inputs are the services judged, with the samples they were judged on.
	Inputs []ServiceREDInput
	// Anomalies are the findings, by service then signal.
	Anomalies []Anomaly
	// Window is the observed window's start and end.
	WindowStart, WindowEnd time.Time
	// Truncated is set when more services existed than MaxAnomalyServices:
	// the busiest were judged.
	Truncated bool
	Warnings  []string
}

type AttrFilter struct {
	Key    string
	Op     string // "" | "eq" | "neq" | "in" | "contains" | "exists"
	Value  string
	Values []string
}

type AttrValues struct {
	Scope  Scope
	Key    string
	Prefix string
	// Signal is where to read; zero picks the key's natural home: span keys
	// read traces, event keys logs, a metric's attribute metrics, and resource
	// keys traces AND metrics (logs only when asked, they are the largest).
	Signal Signal
	// Metric names the metric whose declared attribute Key is; required for a
	// key that is not on the allowlist.
	Metric string
	Limit  int
}

type AttributeStat struct {
	Key      string
	Resource bool
	// DistinctEstimate is the estimated number of values over the range.
	DistinctEstimate int64
	// Enumerated is the declared closed value set; empty when open.
	Enumerated []string
	// HighCardinality: grouping by the key (with the rest of the panel's
	// group-by) could exceed MaxMetricSeries.
	HighCardinality bool
}

type CatalogEntry struct {
	Name        string
	Kind        CatalogKind
	Unit        string
	Description string
	// Monotonic: a sum that is a counter, not an up-down counter.
	Monotonic   bool
	Temporality Temporality
	// Services are up to 10 service.name values that emit it; ServiceCount is
	// how many do.
	Services     []string
	ServiceCount int
	// LastSeen is the newest data point in the catalog range; zero for a
	// declared metric never seen.
	LastSeen       time.Time
	SeriesEstimate int64
	// Queryable is false for a kind the evaluator cannot run.
	Queryable bool
	Builtin   bool
	// Declared: the release's metrics schema lists it. Seen: it has data in
	// the range.
	Declared bool
	Seen     bool
	// Stability is the declaration's "stable", "experimental" or
	// "deprecated"; empty when not declared.
	Stability          string
	DeclaredAttributes []metrics.Attribute
}

type CatalogKind int

type DeclaredKeys struct {
	Scope Scope
	Name  string
	Type  MetricType
}

type Env struct{ ID, Name string }

type EvalOptions struct {
	// StepSeconds is the requested bucket width; 0 picks one. It is raised to
	// the metrics' export interval, with a step_raised warning.
	StepSeconds int32
	// Explain compiles every statement and runs nothing (the Runner is not
	// called). The kind of each metric is taken from the series' metricType.
	Explain bool
	// Now decides which buckets are partial; zero is time.Now().
	Now time.Time
	// MaxSeries lowers the series cap (default MaxMetricSeries).
	MaxSeries int
	// Filters are ANDed onto every series' predicates.
	Filters []PanelPredicate
}

type Exemplar struct {
	Time       time.Time
	Value      float64
	TraceID    string
	SpanID     string
	Attributes map[string]string
	// Stored: the trace is in the trace store. false means it was sampled out
	// and the trace view would be empty.
	Stored bool
}

type ExemplarsStored struct {
	Scope    Scope
	TraceIDs []string
	// From and To are the exemplar window; both zero means the scope's range.
	// The probe reads one hour either side.
	From, To time.Time
	// UseLookupTable reads the otel_traces_trace_id_ts lookup table (a hosted
	// backend has it) instead of otel_traces itself (the local ClickStack).
	UseLookupTable bool
}

type Flamegraph struct {
	Scope      Scope
	Service    string
	SampleType string
	TraceID    string
}

type IncidentCandidate struct {
	// ID is the caller's handle for the issue; it comes back in IncidentGroup.
	ID        string
	Cause     string
	FirstSeen time.Time
}

type IncidentGroup struct {
	Key   string
	Cause string
	// First is the first-seen time of the incident's earliest issue.
	First time.Time
	// IDs are the members, earliest first seen first.
	IDs []string
}

type LogCursor struct {
	TsNano int64  `json:"t"`
	Hash   uint64 `json:"h,string"`
	Finger string `json:"f"`
}

type LogQuery struct {
	Scope      Scope
	Query      string
	Severities []string
	Oldest     bool
	Limit      int // rows to return; the statement fetches one more
	Cursor     *LogCursor
}

type MetricAttributes struct {
	Scope Scope
	Name  string
	Kind  CatalogKind
}

type MetricCatalog struct {
	Scope        Scope
	NameContains string
	Limit        int
}

type MetricExemplars struct {
	Scope Scope
	Name  string
	Kind  CatalogKind
	// Where narrows to series matching the predicates (a panel's vocabulary).
	Where []PanelPredicate
	// Group narrows to one series group: group-by key to value.
	Group map[string]string
	// From and To bound the exemplars' own timestamps (the bucket the user
	// clicked), inside the scope's range; both zero means the scope's range.
	From, To time.Time
	// MinValue keeps only exemplars at or above it (the tail of a latency
	// histogram).
	MinValue *float64
	// Limit is at most MaxExemplars; zero means MaxExemplars.
	Limit int
}

type MetricInfo struct {
	Type MetricType
	Unit string
	// Monotonic is a Sum's IsMonotonic. An up-down counter is not.
	Monotonic        bool
	Temporality      Temporality
	MixedTemporality bool
	// Series is the number of distinct series in the lookup window; it
	// decides whether the series cap is applied in SQL.
	Series int64
	// IntervalSeconds estimates the export interval; it is the floor of the
	// bucket width.
	IntervalSeconds int64
	// StoredKinds is how many metric kinds hold this name (normally 1).
	StoredKinds int
}

type MetricLookup struct {
	Scope Scope
	Name  string
}

type MetricPanelResult struct {
	Meta   []SeriesMeta
	Series []MetricSeriesResult
	// SeriesTotal is how many groups existed before the series cap.
	SeriesTotal int
	Truncated   bool
	StepSeconds int64
	// Warnings are "<code>" or "<code>: <detail>"; see WarningCode.
	Warnings []string
	// Absent are the metrics of panel series that have no data in the scope
	// and range (each with a metric_absent warning). Their series are empty.
	Absent     []string
	Statements []NamedStmt
}

type MetricPoint struct {
	Time          time.Time
	Value         float64
	Null, Partial bool
}

type MetricQuery struct {
	Scope Scope
	Name  string
	// Info is what MetricLookup found (see ParseLookup); the kind selects the
	// table and the statement shape, and Info.Series decides the SQL series cap.
	Info MetricInfo
	// Agg is resolved against Info (ResolveAgg), so AggDefault is allowed.
	Agg Agg
	// Quantile is the level for AggQuantile, in (0, 1].
	Quantile float64
	// GroupBy are allowlisted keys, the metric's declared attributes
	// (Scope.Declared), or panel-vocabulary keys (metric.attr.<k>,
	// resource.attr.<k>).
	GroupBy []string
	// Where are dashboard-panel predicates (metric.attr.*, service.name,
	// resource.attr.*), ANDed with Scope.Filters.
	Where []PanelPredicate
	// StepSeconds is the resolved bucket width (see StepForMetric). Unused
	// with Reduce.
	StepSeconds int64
	// MaxSeries caps a grouped query in SQL at the top MaxSeries groups; 0 is
	// MaxMetricSeries, and the most a table or bar panel may ask is MaxTableRows.
	MaxSeries int
	// Reduce compiles one bucket spanning the whole range: a rate becomes the
	// range-average rate, a quantile is over the merged range, a level
	// aggregation is the last value.
	Reduce bool
}

type MetricSeriesResult struct {
	Label   string
	Labels  map[string]string
	Points  []MetricPoint
	Reduced *float64
}

type MetricType int

type NamedStmt struct {
	Purpose string
	Stmt    Stmt
}

type Node interface{}

type Overview struct {
	Scope Scope
	// GroupBy splits each service by these allowlisted keys.
	GroupBy []string
}

type Panel struct {
	ID      string
	Kind    string // number | line | table | bar | heatmap | sql | funnel | issues | sessions  (search is not executable here)
	Signal  string // traces | logs | metrics; browser kinds: traces or empty; sql: optional
	Series  []PanelSeries
	Ratio   bool
	Where   []PanelPredicate
	GroupBy []string
	// Formula plots one expression over the series (forge dashspec.ParseFormula)
	// instead of the series, on line and number panels.
	Formula string
	// Limit keeps the top Limit groups of a table or bar panel; zero is the
	// kind's default (RowCap).
	Limit int
	// SQL is a sql panel's statement (see sql_panel.go).
	SQL string
	// Funnel is the definition of a funnel panel; HasError narrows a sessions
	// panel to sessions that hit an error. See panel_browser.go.
	Funnel   *PanelFunnel
	HasError bool
}

type PanelFunnel struct {
	Steps  []string
	Window string // "<n><s|m|h|d>", at most MaxRangeFunnel; empty = DefaultFunnelWindow
	By     string // "session" | "user"; empty = DefaultFunnelBy
}

type PanelPredicate struct {
	Field  string
	Op     string // eq neq in not_in prefix match exists gte
	Value  string
	Values []string
}

type PanelQuery struct {
	Scope   Scope
	Panel   Panel
	Filters []PanelPredicate
	// StepSeconds is the resolved bucket width for line panels.
	StepSeconds int64
}

type PanelSeries struct {
	Label      string
	Agg        string // count count_distinct sum avg max quantile last
	Quantile   float64
	Field      string // a semantic field; the metric NAME for metrics panels
	MetricType string // "sum" | "gauge" | "histogram" (metrics panels)
	Where      []PanelPredicate
}

type PanelShape struct {
	Bucketed bool // first column is the bucket (line panels, sparklines)
	// Total: after the bucket, a UInt8 that is 1 on the row aggregating the
	// whole range (an ungrouped number panel's value; the others are its
	// sparkline).
	Total  bool
	Groups int // length of the labels array
	Series int // trailing Float64 columns
	// Rows is how many rows a table or bar panel keeps; the statement returns
	// one more when there were more.
	Rows int
	// Heatmap: the columns are bucket, value bucket (Int32), count.
	Heatmap bool
}

type REDSample struct {
	Requests, Errors float64
	// P95 is in seconds; valid when HasP95.
	P95    float64
	HasP95 bool
}

type ReplayCursor struct {
	TsNano int64  `json:"t"`
	Index  uint32 `json:"e"`
	Finger string `json:"f"`
}

type ReplayEvent struct {
	// Time is the event's timestamp (rrweb's own, to the millisecond).
	Time time.Time
	// Index is the recorder's rr-web.event counter. It restarts on every page
	// load, so it orders events only within one timestamp.
	Index uint32
	// Chunks is how many stored records the event was reassembled from.
	Chunks int
	// Data is the event's JSON text exactly as recorded: opaque, masked at
	// record time, never altered.
	Data []byte
}

type ReplayPage struct {
	Events []ReplayEvent
	// More says more complete events follow now. NextToken is set exactly then.
	More      bool
	NextToken string
	// Resume continues after the last returned event and is set whenever the
	// page holds one, even on the last page: passing it later returns the events
	// recorded since (a session still being recorded). Empty for an empty page.
	Resume string
	// Bytes is the total size of Events' Data.
	Bytes int
	// Withheld counts events the statement picked that Parse refused because
	// they were not whole JSON objects. It should be zero; a nonzero value is a
	// storage fault worth logging.
	Withheld int
}

type ReplayQuery struct {
	// Scope bounds the read: the database, the environments, the services and
	// the time range (which should cover the session; rum_replay is partitioned
	// by day). Scope.Filters do not apply to a read of one named session.
	Scope     Scope
	SessionID string
	// MaxBytes is the page's byte budget; 0 = DefaultReplayPageBytes.
	MaxBytes int
	Cursor   *ReplayCursor
}

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	Err() error
	Close() error
}

type Runner func(ctx context.Context, st Stmt) (Rows, error)

type SQLPanel struct {
	Scope       Scope
	SQL         string
	StepSeconds int64
}

type Scope struct {
	// Database qualifies every table: the org's database (t_<org>) in
	// the control plane, LocalDatabase against a local ClickStack.
	Database string
	// Local marks a scope over a project's own local ClickStack. Only a local
	// scope may name LocalDatabase: in the control plane `default` is the
	// server's own database, and an org scope that names it is refused.
	Local bool
	// EnvIDs narrows to these environments (reliant.env.id) when EnvRestricted
	// is set; an empty restricted list matches nothing. Unrestricted = every
	// environment of the org, and rows that carry no environment at all.
	EnvIDs        []string
	EnvRestricted bool
	// Envs are the environments in scope, for resolving
	// deployment.environment.name to the Reliant environment's name.
	Envs []Env
	// Services narrows to these service.name values; empty = all.
	Services []string
	// Filters are generic attribute predicates, ANDed.
	Filters []AttrFilter
	// Declared are the attribute keys the queried metric's own data points
	// carry; the one extension to the key allowlist, for metrics.
	Declared map[string]bool
	// Start inclusive, End exclusive.
	Start, End time.Time
}

type SeriesMeta struct {
	Label, Metric string
	Info          MetricInfo
	Agg           Agg
	Quantile      float64
	ValueUnit     string
}

type ServerErrorRecord struct {
	ServiceName string
	ScopeName   string
	Body        string
	// Attributes are the row's LogAttributes.
	Attributes map[string]string
}

type ServerIssueCoOccurring struct {
	Scope       Scope
	Fingerprint string
}

type ServerIssueEvents struct {
	Scope       Scope
	Fingerprint string
	Limit       int
}

type ServerIssueIncidents struct {
	Scope Scope
	// Service narrows to one service, as the list it marks does.
	Service string
}

type ServerIssueVersions struct {
	Scope       Scope
	Fingerprint string
}

type ServerIssues struct {
	Scope Scope
	// Service narrows to one service.name, beside Scope.Services.
	Service string
	// Fingerprint narrows to one issue; empty lists them all.
	Fingerprint string
	// Source lists the issues of this issue source (LogKeyIssueSource);
	// empty lists errors. Ignored with a Fingerprint, which names its issue
	// whatever its source.
	Source string
	Limit  int // issues to return; the statement fetches one more
	Sort   string
}

type ServiceREDInput struct {
	Service string
	// Observed is the window's aggregate.
	Observed REDSample
	// Baseline is one sample per slot of the previous weeks, a slot with no
	// traffic a zero sample, for the weeks the service already existed in.
	Baseline []REDSample
	// FirstSeen is when the service's metrics first appeared in the lookback
	// (zero: never).
	FirstSeen time.Time
	Now       time.Time
}

type SessionCursor struct {
	TsMs      int64  `json:"t"`
	Service   string `json:"s"`
	SessionID string `json:"i"`
	Finger    string `json:"f"`
}

type SessionLookup struct {
	// Scope bounds the read; its range should cover the session (the days it
	// touched are read, and the day before the range start).
	Scope     Scope
	SessionID string
}

type SessionPage struct {
	Sessions []SessionSummary
	// NextCursor continues after the last returned session; "" on the last page.
	NextCursor string
}

type SessionQuery struct {
	Scope Scope
	// HasError keeps sessions with at least one browser error; HasReplay those
	// with recorded replay.
	HasError, HasReplay bool
	// UserID keeps sessions of that user id; empty keeps all.
	UserID string
	// PathContains keeps sessions whose entry path contains it, case-insensitive.
	PathContains string
	Limit        int // 0 = DefaultSessionLimit; the statement fetches one more
	Cursor       *SessionCursor
}

type SessionSummary struct {
	SessionID    string
	Service      string
	Version      string
	EnvID        string
	EnvName      string
	UserID       string // the userId global attribute, empty when never identified
	EntryPath    string // path of the first page, no query or fragment
	Started      time.Time
	Ended        time.Time
	PageViews    uint64
	Interactions uint64
	Errors       uint64
	HasReplay    bool
}

type SessionTimeline struct {
	// Scope bounds the read; its range (at most MaxRangeTimeline) should cover
	// the session, e.g. its start minus a minute to its end plus a minute.
	Scope     Scope
	SessionID string
	Limit     int // 0 = DefaultTimelineLimit; the statement fetches one more
	Cursor    *TimelineCursor
}

type Signal int

type Stmt struct {
	SQL    string
	Params map[string]string
}

type Temporality int32

type TimelineCursor struct {
	TsNano int64  `json:"t"`
	Kind   string `json:"k"`
	SpanID string `json:"i"`
	Finger string `json:"f"`
}

type TimelineEntry struct {
	Time time.Time
	Kind TimelineKind
	// Name: the span name of a navigation (documentLoad, routeChange), "click",
	// the HTTP method of a failed request, the span name of an error
	// (onerror, unhandledrejection, ...), the event name of a custom event.
	Name string
	// Path is the page (navigation, click, error, event) or the request's path.
	Path     string
	Method   string
	Status   int    // HTTP status of a failed request; 0 for a network failure
	Selector string // click: the element's xpath
	Element  string // click: the element's tag name
	// ErrorType is the exception type of an error, or the SDK's error.type of a
	// failed request. Message is the masked error message, or a failed
	// request's status text.
	ErrorType string
	Message   string
	// Fingerprint is the issue fingerprint of an error (error_stacks): empty
	// until the enrichment worker has seen its stack. The control plane maps it
	// to an issue id.
	Fingerprint string
	TraceID     string
	SpanID      string
	DurationMs  float64
	// Props: a custom event's properties (at most 32, values cut at 256
	// characters); a navigation's "from" (the previous path).
	Props   map[string]string
	Service string
}

type TimelineKind string

type TimelinePage struct {
	Entries []TimelineEntry
	// NextCursor continues after the last returned entry; "" on the last page.
	NextCursor string
}

type TraceCursor struct {
	TsNano  int64  `json:"t"`
	TraceID string `json:"i"`
	// DurNano is the last trace's duration, set only for OrderDurationDesc.
	DurNano int64  `json:"d,omitempty"`
	Finger  string `json:"f"`
}

type TraceOrder string

type TraceQuery struct {
	Scope         Scope
	ErrorsOnly    bool
	MinDurationMs float64
	RootSpanName  string
	// GroupBy are the allowlisted keys the RED summary is split by, valued at
	// each trace's root span (CompileREDGroups).
	GroupBy []string
	// Order is the page's row order; the zero value is newest first. It is
	// part of the cursor's fingerprint: a token only continues the order that
	// produced it.
	Order  TraceOrder
	Limit  int
	Cursor *TraceCursor
}

type TraceSpans struct {
	Scope   Scope
	TraceID string
}

type Workloads struct {
	Scope Scope
	// Workload narrows to one k8s.workload.name (GetWorkload); empty = all.
	Workload string
	// Container narrows to one container; empty = all.
	Container string
}