logstore

package
v1.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: Apache-2.0 Imports: 50 Imported by: 5

Documentation

Overview

Package logstore provides a logs store for Bifrost.

Index

Constants

View Source 
const (
	DefaultWriterMaxBatchSize             = 1000
	DefaultWriterBatchInterval            = "5s"
	DefaultWriterMaxBatchBytes            = 300 * 1024 * 1024
	DefaultWriterQueueCapacity            = 10000
	DefaultWriterDeferredUsageConcurrency = 5
)
View Source 
const (
	GuardrailOutcomeBlocked  = "blocked"
	GuardrailOutcomeDetected = "detected"
)

Guardrail outcome values accepted by SearchFilters.GuardrailOutcomes.

View Source 
const (
	RelayLogKindCall = "call"
	RelayLogKindJob  = "job"

	RelayLogStatusSuccess   = "success"
	RelayLogStatusError     = "error"
	RelayLogStatusCancelled = "cancelled"
)

Relay log kinds and statuses.

View Source 
const (
	WebhookDeliveryStatusClass2xx  = "2xx"
	WebhookDeliveryStatusClass4xx  = "4xx"
	WebhookDeliveryStatusClass5xx  = "5xx"
	WebhookDeliveryStatusClassNone = "none"
)

Webhook delivery status classes, used to filter by response band without the caller having to enumerate individual status codes. StatusClassNone matches attempts where no response arrived at all (a zero status code).

View Source 
const (
	// WarpTopicKindTopic is a subject requests are assigned to directly.
	WarpTopicKindTopic = "topic"
	// WarpTopicKindTheme groups related topics. Nothing is assigned to a theme;
	// a topic names its theme in ParentID.
	WarpTopicKindTheme = "theme"

	// WarpTopicStatusActive topics take new assignments.
	WarpTopicStatusActive = "active"
	// WarpTopicStatusMerged topics were folded into MergedInto. The row stays
	// so assignments written before the merge still resolve.
	WarpTopicStatusMerged = "merged"
	// WarpTopicStatusRetired topics take nothing new: their traffic stopped, or
	// the embedding model they were built with was replaced.
	WarpTopicStatusRetired = "retired"
	// WarpTopicStatusSeeding topics belong to a seed run still writing. The
	// run makes them active once it has written all of them, so a seed that
	// fails partway never reads as one that finished.
	WarpTopicStatusSeeding = "seeding"
)
View Source 
const AgentLogHistoryMaxLimit = 1000

AgentLogHistoryMaxLimit is the hard page-size cap for A2A history searches.

View Source 
const BillingHydrationChunkSize = 3

ClearPayload zeros out both the TEXT payload columns and the Parsed virtual fields on a Log struct. Clearing the Parsed fields is necessary to prevent GORM's BeforeCreate/SerializeFields from re-populating TEXT columns. After calling this, the struct only contains index-weight data suitable for a lightweight DB INSERT. BillingHydrationChunkSize is how many rows a cost recomputation may hydrate at once. Kept deliberately tiny: a hydrated row holds its whole offloaded payload, which can include full message histories and raw request/response bodies, so this is the knob that bounds a recompute worker's peak memory. Billing query pages are capped to the same size because DB-resident modality payloads are materialized by the query before object-store hydration begins.

View Source 
const (
	// DefaultAsyncJobResultTTL is the default TTL for async job results in seconds (1 hour).
	DefaultAsyncJobResultTTL = 3600
)
View Source 
const (
	// DefaultMatViewPauseCancelAfter is how long a migration waits for an
	// in-flight materialized-view refresh pass to finish on its own before
	// cancelling it. A REFRESH ... CONCURRENTLY over a very large logs table can
	// run for many minutes, and while it runs it holds a snapshot that every
	// CREATE INDEX CONCURRENTLY in the database waits on and an ACCESS SHARE lock
	// that every ALTER TABLE logs times out behind.
	DefaultMatViewPauseCancelAfter = 60 * time.Second
)
View Source 
const HiddenRequestTypesContextKey visibilityContextKey = "logstore-hidden-request-types"

HiddenRequestTypesContextKey carries []string request types on dashboard read contexts. Writers and background jobs must not set this key.

View Source 
const (

	// MaxContentSummaryBytes caps the content_summary column, on write and in
	// the list query; a summary that long may have been cut mid-message.
	MaxContentSummaryBytes = 2048
)
View Source 
const OtherDimensionID = otherDimensionID

OtherDimensionID is the id of the synthetic Other ranking bucket that holds the caller's rows whose entity it may not be shown.

View Source 
const UnassignedDimensionID = unassignedDimensionID

UnassignedDimensionID is the id of the synthetic Unassigned ranking bucket, so callers that decorate rankings can tell it apart from a real entity.

View Source 
const WarpMaxTranscriptMessages = 500

WarpMaxTranscriptMessages bounds one detail read. A thread grows two messages per turn with no per-thread cap - the conversation-count prune and the age sweep delete whole threads, never trim live ones - so an unbounded preload made every GET of a long-lived conversation load and serialize an ever-larger transcript. The newest messages win, because they are the context a reopened chat needs, and TotalMessages says the bound applied rather than shortening the thread silently.

Variables

View Source 
var (
	ErrNotFound    = fmt.Errorf("log not found")
	ErrJobInternal = fmt.Errorf("internal job store error")
	// ErrInvalidWebhookReference marks a submit whose webhook endpoint
	// reference is unusable — a caller mistake, not a server failure.
	ErrInvalidWebhookReference = fmt.Errorf("invalid webhook endpoint reference")
	// ErrPartialLogDelete marks a log delete whose log rows are gone but whose
	// Warp topic rows could not be removed after them. Only ClickHouse returns
	// it: it has no transaction to roll the log delete back with.
	ErrPartialLogDelete = fmt.Errorf("logs deleted but their warp topic rows were not")
)
View Source 
var ErrWarpConversationNotFound = errors.New("warp conversation not found")

Warp's saved chats live here rather than in the config store, which was where they started.

A transcript is not configuration. It is user-generated content: it grows with use, it carries the same prompt and answer text the logs do, and it wants the retention and cleanup machinery that already exists on this side. The config store holds providers, keys, budgets and settings - things an operator sets once and an install is worthless without. Deployments size, replicate and back the two up differently, and chat history belongs with the large, expendable one.

ErrWarpConversationNotFound is returned for a thread that does not exist and for one belonging to somebody else, deliberately without distinction. Telling a caller "that exists but is not yours" confirms another person's thread, and a thread id is the only thing an attacker would need to enumerate.

View Source 
var RelayFilterDimensions = []string{"relay_names", "methods", "apps", "virtual_keys", "users", "teams", "customers", "business_units", "projects"}

RelayFilterDimensions are the dimensions GetRelayFilterData can list.

View Source 
var ValidHistogramDimensions = map[HistogramDimension]bool{
	DimensionProvider:     true,
	DimensionTeam:         true,
	DimensionCustomer:     true,
	DimensionUser:         true,
	DimensionBusinessUnit: true,
	DimensionProject:      true,
	DimensionApp:          true,
	DimensionUserAgent:    true,
}

ValidHistogramDimensions is the set of allowed dimension values

View Source 
var ValidRankingDimensions = map[RankingDimension]bool{
	RankingDimensionTeam:         true,
	RankingDimensionCustomer:     true,
	RankingDimensionBusinessUnit: true,
	RankingDimensionProject:      true,
	RankingDimensionUser:         true,
	RankingDimensionVirtualKey:   true,
	RankingDimensionApp:          true,
	RankingDimensionUserAgent:    true,
}

ValidRankingDimensions is what the HTTP rankings endpoint accepts. The routing, JSON-field and comma-list dimensions are deliberately not in it: they are reachable through GetDimensionRankings for in-process callers, and adding one here is a change to the public API.

Functions

func AgentLogHasPayload added in v1.9.0 

func AgentLogHasPayload(l *AgentLog) bool

func AgentLogObjectKey added in v1.9.0 

func AgentLogObjectKey(prefix string, timestamp time.Time, logID string) string

AgentLogObjectKey constructs the S3 object key for a JSON A2A log entry.

func BillingPayloadRequired added in v1.9.0 

func BillingPayloadRequired(objectType string) bool

func BuildAgentLogTags added in v1.9.0 

func BuildAgentLogTags(l *AgentLog) map[string]string

func BuildMCPToolTags added in v1.3.9 

func BuildMCPToolTags(l *MCPToolLog) map[string]string

BuildMCPToolTags creates the object tag map from an MCP tool log's index fields. S3 allows max 10 tags per object.

func BuildRelayLogTags added in v1.11.1 

func BuildRelayLogTags(l *RelayLog) map[string]string

func BuildTags added in v1.3.2 

func BuildTags(l *Log) map[string]string

BuildTags creates the S3 object tag map from a Log's index fields. S3 allows max 10 tags per object; chosen for lifecycle rules and S3 Metadata Tables queryability.

func ClearPayload added in v1.3.2 

func ClearPayload(l *Log)

func ClearPayloadFiltered added in v1.3.7 

func ClearPayloadFiltered(l *Log, excluded map[string]struct{})

ClearPayloadFiltered zeros only the payload fields that are not present in the excluded set (i.e. the fields that will be sent to object storage). Fields in the excluded set stay in the DB and are left untouched. An empty/nil excluded map is equivalent to ClearPayload.

func DecodeWarpVector added in v1.11.0 

func DecodeWarpVector(encoded []byte) ([]float32, error)

DecodeWarpVector reverses EncodeWarpVector.

func DefaultBucketSize added in v1.9.0 

func DefaultBucketSize(start, end *time.Time) int64

DefaultBucketSize picks a histogram bucket width for a time range, in seconds.

The goal is a readable number of bars rather than a fixed resolution: a one-hour range wants minutes and a one-year range wants months, and using either width for the other produces a chart nobody can read. The thresholds are chosen so any range lands somewhere between roughly 12 and 60 buckets.

A missing bound falls back to hourly rather than erroring. Callers reach here from query strings where an absent parameter is normal.

func DimensionColumnDef added in v1.3.14 

func DimensionColumnDef(d RankingDimension) (idCol, nameCol string, ok bool)

DimensionColumnDef returns the column pair for a supported ranking dimension.

func EncodeWarpVector added in v1.11.0 

func EncodeWarpVector(vector []float32) []byte

EncodeWarpVector packs a vector as little-endian float32s, four bytes a dimension. Stored this way instead of as JSON because a 1536-dimension vector is 6 KB packed and about three times that as text, and the unmatched pool holds thousands.

func ExtractPayload added in v1.3.2 

func ExtractPayload(l *Log) map[string]string

ExtractPayload reads the serialized TEXT payload fields from a Log into a map. The map keys are the DB column names.

func ExtractPayloadFiltered added in v1.3.7 

func ExtractPayloadFiltered(l *Log, excluded map[string]struct{}) map[string]string

ExtractPayloadFiltered is like ExtractPayload but omits fields present in the excluded set. An empty/nil excluded map is equivalent to ExtractPayload.

func HiddenRequestTypesFromContext added in v1.6.1 

func HiddenRequestTypesFromContext(ctx context.Context) []string

HiddenRequestTypesFromContext returns the request types excluded from a read.

func IsPassthroughObjectType added in v1.10.0 

func IsPassthroughObjectType(objectType string) bool

IsPassthroughObjectType reports whether objectType names a passthrough call.

func IsPostgresStatementTimeoutError added in v1.9.0 

func IsPostgresStatementTimeoutError(err error) bool

IsPostgresStatementTimeoutError reports whether err is PostgreSQL query_canceled (SQLSTATE 57014), which is what statement_timeout raises. It is Postgres-specific: SQLite has no statement timeout of this kind and ClickHouse signals one with its own exception code, so it reports false for those stores. It is also a transient error (IsTransientWriteError reports true), but it deserves its own recovery: the same statement will usually time out again, while a smaller write of the same rows may finish within the budget, so callers split the batch instead of retrying or dropping it whole.

func IsTransientWriteError added in v1.9.0 

func IsTransientWriteError(err error) bool

IsTransientWriteError reports whether a failed batch write failed for a reason that has nothing to do with the rows in it: the connection dropped, the server was unreachable or shutting down, the statement timed out or waited too long for a lock, or the context was cancelled. Retrying each row of the batch on its own cannot help with any of these; it only multiplies the failed statements by the batch size. Callers use it to decide between retrying the batch whole and the per-row fallback that isolates a single bad row.

Coverage by store: the context, net.Error, driver.ErrBadConn and EOF checks apply to every SQL driver. The server-side classification (SQLSTATE classes, lock_timeout, pgx connect and timeout errors) is Postgres only, via isPostgresTransientError. SQLite's SQLITE_BUSY and SQLITE_LOCKED ("database is locked": another connection holds the single writer lock) are recognised via isSQLiteTransientError. ClickHouse exception codes are not recognised, so on that store only the driver-agnostic checks fire and everything else takes the row-isolating fallback.

Anything not recognised here (including data errors such as SQLSTATE class 22 and constraint violations in class 23, serialization failures from the JSON column types, and the pgx parameter-limit error) reports false, so the row-isolating fallback remains the default.

func MCPToolObjectKey added in v1.3.9 

func MCPToolObjectKey(prefix string, timestamp time.Time, logID string) string

MCPToolObjectKey constructs the S3 object key for a JSON MCP tool log entry.

func MarshalAgentLogPayload added in v1.9.0 

func MarshalAgentLogPayload(l *AgentLog) ([]byte, error)

func MarshalMCPToolLogPayload added in v1.3.9 

func MarshalMCPToolLogPayload(l *MCPToolLog) ([]byte, error)

MarshalMCPToolLogPayload serializes a full MCP tool log for object storage. The object-store copy is intentionally complete; the DB row is only a lightweight index plus a short input preview.

func MarshalPayload added in v1.3.2 

func MarshalPayload(payload map[string]string) ([]byte, error)

func MarshalRelayLogPayload added in v1.11.1 

func MarshalRelayLogPayload(l *RelayLog) ([]byte, error)

MarshalRelayLogPayload serializes a Relay Logs row's full bodies for object storage.

func MergeAgentLogPayloadFromJSON added in v1.9.0 

func MergeAgentLogPayloadFromJSON(l *AgentLog, data []byte) error

func MergeMCPToolLogPayloadFromJSON added in v1.3.9 

func MergeMCPToolLogPayloadFromJSON(l *MCPToolLog, data []byte) error

MergeMCPToolLogPayloadFromJSON replaces an MCP tool log with the full object storage copy while preserving DB-local hydration state.

func MergePayloadFromJSON added in v1.3.2 

func MergePayloadFromJSON(l *Log, data []byte) error

MergePayloadFromJSON takes a JSON payload (as marshaled by MarshalPayload) and merges the fields back into the Log struct's serialized TEXT columns, then calls DeserializeFields to populate the Parsed virtual fields.

func MergeRelayLogPayloadFromJSON added in v1.11.1 

func MergeRelayLogPayloadFromJSON(l *RelayLog, data []byte) error

MergeRelayLogPayloadFromJSON restores the full bodies read back from object storage.

func MigrationInProgressFor added in v1.9.0 

func MigrationInProgressFor(ctx context.Context, store any) bool

MigrationInProgressFor is the type-asserting helper callers use so a store without a gate reads as "not migrating".

func MigrationLockRetryOptions added in v1.10.0 

func MigrationLockRetryOptions(cfg *Config, logger schemas.Logger) postgresconn.LockRetryOptions

MigrationLockRetryOptions returns the lock-timeout retry options a log store config asks for: its migration_lock_retry_budget when cfg is a Postgres log store, and the package default otherwise. Downstream migrations that run against the log store (bifrost-enterprise) call it so one setting governs them.

func ObjectKey added in v1.3.2 

func ObjectKey(prefix string, timestamp time.Time, logID string) string

ObjectKey constructs the S3 object key for a JSON log entry.

func PauseMatViewMaintenance added in v1.10.0 

func PauseMatViewMaintenance(ctx context.Context, db *gorm.DB, logger schemas.Logger, opts MatViewPauseOptions) (release func(), err error)

PauseMatViewMaintenance stops every replica from starting a materialized-view refresh pass until release is called. Migrations call it so a long refresh cannot block their DDL.

It works across versions because it holds the same advisory lock (matviewRefreshAdvisoryLockKey) that every refresher, including older releases, try-locks before a pass and skips the pass when it cannot get it. A pass that is already running is waited for; after opts.CancelAfter its REFRESH statements are cancelled with pg_cancel_backend. A cancelled REFRESH ... CONCURRENTLY rolls back and the view keeps its previous contents. The refresher moves on to its next view while still holding the lock, so the cancel repeats on each poll until the pass ends and the lock frees. Sessions are never terminated, and a holder that is not running a REFRESH is never cancelled.

Non-Postgres stores have no materialized views, so this is a no-op there. The wait is bounded by ctx; callers should treat an error as "proceed without the pause" rather than fail their migrations.

func PauseMatViewsForMigrations added in v1.10.0 

func PauseMatViewsForMigrations(ctx context.Context, db *gorm.DB, logger schemas.Logger, opts MatViewPauseOptions) (release func())

PauseMatViewsForMigrations is PauseMatViewMaintenance for migration runners: it bounds the wait and never fails the caller. On any error it logs a warning and returns a no-op release so migrations carry on unpaused.

func PayloadFieldNames added in v1.3.2 

func PayloadFieldNames() []string

PayloadFieldNames returns the list of DB column names that are payload fields.

func PrepareAgentLogDBEntry added in v1.9.0 

func PrepareAgentLogDBEntry(l *AgentLog, objectKey string)

func PrepareMCPToolDBEntry added in v1.3.9 

func PrepareMCPToolDBEntry(l *MCPToolLog)

PrepareMCPToolDBEntry converts an MCP tool log to the lightweight DB form used by hybrid storage. It preserves indexed/display fields and metadata, keeps only a 200-character JSON-string argument preview, and clears result and error payloads.

func PrepareRelayLogDBEntry added in v1.11.1 

func PrepareRelayLogDBEntry(l *RelayLog, objectKey string)

PrepareRelayLogDBEntry turns a Relay Logs row into its database form in hybrid mode: the bodies shrink to a preview (or nothing, when content is hidden) and the row points at the object holding them in full.

func RelayLogHasPayload added in v1.11.1 

func RelayLogHasPayload(l *RelayLog) bool

RelayLogHasPayload reports whether a Relay Logs row carries a body to offload.

func RelayLogObjectKey added in v1.11.1 

func RelayLogObjectKey(prefix string, timestamp time.Time, logID string) string

RelayLogObjectKey constructs the S3 object key for a JSON Relay Logs entry.

func ReleaseBillingPayloads added in v1.5.5 

func ReleaseBillingPayloads(logs []*Log)

ReleaseBillingPayloads drops the payload fields from rows that have already been priced, so a batch never accumulates more than one chunk of them.

Safe because pricing is the last thing that reads these: the recalc job keeps only the ID, timestamp and computed cost afterwards, and the rows are never written back (BulkUpdateCost takes an id → CostUpdate map).

Types

type AgentFilterData added in v1.9.0 

type AgentFilterData struct {
	Users         []AgentFilterKeyPair `json:"users,omitempty"`
	VirtualKeys   []AgentFilterKeyPair `json:"virtual_keys,omitempty"`
	Teams         []AgentFilterKeyPair `json:"teams,omitempty"`
	Customers     []AgentFilterKeyPair `json:"customers,omitempty"`
	BusinessUnits []AgentFilterKeyPair `json:"business_units,omitempty"`
	Projects      []AgentFilterKeyPair `json:"projects,omitempty"`
}

type AgentFilterKeyPair added in v1.9.0 

type AgentFilterKeyPair struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type AgentHistogramBucket added in v1.9.0 

type AgentHistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	Count     int64     `json:"count"`
	Success   int64     `json:"success"`
	Error     int64     `json:"error"`
}

AgentHistogramBucket is one time bucket of the A2A volume chart.

type AgentHistogramResult added in v1.9.0 

type AgentHistogramResult struct {
	Buckets           []AgentHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                  `json:"bucket_size_seconds"`
}

AgentHistogramResult is the bucketed A2A volume series.

type AgentLog added in v1.9.0 

type AgentLog struct {
	ID        string    `gorm:"primaryKey;type:varchar(255)" json:"id"`
	Timestamp time.Time `gorm:"index:idx_agent_logs_timestamp;not null" json:"timestamp"`
	CreatedAt time.Time `gorm:"index:idx_agent_logs_created_at;not null;autoCreateTime:false;default:CURRENT_TIMESTAMP" json:"created_at"`

	RecordKind string `gorm:"type:varchar(32);index:idx_agent_logs_record_kind;not null" json:"record_kind"`
	Operation  string `gorm:"type:varchar(128);index:idx_agent_logs_operation" json:"operation"`
	Status     string `gorm:"type:varchar(50);index:idx_agent_logs_status;not null" json:"status"`
	AgentName  string `gorm:"type:varchar(255);index:idx_agent_logs_agent_name;not null" json:"agent_name"`

	UserID            *string `gorm:"type:varchar(255);index:idx_agent_logs_user_id" json:"user_id,omitempty"`
	UserName          *string `gorm:"type:varchar(255)" json:"user_name,omitempty"`
	VirtualKeyID      *string `gorm:"type:varchar(255);index:idx_agent_logs_virtual_key_id" json:"virtual_key_id,omitempty"`
	VirtualKeyName    *string `gorm:"type:varchar(255)" json:"virtual_key_name,omitempty"`
	TeamID            *string `gorm:"type:varchar(255);index:idx_agent_logs_team_id" json:"team_id,omitempty"`
	TeamName          *string `gorm:"type:varchar(255)" json:"team_name,omitempty"`
	CustomerID        *string `gorm:"type:varchar(255);index:idx_agent_logs_customer_id" json:"customer_id,omitempty"`
	CustomerName      *string `gorm:"type:varchar(255)" json:"customer_name,omitempty"`
	BusinessUnitID    *string `gorm:"type:varchar(255);index:idx_agent_logs_business_unit_id" json:"business_unit_id,omitempty"`
	BusinessUnitName  *string `gorm:"type:varchar(255)" json:"business_unit_name,omitempty"`
	ProjectID         *string `gorm:"type:varchar(255);index:idx_agent_logs_project_id" json:"project_id,omitempty"`
	ProjectName       *string `gorm:"type:varchar(255)" json:"project_name,omitempty"`
	TeamIDs           *string `gorm:"type:text" json:"-"`
	TeamNames         *string `gorm:"type:text" json:"-"`
	CustomerIDs       *string `gorm:"type:text" json:"-"`
	CustomerNames     *string `gorm:"type:text" json:"-"`
	BusinessUnitIDs   *string `gorm:"type:text" json:"-"`
	BusinessUnitNames *string `gorm:"type:text" json:"-"`
	BudgetIDs         *string `gorm:"type:text" json:"-"`
	RateLimitIDs      *string `gorm:"type:text" json:"-"`
	RequestID         string  `gorm:"type:varchar(255);index:idx_agent_logs_request_id;not null" json:"request_id"`
	TraceID           *string `gorm:"type:varchar(255);index:idx_agent_logs_trace_id" json:"trace_id,omitempty"`

	TaskID            *string `gorm:"type:varchar(255);index:idx_agent_logs_task_id" json:"task_id,omitempty"`
	ContextID         *string `gorm:"type:varchar(255);index:idx_agent_logs_context_id" json:"context_id,omitempty"`
	MessageID         *string `gorm:"type:varchar(255);index:idx_agent_logs_message_id" json:"message_id,omitempty"`
	RequestMessageID  *string `gorm:"type:varchar(255);index:idx_agent_logs_request_message_id" json:"request_message_id,omitempty"`
	ResponseMessageID *string `gorm:"type:varchar(255);index:idx_agent_logs_response_message_id" json:"response_message_id,omitempty"`
	ArtifactID        *string `gorm:"type:varchar(255);index:idx_agent_logs_artifact_id" json:"artifact_id,omitempty"`
	PushConfigID      *string `gorm:"type:varchar(255);index:idx_agent_logs_push_config_id" json:"push_config_id,omitempty"`
	DeliveryID        *string `gorm:"type:varchar(255);index:idx_agent_logs_delivery_id" json:"delivery_id,omitempty"`
	AttemptID         *string `gorm:"type:varchar(255);index:idx_agent_logs_attempt_id" json:"attempt_id,omitempty"`
	EventSequence     *int64  `json:"event_sequence,omitempty"`
	EventType         *string `gorm:"type:varchar(64);index:idx_agent_logs_event_type" json:"event_type,omitempty"`
	TaskState         *string `gorm:"type:varchar(64);index:idx_agent_logs_task_state" json:"task_state,omitempty"`

	DownstreamTransport *string  `gorm:"type:varchar(32)" json:"downstream_transport,omitempty"`
	UpstreamTransport   *string  `gorm:"type:varchar(32)" json:"upstream_transport,omitempty"`
	Latency             *float64 `json:"latency,omitempty"`
	// UpstreamLatency/OverheadLatency mirror the logs table: request-level time
	// blocked on the upstream agent socket vs Bifrost's own cost, in ms. Only
	// request rows carry them; nil means unmeasured.
	UpstreamLatency   *float64 `json:"upstream_latency,omitempty"`
	OverheadLatency   *float64 `json:"overhead_latency,omitempty"`
	OverheadBreakdown string   `gorm:"type:text" json:"-"` // Name-keyed JSON object, mirroring Log.OverheadBreakdown
	ContentType       *string  `gorm:"type:varchar(255)" json:"content_type,omitempty"`
	RawRequest        *string  `gorm:"type:text" json:"raw_request,omitempty"` // Base64 preserves binary transport bytes.
	RawResponse       *string  `gorm:"type:text" json:"raw_response,omitempty"`
	RequestBody       *string  `gorm:"type:text" json:"request_body,omitempty"`
	ResponseBody      *string  `gorm:"type:text" json:"response_body,omitempty"`
	EventBody         *string  `gorm:"type:text" json:"event_body,omitempty"`
	ErrorDetails      string   `gorm:"type:text" json:"-"`
	PluginLogs        string   `gorm:"type:text" json:"plugin_logs,omitempty"`

	PayloadReference *string `gorm:"type:varchar(1024)" json:"payload_reference,omitempty"`
	HasObject        bool    `gorm:"default:false" json:"has_object"`
	ContentHidden    bool    `gorm:"default:false" json:"-"`

	ErrorDetailsParsed      *schemas.BifrostError `gorm:"-" json:"error_details,omitempty"`
	OverheadBreakdownParsed []OverheadBucket      `gorm:"-" json:"overhead_breakdown,omitempty"`
	TeamIDsParsed           []string              `gorm:"-" json:"team_ids,omitempty"`
	TeamNamesParsed         []string              `gorm:"-" json:"team_names,omitempty"`
	CustomerIDsParsed       []string              `gorm:"-" json:"customer_ids,omitempty"`
	CustomerNamesParsed     []string              `gorm:"-" json:"customer_names,omitempty"`
	BusinessUnitIDsParsed   []string              `gorm:"-" json:"business_unit_ids,omitempty"`
	BusinessUnitNamesParsed []string              `gorm:"-" json:"business_unit_names,omitempty"`
	BudgetIDsParsed         []string              `gorm:"-" json:"budget_ids,omitempty"`
	RateLimitIDsParsed      []string              `gorm:"-" json:"rate_limit_ids,omitempty"`
}

AgentLog records Agent Gateway request and event observability. Queryable metadata remains in the database while hybrid storage can offload protocol request and response bodies.

func (*AgentLog) AfterFind added in v1.9.0 

func (l *AgentLog) AfterFind(_ *gorm.DB) error

func (*AgentLog) ApplyGovernanceContext added in v1.9.0 

func (l *AgentLog) ApplyGovernanceContext(ctx *schemas.BifrostContext)

func (*AgentLog) BeforeCreate added in v1.9.0 

func (l *AgentLog) BeforeCreate(_ *gorm.DB) error

func (*AgentLog) DeserializeFields added in v1.9.0 

func (l *AgentLog) DeserializeFields() error

func (*AgentLog) SerializeFields added in v1.9.0 

func (l *AgentLog) SerializeFields() error

func (AgentLog) TableName added in v1.9.0 

func (AgentLog) TableName() string

type AgentLogDetail added in v1.9.0 

type AgentLogDetail struct {
	RawRequest  *string `json:"raw_request,omitempty"` // Base64-encoded upstream body bytes.
	RawResponse *string `json:"raw_response,omitempty"`
	AgentLogSummary
	RequestBody  *string               `json:"request_body,omitempty"`
	ResponseBody *string               `json:"response_body,omitempty"`
	EventBody    *string               `json:"event_body,omitempty"`
	PluginLogs   string                `json:"plugin_logs,omitempty"`
	ErrorDetails *schemas.BifrostError `json:"error_details,omitempty"`
	// contains filtered or unexported fields
}

AgentLogDetail is the rich public contract. Persistence and object-storage bookkeeping never leave the log store through this type.

func NewAgentLogDetail added in v1.9.0 

func NewAgentLogDetail(entry *AgentLog) AgentLogDetail

type AgentLogHistoryFilter added in v1.9.0 

type AgentLogHistoryFilter struct {
	GroupSessions  bool
	AgentName      []string
	StartTime      *time.Time
	EndTime        *time.Time
	Operation      []string
	UserID         []string
	VirtualKeyID   []string
	TeamID         []string
	CustomerID     []string
	BusinessUnitID []string
	ProjectID      []string
	RequestID      string
	TraceID        string
	TaskID         string
	ContextID      string
	PushConfigID   string
	DeliveryID     string
	AttemptID      string
	RecordKind     []string
	EventType      []string
	TaskState      []string
	Status         []string
	// Search is a free-text match across DB-resident metadata columns only
	// (agent name, operation, task/context/request/trace id and the serialized
	// error). Protocol payloads are deliberately excluded: under the hybrid
	// store they live in object storage and are not queryable in SQL.
	Search string
}

AgentLogHistoryFilter selects indexed A2A history metadata.

The slice fields match any of their values (OR); every populated filter must match (AND).

func (AgentLogHistoryFilter) SessionGroupingActive added in v1.9.0 

func (f AgentLogHistoryFilter) SessionGroupingActive() bool

SessionGroupingActive reports whether context grouping may collapse this search. Explicit identifier searches keep every matching operation visible.

type AgentLogHistoryResult added in v1.9.0 

type AgentLogHistoryResult struct {
	Logs       []AgentLogSummary `json:"logs"`
	Pagination PaginationOptions `json:"pagination"`
}

AgentLogHistoryResult is a metadata-only page.

type AgentLogOperation added in v1.9.0 

type AgentLogOperation struct {
	AgentLogDetail
	Events []AgentLogDetail `json:"events"`
}

AgentLogOperation is one request row with the event rows produced by that request.

type AgentLogOperationResult added in v1.9.0 

type AgentLogOperationResult struct {
	Logs       []AgentLogOperation `json:"logs"`
	Pagination PaginationOptions   `json:"pagination"`
}

AgentLogOperationResult is a bounded page of hydrated request operations.

type AgentLogStats added in v1.9.0 

type AgentLogStats struct {
	TotalEntries   int64   `json:"total_entries"`
	SuccessCount   int64   `json:"success_count"`
	ErrorCount     int64   `json:"error_count"`
	SuccessRate    float64 `json:"success_rate"`    // Percentage of terminal entries that succeeded
	AverageLatency float64 `json:"average_latency"` // Average latency in milliseconds
}

AgentLogStats aggregates an A2A history search. A2A has no pricing model, so there are deliberately no token or cost fields here.

type AgentLogSummary added in v1.9.0 

type AgentLogSummary struct {
	SessionChildCount       int64            `gorm:"-" json:"session_child_count,omitempty"`
	ID                      string           `json:"id"`
	Timestamp               time.Time        `json:"timestamp"`
	RecordKind              string           `json:"record_kind"`
	Operation               string           `json:"operation"`
	Status                  string           `json:"status"`
	AgentName               string           `json:"agent_name"`
	UserID                  *string          `json:"user_id,omitempty"`
	UserName                *string          `json:"user_name,omitempty"`
	VirtualKeyID            *string          `json:"virtual_key_id,omitempty"`
	VirtualKeyName          *string          `json:"virtual_key_name,omitempty"`
	TeamID                  *string          `json:"team_id,omitempty"`
	TeamName                *string          `json:"team_name,omitempty"`
	TeamIDs                 []string         `gorm:"-" json:"team_ids,omitempty"`
	TeamNames               []string         `gorm:"-" json:"team_names,omitempty"`
	CustomerID              *string          `json:"customer_id,omitempty"`
	CustomerName            *string          `json:"customer_name,omitempty"`
	CustomerIDs             []string         `gorm:"-" json:"customer_ids,omitempty"`
	CustomerNames           []string         `gorm:"-" json:"customer_names,omitempty"`
	BusinessUnitID          *string          `json:"business_unit_id,omitempty"`
	BusinessUnitName        *string          `json:"business_unit_name,omitempty"`
	BusinessUnitIDs         []string         `gorm:"-" json:"business_unit_ids,omitempty"`
	BusinessUnitNames       []string         `gorm:"-" json:"business_unit_names,omitempty"`
	ProjectID               *string          `json:"project_id,omitempty"`
	ProjectName             *string          `json:"project_name,omitempty"`
	BudgetIDs               []string         `gorm:"-" json:"budget_ids,omitempty"`
	RateLimitIDs            []string         `gorm:"-" json:"rate_limit_ids,omitempty"`
	TeamIDsStored           *string          `gorm:"column:team_ids" json:"-"`
	TeamNamesStored         *string          `gorm:"column:team_names" json:"-"`
	CustomerIDsStored       *string          `gorm:"column:customer_ids" json:"-"`
	CustomerNamesStored     *string          `gorm:"column:customer_names" json:"-"`
	BusinessUnitIDsStored   *string          `gorm:"column:business_unit_ids" json:"-"`
	BusinessUnitNamesStored *string          `gorm:"column:business_unit_names" json:"-"`
	BudgetIDsStored         *string          `gorm:"column:budget_ids" json:"-"`
	RateLimitIDsStored      *string          `gorm:"column:rate_limit_ids" json:"-"`
	RequestID               string           `json:"request_id"`
	TraceID                 *string          `json:"trace_id,omitempty"`
	TaskID                  *string          `json:"task_id,omitempty"`
	ContextID               *string          `json:"context_id,omitempty"`
	MessageID               *string          `json:"message_id,omitempty"`
	RequestMessageID        *string          `json:"request_message_id,omitempty"`
	ResponseMessageID       *string          `json:"response_message_id,omitempty"`
	ArtifactID              *string          `json:"artifact_id,omitempty"`
	PushConfigID            *string          `json:"push_config_id,omitempty"`
	DeliveryID              *string          `json:"delivery_id,omitempty"`
	AttemptID               *string          `json:"attempt_id,omitempty"`
	EventSequence           *int64           `json:"event_sequence,omitempty"`
	EventType               *string          `json:"event_type,omitempty"`
	TaskState               *string          `json:"task_state,omitempty"`
	DownstreamTransport     *string          `json:"downstream_transport,omitempty"`
	UpstreamTransport       *string          `json:"upstream_transport,omitempty"`
	Latency                 *float64         `json:"latency,omitempty"`
	UpstreamLatency         *float64         `json:"upstream_latency,omitempty"`
	OverheadLatency         *float64         `json:"overhead_latency,omitempty"`
	OverheadBreakdownStored *string          `gorm:"column:overhead_breakdown" json:"-"`
	OverheadBreakdown       []OverheadBucket `gorm:"-" json:"overhead_breakdown,omitempty"`
	ContentType             *string          `json:"content_type,omitempty"`
	Input                   *string          `json:"input,omitempty"`
}

AgentLogSummary is the compact metadata contract returned by list searches.

type AgentTopAgentResult added in v1.9.0 

type AgentTopAgentResult struct {
	AgentName      string  `json:"agent_name"`
	Count          int64   `json:"count"`
	ErrorCount     int64   `json:"error_count"`
	AverageLatency float64 `json:"average_latency"` // Average latency in milliseconds
}

AgentTopAgentResult is one Agent's operation totals in a top-Agents ranking.

type AgentTopAgentsResult added in v1.9.0 

type AgentTopAgentsResult struct {
	Agents []AgentTopAgentResult `json:"agents"`
}

AgentTopAgentsResult ranks Agents by operation count.

type AsyncJob added in v1.2.22 

type AsyncJob struct {
	ID           string                 `gorm:"primaryKey;type:varchar(255)" json:"id"`
	Status       schemas.AsyncJobStatus `gorm:"type:varchar(50);index:idx_async_jobs_status;not null" json:"status"`
	RequestID    string                 `gorm:"type:varchar(255)" json:"request_id,omitempty"`
	RequestType  schemas.RequestType    `gorm:"type:varchar(50);index:idx_async_jobs_request_type;not null" json:"request_type"`
	Response     string                 `gorm:"type:text" json:"response"`
	StatusCode   int                    `gorm:"default:0" json:"status_code,omitempty"`
	Error        string                 `gorm:"type:text" json:"error,omitempty"`
	VirtualKeyID *string                `gorm:"type:varchar(255);index:idx_async_jobs_vk_id" json:"virtual_key_id,omitempty"`
	// WebhookEndpointID references the webhook endpoint to notify when this
	// job reaches a terminal state, when one was requested at submit time.
	WebhookEndpointID *string    `gorm:"type:varchar(36)" json:"webhook_endpoint_id,omitempty"`
	ResultTTL         int        `gorm:"default:3600" json:"-"` // TTL in seconds, used to calculate ExpiresAt on completion
	ExpiresAt         *time.Time `gorm:"index:idx_async_jobs_expires_at" json:"expires_at,omitempty"`
	CreatedAt         time.Time  `gorm:"index;not null" json:"created_at"`
	CompletedAt       *time.Time `json:"completed_at,omitempty"`
}

AsyncJob represents an asynchronous job record in the database. Jobs are created when requests are submitted to async endpoints and updated when the background operation completes or fails.

func (AsyncJob) TableName added in v1.2.22 

func (AsyncJob) TableName() string

TableName sets the table name for GORM

func (*AsyncJob) ToResponse added in v1.2.22 

func (j *AsyncJob) ToResponse() *schemas.AsyncJobResponse

ToResponse converts an AsyncJob database record to an AsyncJobResponse for JSON output.

type AsyncJobCleaner added in v1.2.22 

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

AsyncJobCleaner manages the cleanup of expired async jobs.

func NewAsyncJobCleaner added in v1.2.22 

func NewAsyncJobCleaner(store LogStore, logger schemas.Logger) *AsyncJobCleaner

NewAsyncJobCleaner creates a new AsyncJobCleaner instance.

func (*AsyncJobCleaner) StartCleanupRoutine added in v1.2.22 

func (c *AsyncJobCleaner) StartCleanupRoutine()

StartCleanupRoutine starts a goroutine that periodically cleans up expired async jobs.

func (*AsyncJobCleaner) StopCleanupRoutine added in v1.2.22 

func (c *AsyncJobCleaner) StopCleanupRoutine()

StopCleanupRoutine gracefully stops the cleanup goroutine.

type AsyncJobExecutor added in v1.2.22 

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

AsyncJobExecutor manages async job creation and background execution.

func NewAsyncJobExecutor added in v1.2.22 

func NewAsyncJobExecutor(logstore LogStore, governanceStore GovernanceStore, webhookDispatcher WebhookDispatcher, webhookManager WebhookManager, logger schemas.Logger) *AsyncJobExecutor

NewAsyncJobExecutor creates a new AsyncJobExecutor. A nil webhookDispatcher leaves webhook notification disabled; a nil webhookManager rejects any submit that references a webhook endpoint.

func (*AsyncJobExecutor) RetrieveJob added in v1.2.22 

func (e *AsyncJobExecutor) RetrieveJob(ctx context.Context, jobID string, vkValue *string, operationType schemas.RequestType) (*AsyncJob, error)

RetrieveJob retrieves a job by its ID.

func (*AsyncJobExecutor) SubmitJob added in v1.2.22 

func (e *AsyncJobExecutor) SubmitJob(bifrostCtx *schemas.BifrostContext, resultTTL int, operation AsyncOperation, operationType schemas.RequestType) (*AsyncJob, error)

SubmitJob creates a pending job, starts background execution, and returns the job record.

type AsyncOperation added in v1.2.22 

type AsyncOperation func(ctx *schemas.BifrostContext) (any, *schemas.BifrostError)

AsyncOperation represents a function that can be executed asynchronously. It returns the response and an optional BifrostError.

type BillingHydrationResult added in v1.5.5 

type BillingHydrationResult struct {
	// Hydrated lists the rows whose pricing inputs were fetched from object storage.
	// These are the only rows worth persisting via BulkBackfillBillingPayloads: every
	// other row's inputs already came from the database.
	Hydrated []string
	// Unpriceable lists rows whose inputs could not be recovered — for example, a
	// missing object or unavailable object storage. Callers must skip these rather
	// than price them from the lossy fallback.
	Unpriceable []string
}

BillingHydrationResult reports what one hydration pass actually did, so the caller does not have to infer it from the rows.

type BillingPayloadBackfill added in v1.5.5 

type BillingPayloadBackfill struct {
	TokenUsage string
	CacheDebug string
}

BillingPayloadBackfill carries pricing inputs recovered from object storage that are worth writing back into the row.

Deliberately only the two small ones. token_usage is a few hundred bytes of counters and cache_debug a handful of cache-hit fields, so keeping them in the row is cheap and repairs legacy rows written before pricing metadata became unconditionally DB-resident. The modality payloads (image_generation_output above all, which carries base64 image bytes) are exactly what offloading exists to keep out of the database, so they stay in object storage and modality rows keep fetching.

type CleanerConfig added in v1.1.36 

type CleanerConfig struct {
	RetentionDays int
}

CleanerConfig holds configuration for the log cleaner

type ClickHouseConfig added in v1.4.3 

type ClickHouseConfig struct {
	Host     *schemas.SecretVar `json:"host"`
	Port     *schemas.SecretVar `json:"port"`
	Database *schemas.SecretVar `json:"database"`
	Username *schemas.SecretVar `json:"username"`
	Password *schemas.SecretVar `json:"password"`
	// Protocol selects the ClickHouse wire protocol: "native" (default, port
	// 9000/9440) or "http" (port 8123/8443). clickhouse-go derives the protocol
	// from the DSN scheme, so this maps to clickhouse:// vs http(s)://.
	Protocol string `json:"protocol,omitempty"`
	// Secure enables TLS (native: secure=true; http: switches to https).
	Secure bool `json:"secure,omitempty"`
	// DialTimeout is the connection dial timeout in milliseconds (JSON config
	// duration fields are integer milliseconds). 0 means the 10s default.
	DialTimeout int `json:"dial_timeout,omitempty"`
	// MaxQuerySize is the ClickHouse max_query_size setting in bytes. 0 means the 16 MiB default.
	MaxQuerySize int `json:"max_query_size,omitempty"`
	// Cluster, when set, makes DDL run as `ON CLUSTER <name>` against
	// ReplicatedReplacingMergeTree engines. Empty means single-node.
	Cluster string `json:"cluster,omitempty"`
}

ClickHouseConfig represents the configuration for a ClickHouse log store.

ClickHouse is an append-only columnar OLAP store. The backend uses ReplacingMergeTree tables with a connection-level `final = 1` setting so reads transparently see the latest version of each row (see clickhousestore.go for the mutation strategy).

type ClickHouseLogStore added in v1.4.3 

type ClickHouseLogStore struct {
	*RDBLogStore
	// contains filtered or unexported fields
}

ClickHouseLogStore is a LogStore backed by ClickHouse. It embeds *RDBLogStore to reuse the (dialect-aware) analytics/read path and overrides only the methods ClickHouse cannot satisfy through plain GORM:

  • inserts that relied on ON CONFLICT DO NOTHING (ClickHouse has no upsert; idempotency comes from ReplacingMergeTree dedup + the connection-level `final = 1` setting, so a plain INSERT is correct),
  • row updates (ClickHouse has no cheap UPDATE; we read-modify-write and re-insert, letting the `ver` DEFAULT now64() column make the newest insert win on merge - see clickhousemigrate.go),
  • every delete. The GORM ClickHouse driver rewrites Delete() into `ALTER TABLE ... DELETE`, a heavyweight mutation that rewrites every column of every part holding a matching row and leaves the old copy on disk for old_parts_lifetime (#7098). All deletes here go through chLightweightDelete, a raw `DELETE FROM ... WHERE` that only writes the _row_exists mask. Never call GORM Delete() on this store.

Table TTL (logs_store.retention_days) is the primary retention mechanism and is reconciled on every startup (clickhouseReconcileTTL); the LogsCleaner sweep is a single lightweight delete per run.

func (*ClickHouseLogStore) AddWarpTopicUnmatched added in v1.11.0 

func (s *ClickHouseLogStore) AddWarpTopicUnmatched(ctx context.Context, rows []WarpTopicUnmatched) error

AddWarpTopicUnmatched puts requests in the unmatched pool.

func (*ClickHouseLogStore) AddWarpVectorDeletes added in v1.11.0 

func (s *ClickHouseLogStore) AddWarpVectorDeletes(ctx context.Context, rows []WarpVectorDelete) error

AddWarpVectorDeletes records deleted logs whose vector delete failed. A log recorded twice is one row once the table merges, and listed twice until then, which costs a retry one more vector delete.

func (*ClickHouseLogStore) AppendWarpMessages added in v1.9.0 

func (s *ClickHouseLogStore) AppendWarpMessages(ctx context.Context, ownerID, conversationID string, messages []WarpMessage) error

AppendWarpMessages adds turns and bumps the thread's updated time.

Messages are written before the bump, which is the safe half to lose: a thread carrying its new messages under a stale timestamp sorts low in the history but is intact, while a bumped thread with no messages would advertise a turn that was never saved. The SQL store gets both or neither; here the choice has to be made explicitly.

func (*ClickHouseLogStore) BatchCreateAgentLogsIfNotExists added in v1.9.0 

func (s *ClickHouseLogStore) BatchCreateAgentLogsIfNotExists(ctx context.Context, entries []*AgentLog) ([]string, error)

BatchCreateAgentLogsIfNotExists inserts Agent records whose IDs are absent and returns the inserted IDs.

func (*ClickHouseLogStore) BatchCreateIfNotExists added in v1.4.3 

func (s *ClickHouseLogStore) BatchCreateIfNotExists(ctx context.Context, entries []*Log) error

BatchCreateIfNotExists inserts the log entries whose ids are not already present. See CreateIfNotExists.

func (*ClickHouseLogStore) BatchCreateMCPToolLogsIfNotExists added in v1.4.3 

func (s *ClickHouseLogStore) BatchCreateMCPToolLogsIfNotExists(ctx context.Context, entries []*MCPToolLog) error

BatchCreateMCPToolLogsIfNotExists inserts the MCP tool log entries whose ids are not already present. See CreateIfNotExists.

func (*ClickHouseLogStore) BatchCreateRelayLogsIfNotExists added in v1.11.0 

func (s *ClickHouseLogStore) BatchCreateRelayLogsIfNotExists(ctx context.Context, entries []*RelayLog) ([]string, error)

BatchCreateRelayLogsIfNotExists inserts Relay Logs rows whose IDs are absent and returns the inserted IDs; ClickHouse has no ON CONFLICT, so absent IDs are found first.

func (*ClickHouseLogStore) BatchUpdate added in v1.9.0 

func (s *ClickHouseLogStore) BatchUpdate(ctx context.Context, entries []*Log) error

BatchUpdate overlays each entry's non-zero fields onto its existing row via read-modify-write and re-insert, one chunk at a time under the RMW locks. It overrides the embedded RDB implementation, whose GORM UPDATE would be a heavyweight mutation here and would bypass rmwLocks. Several entries for one id are applied in batch order, as the RDB store applies them. Missing ids are skipped, matching the RDB semantics. content_summary is left as the row has it: the entry's own serialization would regenerate it from output only.

func (*ClickHouseLogStore) BulkUpdateCost added in v1.4.3 

func (s *ClickHouseLogStore) BulkUpdateCost(ctx context.Context, updates map[string]CostUpdate) error

BulkUpdateCost backfills costs by reading each chunk of rows, patching cost, and re-inserting. Reading the full row is required because the re-insert must reproduce every column (the ReplacingMergeTree dedup key includes timestamp).

func (*ClickHouseLogStore) CreateIfNotExists added in v1.4.3 

func (s *ClickHouseLogStore) CreateIfNotExists(ctx context.Context, entry *Log) error

CreateIfNotExists inserts a log entry only when no row with the same id exists (see the semantics note above).

func (*ClickHouseLogStore) DeleteAgentLogs added in v1.9.0 

func (s *ClickHouseLogStore) DeleteAgentLogs(ctx context.Context, ids []string) error

DeleteAgentLogs deletes the identified Agent log rows together with every row sharing their request IDs, mirroring the SQL stores so a deleted operation's correlated stream events do not survive as orphans.

func (*ClickHouseLogStore) DeleteExpiredAsyncJobs added in v1.4.3 

func (s *ClickHouseLogStore) DeleteExpiredAsyncJobs(ctx context.Context) (int64, error)

DeleteExpiredAsyncJobs deletes async jobs whose expiry has passed with one lightweight delete; the count is selected first because mutations never report rows affected.

func (*ClickHouseLogStore) DeleteExpiredWebhookDeliveries added in v1.5.3 

func (s *ClickHouseLogStore) DeleteExpiredWebhookDeliveries(ctx context.Context) (int64, error)

DeleteExpiredWebhookDeliveries deletes webhook delivery history whose expiry has passed. See DeleteExpiredAsyncJobs.

func (*ClickHouseLogStore) DeleteLog added in v1.7.0 

func (s *ClickHouseLogStore) DeleteLog(ctx context.Context, id string) error

DeleteLog deletes a log entry by id with a lightweight delete, and with it what Warp's topic tables hold about it. There is no transaction to undo the log delete with, so a topic cleanup failure after it is ErrPartialLogDelete.

func (*ClickHouseLogStore) DeleteLogs added in v1.7.0 

func (s *ClickHouseLogStore) DeleteLogs(ctx context.Context, ids []string) error

DeleteLogs deletes multiple log entries by id with one lightweight delete, and with them what Warp's topic tables hold about them. See DeleteLog for ErrPartialLogDelete.

func (*ClickHouseLogStore) DeleteLogsBatch added in v1.4.3 

func (s *ClickHouseLogStore) DeleteLogsBatch(ctx context.Context, cutoff time.Time, _ int) (int64, error)

DeleteLogsBatch deletes every log older than cutoff with one lightweight delete per call. batchSize is ignored: a ClickHouse mutation costs the same per affected part whether it matches 100 rows or all of them, so batching by id would rewrite the same part once per batch (#7098). The returned count is selected before the delete because mutations never report rows affected. The LogsCleaner loop stops after this call because the count differs from batchSize; when it happens to equal batchSize the next call finds nothing and returns 0 without issuing a mutation.

func (*ClickHouseLogStore) DeleteMCPToolLogs added in v1.7.0 

func (s *ClickHouseLogStore) DeleteMCPToolLogs(ctx context.Context, ids []string) error

DeleteMCPToolLogs deletes multiple MCP tool log entries by id with one lightweight delete.

func (*ClickHouseLogStore) DeleteRelayLogs added in v1.11.0 

func (s *ClickHouseLogStore) DeleteRelayLogs(ctx context.Context, ids []string) error

func (*ClickHouseLogStore) DeleteRelayLogsBatch added in v1.11.0 

func (s *ClickHouseLogStore) DeleteRelayLogsBatch(ctx context.Context, cutoff time.Time, _ int) (int64, error)

DeleteRelayLogs deletes the identified rows with a lightweight delete. DeleteRelayLogsBatch removes Relay Logs rows older than cutoff, as DeleteLogsBatch does for the request logs, so the retention cleaner prunes relay rows on ClickHouse too.

func (*ClickHouseLogStore) DeleteStaleAsyncJobs added in v1.4.3 

func (s *ClickHouseLogStore) DeleteStaleAsyncJobs(ctx context.Context, staleSince time.Time) (int64, error)

DeleteStaleAsyncJobs deletes processing jobs created before staleSince. See DeleteExpiredAsyncJobs.

func (*ClickHouseLogStore) DeleteUserAgentMapping added in v1.11.0 

func (s *ClickHouseLogStore) DeleteUserAgentMapping(ctx context.Context, id string) error

DeleteUserAgentMapping deletes a mapping with a lightweight delete. Mutations never report rows affected, so existence is checked first.

func (*ClickHouseLogStore) DeleteWarpConversation added in v1.9.0 

func (s *ClickHouseLogStore) DeleteWarpConversation(ctx context.Context, ownerID, id string) error

DeleteWarpConversation removes a thread and its messages.

Messages go first here, the opposite of the bulk sweeps below, because there is no staleness predicate that could spare the thread: it is going either way, so the risk to avoid is the transcript outliving it. Orphaned messages are unreachable copies of the exact content somebody asked to be rid of.

func (*ClickHouseLogStore) DeleteWarpConversationIfEmpty added in v1.9.0 

func (s *ClickHouseLogStore) DeleteWarpConversationIfEmpty(ctx context.Context, ownerID, id string) (bool, error)

DeleteWarpConversationIfEmpty removes a thread only if it has no messages.

Held under the same locks AppendWarpMessages holds for its whole write - the owner's distributed lock and this process's RMW lock - so an append on any instance either finishes first and the check sees its messages, or starts after and finds the thread gone. Without a locker only the RMW lock applies: an append on another instance that loses the race sees the thread missing on its re-check, removes its own messages and returns ErrWarpConversationNotFound.

func (*ClickHouseLogStore) DeleteWarpConversationsOlderThan added in v1.9.0 

func (s *ClickHouseLogStore) DeleteWarpConversationsOlderThan(ctx context.Context, cutoff time.Time) (int64, error)

DeleteWarpConversationsOlderThan drops threads last touched before the cutoff, across all owners, and returns how many it removed.

One bounded batch per call, like the SQL implementation, so a caller clearing a backlog loops until a call returns zero. See the SQL implementation for why this runs off Warp's own retention setting rather than the table TTL every other table here uses.

func (*ClickHouseLogStore) DeleteWarpTopicAssignments added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopicAssignments(ctx context.Context, logIDs []string) error

DeleteWarpTopicAssignments removes the given requests' assignments with lightweight deletes.

func (*ClickHouseLogStore) DeleteWarpTopicAssignmentsBatch added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopicAssignmentsBatch(ctx context.Context, cutoff time.Time, _ int) (int64, error)

DeleteWarpTopicAssignmentsBatch deletes every assignment whose log was created before cutoff with one lightweight delete; see DeleteLogsBatch for why batchSize is ignored.

func (*ClickHouseLogStore) DeleteWarpTopicAssignmentsUnmatchedSince added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopicAssignmentsUnmatchedSince(ctx context.Context, since time.Time) error

DeleteWarpTopicAssignmentsUnmatchedSince removes the rows filed under no topic at or after since, with one lightweight delete.

func (*ClickHouseLogStore) DeleteWarpTopicUnmatched added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopicUnmatched(ctx context.Context, logIDs []string) error

DeleteWarpTopicUnmatched removes requests from the pool.

func (*ClickHouseLogStore) DeleteWarpTopicUnmatchedBatch added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopicUnmatchedBatch(ctx context.Context, cutoff time.Time, _ int) (int64, error)

DeleteWarpTopicUnmatchedBatch deletes every pool row whose log was created before cutoff with one lightweight delete.

func (*ClickHouseLogStore) DeleteWarpTopicUnmatchedExcept added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopicUnmatchedExcept(ctx context.Context, embeddingSignature string) (int64, error)

DeleteWarpTopicUnmatchedExcept drops the pool rows of every other embedding model with one lightweight delete.

func (*ClickHouseLogStore) DeleteWarpTopics added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpTopics(ctx context.Context, ids []string) error

DeleteWarpTopics removes topic and theme rows with lightweight deletes.

func (*ClickHouseLogStore) DeleteWarpVectorDeletes added in v1.11.0 

func (s *ClickHouseLogStore) DeleteWarpVectorDeletes(ctx context.Context, logIDs []string) error

DeleteWarpVectorDeletes removes the rows of logs whose vector is gone.

func (*ClickHouseLogStore) EnsureClickHouseTable added in v1.5.3 

func (s *ClickHouseLogStore) EnsureClickHouseTable(ctx context.Context, model any, table, partitionBy, orderBy, ttl string, skipIndexes []string) error

EnsureClickHouseTable creates an extension-owned table and reconciles model columns while preserving the configured cluster and replication settings.

func (*ClickHouseLogStore) FindAgentLogsForDeletion added in v1.9.0 

func (s *ClickHouseLogStore) FindAgentLogsForDeletion(ctx context.Context, ids []string) ([]*AgentLog, error)

func (*ClickHouseLogStore) Flush added in v1.7.0 

func (s *ClickHouseLogStore) Flush(ctx context.Context, since time.Time) error

Flush removes stale processing log rows. Overridden so the minute sweep is a probe plus at most one lightweight delete. The error text matches the SQL stores so the logging plugin's warnings are unchanged.

func (*ClickHouseLogStore) FlushAgentLogs added in v1.10.0 

func (s *ClickHouseLogStore) FlushAgentLogs(ctx context.Context, since time.Time) error

FlushAgentLogs removes stale processing A2A log rows. See Flush.

func (*ClickHouseLogStore) FlushMCPToolLogs added in v1.7.0 

func (s *ClickHouseLogStore) FlushMCPToolLogs(ctx context.Context, since time.Time) error

FlushMCPToolLogs removes stale processing MCP tool log rows. See Flush.

func (*ClickHouseLogStore) PruneWarpConversations added in v1.9.0 

func (s *ClickHouseLogStore) PruneWarpConversations(ctx context.Context, ownerID string, keep int) (int64, error)

PruneWarpConversations drops an owner's oldest threads beyond keep.

func (*ClickHouseLogStore) PruneWarpTopicUnmatched added in v1.11.0 

func (s *ClickHouseLogStore) PruneWarpTopicUnmatched(ctx context.Context, olderThan time.Time, keep int) (int64, error)

PruneWarpTopicUnmatched bounds the pool by age and by count, with one lightweight delete for both.

func (*ClickHouseLogStore) ReconcileAgentCorrelation added in v1.9.0 

func (s *ClickHouseLogStore) ReconcileAgentCorrelation(ctx context.Context, entries []*AgentLog) error

ReconcileAgentCorrelation uses ClickHouse's existing read-modify-reinsert update model. Reinserted rows keep their immutable key and receive a newer version.

func (*ClickHouseLogStore) ReconcileClickHouseTTL added in v1.9.0 

func (s *ClickHouseLogStore) ReconcileClickHouseTTL(ctx context.Context, table, ttl string) error

ReconcileClickHouseTTL sets an extension-owned table's TTL to ttl when the table was created with a different one, because CREATE TABLE IF NOT EXISTS never changes an existing table. ttl must be written the way ClickHouse stores it in system.tables.engine_full (for example `+ toIntervalHour(24)`), or the metadata-only ALTER is repeated on every call.

func (*ClickHouseLogStore) SetDistributedLocker added in v1.9.0 

func (s *ClickHouseLogStore) SetDistributedLocker(locker DistributedLocker)

SetDistributedLocker gives the Warp history and user agent mapping writes a lock every instance sharing this ClickHouse honours.

func (*ClickHouseLogStore) Update added in v1.4.3 

func (s *ClickHouseLogStore) Update(ctx context.Context, id string, entry any) error

Update applies an update (a column->value map, or a *Log/Log whose non-zero fields are written) to the log row by re-inserting a patched copy.

func (*ClickHouseLogStore) UpdateAgentLog added in v1.9.0 

func (s *ClickHouseLogStore) UpdateAgentLog(ctx context.Context, id string, entry any) error

UpdateAgentLog applies an update to an Agent log row via read-modify-write.

func (*ClickHouseLogStore) UpdateAsyncJob added in v1.4.3 

func (s *ClickHouseLogStore) UpdateAsyncJob(ctx context.Context, id string, updates map[string]interface{}) error

UpdateAsyncJob applies a column->value map to an async job row via read-modify-write.

func (*ClickHouseLogStore) UpdateMCPToolLog added in v1.4.3 

func (s *ClickHouseLogStore) UpdateMCPToolLog(ctx context.Context, id string, entry any) error

UpdateMCPToolLog applies an update to an MCP tool log row via read-modify-write.

func (*ClickHouseLogStore) UpdateRelayLog added in v1.11.1 

func (s *ClickHouseLogStore) UpdateRelayLog(ctx context.Context, id string, updates map[string]any) error

UpdateRelayLog applies an update to a Relay Logs row via read-modify-write.

func (*ClickHouseLogStore) UpdateUserAgentMapping added in v1.11.0 

func (s *ClickHouseLogStore) UpdateUserAgentMapping(ctx context.Context, id string, mapping *UserAgentMapping) error

UpdateUserAgentMapping re-inserts a patched copy of the mapping, since ReplacingMergeTree has no in-place UPDATE. The shared lock keeps a delete on another instance from landing between the read and the re-insert, which would bring the deleted mapping back.

func (*ClickHouseLogStore) UpsertWarpTopicAssignments added in v1.11.0 

func (s *ClickHouseLogStore) UpsertWarpTopicAssignments(ctx context.Context, assignments []WarpTopicAssignment) error

UpsertWarpTopicAssignments writes one row per request. A request written again replaces its earlier row because (timestamp, log_id) is unchanged.

func (*ClickHouseLogStore) UpsertWarpTopics added in v1.11.0 

func (s *ClickHouseLogStore) UpsertWarpTopics(ctx context.Context, topics []WarpTopic) error

UpsertWarpTopics writes topics whole, replacing any row with the same ID.

type Config 

type Config struct {
	Enabled       bool                `json:"enabled"`
	Type          LogStoreType        `json:"type"`
	RetentionDays int                 `json:"retention_days"`
	Config        any                 `json:"config"`
	Writer        *WriterConfig       `json:"writer,omitempty"`
	ObjectStorage *objectstore.Config `json:"object_storage,omitempty"`
	// ObjectStorageExcludeFields lists payload field names (DB column names) that
	// should NOT be offloaded to object storage and instead remain in the database.
	ObjectStorageExcludeFields []string `json:"object_storage_exclude_fields,omitempty"`
	// ObjectStorageExcludeRequestTypes lists request types (log object_type values) whose logs stay fully in the database and are never offloaded.
	ObjectStorageExcludeRequestTypes []string `json:"object_storage_exclude_request_types,omitempty"`
}

Config represents the configuration for the logs store.

func (*Config) UnmarshalJSON 

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON is the custom unmarshal logic for Config

type CostHistogramBucket added in v1.2.13 

type CostHistogramBucket struct {
	Timestamp time.Time          `json:"timestamp"`
	TotalCost float64            `json:"total_cost"`
	ByModel   map[string]float64 `json:"by_model"`
}

CostHistogramBucket represents a single time bucket for cost data

type CostHistogramResult added in v1.2.13 

type CostHistogramResult struct {
	Buckets           []CostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                 `json:"bucket_size_seconds"`
	Models            []string              `json:"models"`
}

CostHistogramResult represents the cost histogram query result

type CostUpdate added in v1.6.0 

type CostUpdate struct {
	Total      float64
	Input      float64
	Output     float64
	Additional float64
}

CostUpdate is the repriced cost for a single log row, applied in bulk by BulkUpdateCost. It carries the per-category split alongside the total so a reprice keeps the denormalized input/output/additional cost columns in sync with the cost column (they otherwise go stale on recompute). Input + Output + Additional == Total, mirroring schemas.BifrostCost.

func CostUpdateFromBreakdown added in v1.6.0 

func CostUpdateFromBreakdown(bd *schemas.BifrostCost) CostUpdate

CostUpdateFromBreakdown builds a CostUpdate from a cost breakdown, falling back to attributing an unsplit total to the input side (mirrors the SerializeFields reconciliation for opaque provider totals).

type DashboardMCP added in v1.3.22 

type DashboardMCP struct {
	Volume   *MCPHistogramResult     `json:"volume"`    // Tool call volume over time
	Cost     *MCPCostHistogramResult `json:"cost"`      // MCP cost over time
	TopTools *MCPTopToolsResult      `json:"top_tools"` // Top tools by call count
}

DashboardMCP holds the MCP usage tab metrics.

type DashboardMeta added in v1.3.22 

type DashboardMeta struct {
	GeneratedAt       time.Time  `json:"generated_at"`         // UTC time the response was assembled
	BucketSizeSeconds int64      `json:"bucket_size_seconds"`  // Width of every histogram bucket, derived from the time range
	StartTime         *time.Time `json:"start_time,omitempty"` // Resolved start of the queried range (from start_time/end_time or period)
	EndTime           *time.Time `json:"end_time,omitempty"`   // Resolved end of the queried range
}

DashboardMeta describes the parameters the dashboard data was computed with, so consumers can interpret the buckets and rankings without re-deriving them.

type DashboardModelRankings added in v1.3.22 

type DashboardModelRankings struct {
	Rankings  *ModelRankingResult   `json:"rankings"`  // Ranked table with trends
	Histogram *ModelHistogramResult `json:"histogram"` // Backs the "Top Models" stacked bar chart
}

DashboardModelRankings holds the Model Rankings tab data.

type DashboardOverview added in v1.3.22 

type DashboardOverview struct {
	Stats    *SearchStats            `json:"stats"`    // Totals + success/cache rates
	Requests *HistogramResult        `json:"requests"` // Request volume over time
	Tokens   *TokenHistogramResult   `json:"tokens"`   // Token usage over time
	Cost     *CostHistogramResult    `json:"cost"`     // Cost over time, broken down by model
	Models   *ModelHistogramResult   `json:"models"`   // Per-model usage over time
	Latency  *LatencyHistogramResult `json:"latency"`  // Latency percentiles over time
	// Throughput holds tokens/sec over time (aggregate rate per bucket).
	Throughput *ThroughputHistogramResult `json:"throughput"`
}

DashboardOverview holds the Overview tab metrics.

type DashboardProviderUsage added in v1.3.22 

type DashboardProviderUsage struct {
	Cost    *ProviderCostHistogramResult    `json:"cost"`
	Tokens  *ProviderTokenHistogramResult   `json:"tokens"`
	Latency *ProviderLatencyHistogramResult `json:"latency"`
	// Throughput holds per-provider tokens/sec over time.
	Throughput *ProviderThroughputHistogramResult `json:"throughput"`
}

DashboardProviderUsage holds the Provider Usage tab metrics.

type DashboardResult added in v1.3.22 

type DashboardResult struct {
	Meta              DashboardMeta                      `json:"meta"`
	Overview          DashboardOverview                  `json:"overview"`
	ProviderUsage     DashboardProviderUsage             `json:"provider_usage"`
	ModelRankings     DashboardModelRankings             `json:"model_rankings"`
	DimensionRankings map[string]*DimensionRankingResult `json:"dimension_rankings"`
	MCP               DashboardMCP                       `json:"mcp"`
}

DashboardResult is the full consolidated payload for GET /api/logs/dashboard. DimensionRankings is keyed by RankingDimension ("team", "user", "virtual_key", "customer", "business_unit"); each value is that dimension's ranking table.

type DimensionCostHistogramBucket added in v1.3.1 

type DimensionCostHistogramBucket struct {
	Timestamp   time.Time          `json:"timestamp"`
	TotalCost   float64            `json:"total_cost"`
	ByDimension map[string]float64 `json:"by_dimension"`
}

DimensionCostHistogramBucket represents a single time bucket for dimension-grouped cost data

type DimensionCostHistogramResult added in v1.3.1 

type DimensionCostHistogramResult struct {
	Buckets           []DimensionCostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                          `json:"bucket_size_seconds"`
	Dimension         HistogramDimension             `json:"dimension"`
	DimensionValues   []string                       `json:"dimension_values"`
}

DimensionCostHistogramResult represents the dimension cost histogram query result

type DimensionLatencyHistogramBucket added in v1.3.1 

type DimensionLatencyHistogramBucket struct {
	Timestamp   time.Time                        `json:"timestamp"`
	ByDimension map[string]DimensionLatencyStats `json:"by_dimension"`
}

DimensionLatencyHistogramBucket represents a single time bucket for dimension-grouped latency data

type DimensionLatencyHistogramResult added in v1.3.1 

type DimensionLatencyHistogramResult struct {
	Buckets           []DimensionLatencyHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                             `json:"bucket_size_seconds"`
	Dimension         HistogramDimension                `json:"dimension"`
	DimensionValues   []string                          `json:"dimension_values"`
}

DimensionLatencyHistogramResult represents the dimension latency histogram query result

type DimensionLatencyStats added in v1.3.1 

type DimensionLatencyStats struct {
	AvgLatency    float64 `json:"avg_latency"`
	P90Latency    float64 `json:"p90_latency"`
	P95Latency    float64 `json:"p95_latency"`
	P99Latency    float64 `json:"p99_latency"`
	TotalRequests int64   `json:"total_requests"`
}

DimensionLatencyStats represents latency statistics for a single dimension value

type DimensionModelUsageEntry added in v1.11.0 

type DimensionModelUsageEntry struct {
	ID            string  `json:"id"`
	Model         string  `json:"model"`
	Provider      string  `json:"provider"`
	TotalRequests int64   `json:"total_requests"`
	TotalCost     float64 `json:"total_cost"`
}

DimensionModelUsageEntry is one (entity, model, provider) group's usage on a rollup dimension inside the filter window.

type DimensionRankingEntry added in v1.3.14 

type DimensionRankingEntry struct {
	ID            string  `json:"id"`
	Name          string  `json:"name,omitempty"`
	TotalRequests int64   `json:"total_requests"`
	TotalTokens   int64   `json:"total_tokens"`
	TotalCost     float64 `json:"total_cost"`
}

type DimensionRankingResult added in v1.3.14 

type DimensionRankingResult struct {
	Rankings  []DimensionRankingWithTrend `json:"rankings"`
	Dimension RankingDimension            `json:"dimension"`
	// TotalActualRequests / TotalAttributedRequests are set for every rollup
	// dimension (team / business unit / customer / user / virtual key), and both
	// include the "Unassigned" bucket that owner-less traffic falls into and the
	// "Other" bucket holding traffic whose entity the caller may not be shown.
	//
	// TotalActualRequests is the real number of requests in the window.
	// TotalAttributedRequests is the sum of every ranking row. For team /
	// customer / business unit a request is credited to every entity it carries
	// (the enterprise user/AP path records the full hierarchy), so attributed
	// can exceed actual and the rankings are NOT an additive split of org
	// traffic. User and virtual key have a single owner per request, so for them
	// the two counts are equal.
	TotalActualRequests     int64 `json:"total_actual_requests,omitempty"`
	TotalAttributedRequests int64 `json:"total_attributed_requests,omitempty"`
}

type DimensionRankingTrend added in v1.3.14 

type DimensionRankingTrend struct {
	HasPreviousPeriod bool     `json:"has_previous_period"`
	RequestsTrend     float64  `json:"requests_trend"`
	TokensTrend       *float64 `json:"tokens_trend"`
	CostTrend         *float64 `json:"cost_trend"`
}

DimensionRankingTrend follows ModelRankingTrend's nil convention for TokensTrend and CostTrend.

type DimensionRankingWithTrend added in v1.3.14 

type DimensionRankingWithTrend struct {
	DimensionRankingEntry
	Trend DimensionRankingTrend `json:"trend"`
}

type DimensionTokenHistogramBucket added in v1.3.1 

type DimensionTokenHistogramBucket struct {
	Timestamp   time.Time                      `json:"timestamp"`
	ByDimension map[string]DimensionTokenStats `json:"by_dimension"`
}

DimensionTokenHistogramBucket represents a single time bucket for dimension-grouped token data

type DimensionTokenHistogramResult added in v1.3.1 

type DimensionTokenHistogramResult struct {
	Buckets           []DimensionTokenHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                           `json:"bucket_size_seconds"`
	Dimension         HistogramDimension              `json:"dimension"`
	DimensionValues   []string                        `json:"dimension_values"`
}

DimensionTokenHistogramResult represents the dimension token histogram query result

type DimensionTokenStats added in v1.3.1 

type DimensionTokenStats struct {
	PromptTokens     int64 `json:"prompt_tokens"`
	CompletionTokens int64 `json:"completion_tokens"`
	TotalTokens      int64 `json:"total_tokens"`
}

DimensionTokenStats represents token statistics for a single dimension value

type DimensionUsageEntry added in v1.11.0 

type DimensionUsageEntry struct {
	ID            string                `json:"id"`
	TotalRequests int64                 `json:"total_requests"`
	TotalTokens   int64                 `json:"total_tokens"`
	TotalCost     float64               `json:"total_cost"`
	Trend         DimensionRankingTrend `json:"trend"`
}

DimensionUsageEntry is one entity's usage on a rollup dimension inside the filter window. Trend compares it with the equally long window before, and is filled only when GetDimensionUsage was asked to compare.

type DistributedLocker added in v1.9.0 

type DistributedLocker interface {
	// Acquire blocks until key is held or ctx ends. It returns a context to run
	// the critical section on, cancelled if the lock is lost while held, and the
	// release.
	Acquire(ctx context.Context, key string) (held context.Context, release func(), err error)
}

DistributedLocker is mutual exclusion shared by every Bifrost instance that uses the same stores. configstore.DistributedLockManager satisfies it; it is declared here, not imported, because configstore already imports logstore.

type GovernanceStore added in v1.2.22 

type GovernanceStore interface {
	GetVirtualKey(ctx context.Context, vkValue string) (*configstoreTables.TableVirtualKey, bool)
}

GovernanceStore is an interface that provides access to the governance store.

type HistogramBucket added in v1.2.13 

type HistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	Count     int64     `json:"count"`
	Success   int64     `json:"success"`
	Error     int64     `json:"error"`
	Cancelled int64     `json:"cancelled"`
}

HistogramBucket represents a single time bucket in the histogram

type HistogramDimension added in v1.3.1 

type HistogramDimension string

HistogramDimension represents a column that can be used as a grouping dimension in histograms 

const (
	DimensionProvider     HistogramDimension = "provider"
	DimensionTeam         HistogramDimension = "team_id"
	DimensionCustomer     HistogramDimension = "customer_id"
	DimensionUser         HistogramDimension = "user_id"
	DimensionBusinessUnit HistogramDimension = "business_unit_id"
	DimensionProject      HistogramDimension = "project_id"
	DimensionApp          HistogramDimension = "app"
	DimensionUserAgent    HistogramDimension = "user_agent"
)

type HistogramResult added in v1.2.13 

type HistogramResult struct {
	Buckets           []HistogramBucket `json:"buckets"`
	BucketSizeSeconds int64             `json:"bucket_size_seconds"`
}

HistogramResult represents the histogram query result

type HybridLogStore added in v1.3.2 

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

HybridLogStore wraps an existing LogStore and offloads large payload fields to object storage while keeping a lightweight index in the DB.

Method routing:

  • Delegated directly (40+ methods): all analytics, search, histogram, ranking, distinct, MCP, async job methods
  • Intercepted: Create, CreateIfNotExists, BatchCreateIfNotExists, FindByID, Update, DeleteLog, DeleteLogs, DeleteLogsBatch, Close

func (*HybridLogStore) AddWarpTopicUnmatched added in v1.11.0 

func (h *HybridLogStore) AddWarpTopicUnmatched(ctx context.Context, rows []WarpTopicUnmatched) error

AddWarpTopicUnmatched puts requests in the unmatched pool.

func (*HybridLogStore) AddWarpVectorDeletes added in v1.11.0 

func (h *HybridLogStore) AddWarpVectorDeletes(ctx context.Context, rows []WarpVectorDelete) error

AddWarpVectorDeletes records deleted logs whose vector delete failed.

func (*HybridLogStore) AppendWarpMessages added in v1.9.0 

func (h *HybridLogStore) AppendWarpMessages(ctx context.Context, ownerID, conversationID string, messages []WarpMessage) error

AppendWarpMessages adds turns to a thread and bumps its updated time.

func (*HybridLogStore) BatchCreateAgentLogsIfNotExists added in v1.9.0 

func (h *HybridLogStore) BatchCreateAgentLogsIfNotExists(ctx context.Context, entries []*AgentLog) ([]string, error)

func (*HybridLogStore) BatchCreateIfNotExists added in v1.3.2 

func (h *HybridLogStore) BatchCreateIfNotExists(ctx context.Context, entries []*Log) error

BatchCreateIfNotExists inserts many lightweight DB rows in a single inner call, then enqueues one object-storage upload per inserted entry. Nil entries are skipped. On DB failure no uploads are enqueued.

func (*HybridLogStore) BatchCreateMCPToolLogsIfNotExists added in v1.3.9 

func (h *HybridLogStore) BatchCreateMCPToolLogsIfNotExists(ctx context.Context, entries []*MCPToolLog) error

BatchCreateMCPToolLogsIfNotExists creates MCP tool logs in the DB and enqueues them for offload to object storage, if they do not already exist.

func (*HybridLogStore) BatchCreateRelayLogsIfNotExists added in v1.11.0 

func (h *HybridLogStore) BatchCreateRelayLogsIfNotExists(ctx context.Context, entries []*RelayLog) ([]string, error)

BatchCreateRelayLogsIfNotExists inserts the rows with their bodies cut to a preview and uploads the full bodies of the rows it inserted, so a duplicate never overwrites an object.

func (*HybridLogStore) BatchUpdate added in v1.9.0 

func (h *HybridLogStore) BatchUpdate(ctx context.Context, entries []*Log) error

BatchUpdate reconciles output fields onto existing rows the same way an insert would have placed them: the DB row gets the scalar columns, and the payload goes to object storage. The current row is read once per id (the update carries no timestamp, which the object key needs), every entry for that id is applied to the DB in batch order, and their non-empty payload fields are folded, in that same order, into ONE merge upload that the upload worker lays over the row's stored object (see mergeIntoStoredObject). The DB row stays content-free. Hidden rows are handled identically, which is what keeps a retained response from being lost: the hidden DB row must never hold content, so the object is the only place the late output can go. Rows whose request type is excluded from offloading pass through unchanged, and rows that do not exist are skipped, as in the inner store.

func (*HybridLogStore) BucketWarpTopicAssignments added in v1.11.0 

func (h *HybridLogStore) BucketWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter, bucketSizeSeconds int64) ([]WarpTopicBucket, error)

BucketWarpTopicAssignments adds up the selected assignments per topic and per bucket.

func (*HybridLogStore) BulkBackfillBillingPayloads added in v1.5.5 

func (h *HybridLogStore) BulkBackfillBillingPayloads(ctx context.Context, updates map[string]BillingPayloadBackfill) error

BulkBackfillBillingPayloads delegates to the inner store.

Safe to write these columns even though the offload path blanked them: Update is a plain pass-through here (it does not re-run prepareDBEntry), so nothing re-strips them. The object keeps its own copy, so this is a cache, not a move.

func (*HybridLogStore) BulkUpdateCost added in v1.3.2 

func (h *HybridLogStore) BulkUpdateCost(ctx context.Context, updates map[string]CostUpdate) error

BulkUpdateCost delegates to the inner store and updates the cost columns (total + input/output/additional split) for each (logID -> CostUpdate) pair in a single round trip.

func (*HybridLogStore) Close added in v1.3.2 

func (h *HybridLogStore) Close(ctx context.Context) error

Close shuts the store down cleanly: marks the store closed (so further enqueues are dropped), closes the upload queue, waits for workers to drain any in-flight uploads, then closes the object store and the inner store. If ctx is cancelled before workers drain, the cancellation is logged but Close still waits for workers to exit to avoid closing dependencies mid-flight.

func (*HybridLogStore) CountWarpMessages added in v1.9.0 

func (h *HybridLogStore) CountWarpMessages(ctx context.Context, conversationIDs []string) (map[string]int, error)

CountWarpMessages returns message counts for the given threads in one query.

func (*HybridLogStore) CountWarpTopicUnmatched added in v1.11.0 

func (h *HybridLogStore) CountWarpTopicUnmatched(ctx context.Context, embeddingSignature string) (int64, error)

CountWarpTopicUnmatched reports the pool's size for one embedding model.

func (*HybridLogStore) Create added in v1.3.2 

func (h *HybridLogStore) Create(ctx context.Context, entry *Log) error

func (*HybridLogStore) CreateAsyncJob added in v1.3.2 

func (h *HybridLogStore) CreateAsyncJob(ctx context.Context, job *AsyncJob) error

CreateAsyncJob creates a new async job.

func (*HybridLogStore) CreateIfNotExists added in v1.3.2 

func (h *HybridLogStore) CreateIfNotExists(ctx context.Context, entry *Log) error

CreateIfNotExists writes the lightweight DB row only when no row with the same ID exists, then offloads the full payload to object storage on insert. Same payload-stripping and shallow-copy semantics as Create.

func (*HybridLogStore) CreateMCPToolLog added in v1.3.2 

func (h *HybridLogStore) CreateMCPToolLog(ctx context.Context, entry *MCPToolLog) error

CreateMCPToolLog creates a new MCP tool log in the DB and enqueues it for offload to object storage.

func (*HybridLogStore) CreateUserAgentMapping added in v1.5.0 

func (h *HybridLogStore) CreateUserAgentMapping(ctx context.Context, mapping *UserAgentMapping) error

func (*HybridLogStore) CreateWarpConversation added in v1.9.0 

func (h *HybridLogStore) CreateWarpConversation(ctx context.Context, conversation *WarpConversation) error

CreateWarpConversation starts a thread.

func (*HybridLogStore) CreateWebhookDelivery added in v1.5.3 

func (h *HybridLogStore) CreateWebhookDelivery(ctx context.Context, delivery *WebhookDelivery) error

CreateWebhookDelivery appends one webhook delivery attempt record.

func (*HybridLogStore) DeleteAgentLogs added in v1.9.0 

func (h *HybridLogStore) DeleteAgentLogs(ctx context.Context, ids []string) error

DeleteAgentLogs deletes the identified Agent log rows, correlated stream-event rows, and every offloaded object belonging to those rows.

func (*HybridLogStore) DeleteExpiredAsyncJobs added in v1.3.2 

func (h *HybridLogStore) DeleteExpiredAsyncJobs(ctx context.Context) (int64, error)

DeleteExpiredAsyncJobs deletes async jobs that have not been updated since the given time.

func (*HybridLogStore) DeleteExpiredWebhookDeliveries added in v1.5.3 

func (h *HybridLogStore) DeleteExpiredWebhookDeliveries(ctx context.Context) (int64, error)

DeleteExpiredWebhookDeliveries deletes delivery history whose expiry has passed.

func (*HybridLogStore) DeleteLog added in v1.3.2 

func (h *HybridLogStore) DeleteLog(ctx context.Context, id string) error

DeleteLog removes a single log row from the DB and, when HasObject is true, also deletes the corresponding payload from object storage. Object-store delete failures are logged but do not fail the operation, since the DB row (the source of truth for visibility) is already gone.

func (*HybridLogStore) DeleteLogs added in v1.3.2 

func (h *HybridLogStore) DeleteLogs(ctx context.Context, ids []string) error

DeleteLogs removes many log rows from the DB and batches a single DeleteBatch call against object storage for any rows that had HasObject set. Keys are collected before the DB delete so we can still identify object-store entries to clean up.

func (*HybridLogStore) DeleteLogsBatch added in v1.3.2 

func (h *HybridLogStore) DeleteLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteLogsBatch deletes old DB rows older than cutoff in batches of batchSize. Object-store entries are intentionally NOT deleted here: the expectation is that the bucket has a lifecycle policy configured to expire objects on the same schedule, which is far cheaper than per-row DELETEs.

func (*HybridLogStore) DeleteMCPToolLogs added in v1.3.2 

func (h *HybridLogStore) DeleteMCPToolLogs(ctx context.Context, ids []string) error

DeleteMCPToolLogs deletes MCP tool logs with the given IDs, including any associated object storage objects.

func (*HybridLogStore) DeleteMCPToolLogsBatch added in v1.9.0 

func (h *HybridLogStore) DeleteMCPToolLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteMCPToolLogsBatch deletes old MCP tool log rows in batches. Like DeleteLogsBatch, object-store entries are left to the bucket lifecycle policy.

func (*HybridLogStore) DeleteRelayLogs added in v1.11.0 

func (h *HybridLogStore) DeleteRelayLogs(ctx context.Context, ids []string) error

DeleteRelayLogs deletes the identified rows, the job rows that settle them, and every offloaded object belonging to those rows.

func (*HybridLogStore) DeleteRelayLogsBatch added in v1.11.0 

func (h *HybridLogStore) DeleteRelayLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

func (*HybridLogStore) DeleteStaleAsyncJobs added in v1.3.2 

func (h *HybridLogStore) DeleteStaleAsyncJobs(ctx context.Context, staleSince time.Time) (int64, error)

DeleteStaleAsyncJobs deletes async jobs that have not been updated since the given time.

func (*HybridLogStore) DeleteUserAgentMapping added in v1.5.0 

func (h *HybridLogStore) DeleteUserAgentMapping(ctx context.Context, id string) error

func (*HybridLogStore) DeleteWarpConversation added in v1.9.0 

func (h *HybridLogStore) DeleteWarpConversation(ctx context.Context, ownerID, id string) error

DeleteWarpConversation removes a thread and its messages.

func (*HybridLogStore) DeleteWarpConversationIfEmpty added in v1.9.0 

func (h *HybridLogStore) DeleteWarpConversationIfEmpty(ctx context.Context, ownerID, id string) (bool, error)

DeleteWarpConversationIfEmpty removes a thread only if it has no messages.

func (*HybridLogStore) DeleteWarpConversationsOlderThan added in v1.9.0 

func (h *HybridLogStore) DeleteWarpConversationsOlderThan(ctx context.Context, cutoff time.Time) (int64, error)

DeleteWarpConversationsOlderThan drops threads last touched before the cutoff, across all owners, one bounded batch per call - callers loop until a call returns zero.

func (*HybridLogStore) DeleteWarpTopicAssignments added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopicAssignments(ctx context.Context, logIDs []string) error

DeleteWarpTopicAssignments removes the given requests' assignments.

func (*HybridLogStore) DeleteWarpTopicAssignmentsBatch added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopicAssignmentsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteWarpTopicAssignmentsBatch deletes expired assignments in batches.

func (*HybridLogStore) DeleteWarpTopicAssignmentsUnmatchedSince added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopicAssignmentsUnmatchedSince(ctx context.Context, since time.Time) error

DeleteWarpTopicAssignmentsUnmatchedSince removes the rows filed under no topic at or after since.

func (*HybridLogStore) DeleteWarpTopicUnmatched added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopicUnmatched(ctx context.Context, logIDs []string) error

DeleteWarpTopicUnmatched removes requests from the pool.

func (*HybridLogStore) DeleteWarpTopicUnmatchedBatch added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopicUnmatchedBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteWarpTopicUnmatchedBatch deletes expired pool rows in batches.

func (*HybridLogStore) DeleteWarpTopicUnmatchedExcept added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopicUnmatchedExcept(ctx context.Context, embeddingSignature string) (int64, error)

DeleteWarpTopicUnmatchedExcept drops the pool rows of every other embedding model.

func (*HybridLogStore) DeleteWarpTopics added in v1.11.0 

func (h *HybridLogStore) DeleteWarpTopics(ctx context.Context, ids []string) error

DeleteWarpTopics removes topic and theme rows outright.

func (*HybridLogStore) DeleteWarpVectorDeletes added in v1.11.0 

func (h *HybridLogStore) DeleteWarpVectorDeletes(ctx context.Context, logIDs []string) error

DeleteWarpVectorDeletes removes the rows of logs whose vector is gone.

func (*HybridLogStore) DroppedUploads added in v1.3.2 

func (h *HybridLogStore) DroppedUploads() int64

DroppedUploads returns the number of S3 uploads that were dropped.

func (*HybridLogStore) EnsureClickHouseTable added in v1.5.3 

func (h *HybridLogStore) EnsureClickHouseTable(ctx context.Context, model any, table, partitionBy, orderBy, ttl string, skipIndexes []string) error

EnsureClickHouseTable delegates extension-table schema management to the ClickHouse logstore wrapped by hybrid object storage.

func (*HybridLogStore) FindAgentLog added in v1.9.0 

func (h *HybridLogStore) FindAgentLog(ctx context.Context, id string) (*AgentLog, error)

func (*HybridLogStore) FindAgentLogOperation added in v1.9.0 

func (h *HybridLogStore) FindAgentLogOperation(ctx context.Context, id string) (*AgentLogOperation, error)

FindAgentLogOperation hydrates the request and correlated event payload objects.

func (*HybridLogStore) FindAgentLogsForDeletion added in v1.9.0 

func (h *HybridLogStore) FindAgentLogsForDeletion(ctx context.Context, ids []string) ([]*AgentLog, error)

func (*HybridLogStore) FindAll added in v1.3.2 

func (h *HybridLogStore) FindAll(ctx context.Context, query any, fields ...string) ([]*Log, error)

FindAll returns all logs matching query. Each result is hydrated from object storage when the projection requires payload fields. Per-row hydration failures are logged inside hydrateLog and do not fail the call.

func (*HybridLogStore) FindAllDistinct added in v1.3.2 

func (h *HybridLogStore) FindAllDistinct(ctx context.Context, query any, fields ...string) ([]*Log, error)

FindAllDistinct delegates to the inner store. No hydration is performed: distinct queries operate purely on DB-resident columns and never need the offloaded payload.

func (*HybridLogStore) FindAsyncJobByID added in v1.3.2 

func (h *HybridLogStore) FindAsyncJobByID(ctx context.Context, id string) (*AsyncJob, error)

FindAsyncJobByID finds an async job by its ID.

func (*HybridLogStore) FindByID added in v1.3.2 

func (h *HybridLogStore) FindByID(ctx context.Context, id string) (*Log, error)

FindByID loads a log row from the DB and hydrates its payload fields from object storage when HasObject is true. Object-store fetch failures are logged but not returned, so the caller still receives the DB row.

func (*HybridLogStore) FindFirst added in v1.3.2 

func (h *HybridLogStore) FindFirst(ctx context.Context, query any, fields ...string) (*Log, error)

FindFirst returns the first log matching query. When the projection asks for payload-bearing fields (or the projection is empty, implying full hydration), the result is hydrated from object storage; otherwise the DB row is returned as-is.

func (*HybridLogStore) FindMCPToolLog added in v1.3.2 

func (h *HybridLogStore) FindMCPToolLog(ctx context.Context, id string) (*MCPToolLog, error)

FindMCPToolLog finds an MCP tool log by its ID and hydrates it with any associated object storage data.

func (*HybridLogStore) FindRelayLog added in v1.11.0 

func (h *HybridLogStore) FindRelayLog(ctx context.Context, id string) (*RelayLog, error)

func (*HybridLogStore) FindRelayLogsForDeletion added in v1.11.1 

func (h *HybridLogStore) FindRelayLogsForDeletion(ctx context.Context, ids []string) ([]*RelayLog, error)

func (*HybridLogStore) FindWebhookDeliveryByID added in v1.5.3 

func (h *HybridLogStore) FindWebhookDeliveryByID(ctx context.Context, id string) (*WebhookDelivery, error)

FindWebhookDeliveryByID retrieves a webhook delivery attempt by its ID.

func (*HybridLogStore) Flush added in v1.3.2 

func (h *HybridLogStore) Flush(ctx context.Context, since time.Time) error

Flush delegates to the inner store and forces any buffered DB writes since the given timestamp to be persisted. Object-store uploads are independently queued and not affected.

func (*HybridLogStore) FlushAgentLogs added in v1.9.0 

func (h *HybridLogStore) FlushAgentLogs(ctx context.Context, since time.Time) error

func (*HybridLogStore) FlushMCPToolLogs added in v1.3.2 

func (h *HybridLogStore) FlushMCPToolLogs(ctx context.Context, since time.Time) error

FlushMCPToolLogs flushes MCP tool logs that are older than the given time.

func (*HybridLogStore) GetAgentFilterData added in v1.9.0 

func (h *HybridLogStore) GetAgentFilterData(ctx context.Context, dimensions []string, limit int, query string) (*AgentFilterData, error)

func (*HybridLogStore) GetAgentHistogram added in v1.9.0 

func (h *HybridLogStore) GetAgentHistogram(ctx context.Context, filter AgentLogHistoryFilter, bucketSizeSeconds int64) (*AgentHistogramResult, error)

func (*HybridLogStore) GetAgentLogStats added in v1.9.0 

func (h *HybridLogStore) GetAgentLogStats(ctx context.Context, filter AgentLogHistoryFilter) (*AgentLogStats, error)

func (*HybridLogStore) GetAgentTopAgents added in v1.9.0 

func (h *HybridLogStore) GetAgentTopAgents(ctx context.Context, filter AgentLogHistoryFilter, limit int) (*AgentTopAgentsResult, error)

GetAgentTopAgents delegates to the database store; the ranking uses only database-resident columns.

func (*HybridLogStore) GetAvailableMCPApps added in v1.5.0 

func (h *HybridLogStore) GetAvailableMCPApps(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableMCPApps delegates to the inner store and returns distinct backend- detected app labels from MCP tool logs.

func (*HybridLogStore) GetAvailableMCPUserAgents added in v1.5.0 

func (h *HybridLogStore) GetAvailableMCPUserAgents(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableMCPUserAgents returns distinct raw User-Agent strings from MCP tool logs.

func (*HybridLogStore) GetAvailableMCPVirtualKeys added in v1.3.2 

func (h *HybridLogStore) GetAvailableMCPVirtualKeys(ctx context.Context, limit int, query string) ([]MCPToolLog, error)

GetAvailableMCPVirtualKeys returns a list of MCP tool log virtual keys that match the given query.

func (*HybridLogStore) GetAvailableServerLabels added in v1.3.2 

func (h *HybridLogStore) GetAvailableServerLabels(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableServerLabels returns a list of server labels that match the given query.

func (*HybridLogStore) GetAvailableToolNames added in v1.3.2 

func (h *HybridLogStore) GetAvailableToolNames(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableToolNames returns a list of tool names that match the given query.

func (*HybridLogStore) GetCostHistogram added in v1.3.2 

func (h *HybridLogStore) GetCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*CostHistogramResult, error)

GetCostHistogram delegates to the inner store and returns a cost histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetDimensionCostHistogram added in v1.3.2 

func (h *HybridLogStore) GetDimensionCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionCostHistogramResult, error)

GetDimensionCostHistogram delegates to the inner store and returns a cost histogram bucketed by bucketSizeSeconds and grouped by the given dimension.

func (*HybridLogStore) GetDimensionLatencyHistogram added in v1.3.2 

func (h *HybridLogStore) GetDimensionLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionLatencyHistogramResult, error)

GetDimensionLatencyHistogram delegates to the inner store and returns a latency histogram bucketed by bucketSizeSeconds and grouped by the given dimension.

func (*HybridLogStore) GetDimensionModelUsage added in v1.11.0 

func (h *HybridLogStore) GetDimensionModelUsage(ctx context.Context, filters SearchFilters, dimension RankingDimension) ([]DimensionModelUsageEntry, error)

GetDimensionModelUsage delegates to the inner store and returns usage per (entity, model, provider) on a rollup dimension in one read.

func (*HybridLogStore) GetDimensionRankings added in v1.3.14 

func (h *HybridLogStore) GetDimensionRankings(ctx context.Context, filters SearchFilters, dimension RankingDimension) (*DimensionRankingResult, error)

func (*HybridLogStore) GetDimensionTokenHistogram added in v1.3.2 

func (h *HybridLogStore) GetDimensionTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionTokenHistogramResult, error)

GetDimensionTokenHistogram delegates to the inner store and returns a token histogram bucketed by bucketSizeSeconds and grouped by the given dimension.

func (*HybridLogStore) GetDimensionUsage added in v1.11.0 

func (h *HybridLogStore) GetDimensionUsage(ctx context.Context, filters SearchFilters, dimension RankingDimension, compare bool) ([]DimensionUsageEntry, error)

GetDimensionUsage delegates to the inner store and returns each entity's usage on a rollup dimension in one read.

func (*HybridLogStore) GetDistinctAliases added in v1.3.2 

func (h *HybridLogStore) GetDistinctAliases(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctAliases delegates to the inner store and returns distinct alias values matching query, capped at limit.

func (*HybridLogStore) GetDistinctApps added in v1.5.0 

func (h *HybridLogStore) GetDistinctApps(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctApps delegates to the inner store and returns distinct backend- detected app labels from recent logs.

func (*HybridLogStore) GetDistinctKeyPairs added in v1.3.2 

func (h *HybridLogStore) GetDistinctKeyPairs(ctx context.Context, idCol, nameCol string, limit int, query string) ([]KeyPairResult, error)

GetDistinctKeyPairs delegates to the inner store and returns distinct (idCol, nameCol) pairs matching query, capped at limit. Used to populate id/name filters in the UI for virtual keys, providers, etc.

func (*HybridLogStore) GetDistinctMetadataKeys added in v1.3.2 

func (h *HybridLogStore) GetDistinctMetadataKeys(ctx context.Context, limit int, query string) (map[string][]string, error)

GetDistinctMetadataKeys delegates to the inner store and returns distinct metadata keys (and their distinct values) matching query, capped at limit.

func (*HybridLogStore) GetDistinctModels added in v1.3.2 

func (h *HybridLogStore) GetDistinctModels(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctModels delegates to the inner store and returns distinct model values matching query, capped at limit.

func (*HybridLogStore) GetDistinctRoutingEngines added in v1.3.2 

func (h *HybridLogStore) GetDistinctRoutingEngines(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctRoutingEngines delegates to the inner store and returns distinct routing-engine values matching query, capped at limit.

func (*HybridLogStore) GetDistinctStopReasons added in v1.3.6 

func (h *HybridLogStore) GetDistinctStopReasons(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctStopReasons delegates to the inner store and returns distinct stop-reason values matching query, capped at limit.

func (*HybridLogStore) GetDistinctToolCallNames added in v1.6.1 

func (h *HybridLogStore) GetDistinctToolCallNames(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctToolCallNames delegates to the inner store. tool_call_names is not a payload field, so the inner row carries it even when content is offloaded.

func (*HybridLogStore) GetDistinctUserAgents added in v1.5.0 

func (h *HybridLogStore) GetDistinctUserAgents(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctUserAgents delegates to the inner store and returns distinct raw User-Agent strings for the logs "App" filter, capped at limit.

func (*HybridLogStore) GetHistogram added in v1.3.2 

func (h *HybridLogStore) GetHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*HistogramResult, error)

GetHistogram delegates to the inner store and returns a request-count histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetLatencyHistogram added in v1.3.2 

func (h *HybridLogStore) GetLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*LatencyHistogramResult, error)

GetLatencyHistogram delegates to the inner store and returns a latency histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetMCPCostHistogram added in v1.3.2 

func (h *HybridLogStore) GetMCPCostHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPCostHistogramResult, error)

GetMCPCostHistogram returns the cost histogram for MCP tool logs.

func (*HybridLogStore) GetMCPHistogram added in v1.3.2 

func (h *HybridLogStore) GetMCPHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPHistogramResult, error)

GetMCPHistogram delegates to the inner store and returns an MCP tool-call count histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetMCPToolCountsByDimension added in v1.11.0 

func (h *HybridLogStore) GetMCPToolCountsByDimension(ctx context.Context, filters MCPToolLogSearchFilters, dimension RankingDimension) (map[string]int, error)

GetMCPToolCountsByDimension delegates to the inner store and returns each entity's distinct tool count.

func (*HybridLogStore) GetMCPToolLogStats added in v1.3.2 

func (h *HybridLogStore) GetMCPToolLogStats(ctx context.Context, filters MCPToolLogSearchFilters) (*MCPToolLogStats, error)

GetMCPToolLogStats returns statistics about MCP tool logs that match the given filters.

func (*HybridLogStore) GetMCPTopTools added in v1.3.2 

func (h *HybridLogStore) GetMCPTopTools(ctx context.Context, filters MCPToolLogSearchFilters, limit int) (*MCPTopToolsResult, error)

GetMCPTopTools returns the top tools used in MCP tool logs.

func (*HybridLogStore) GetModelHistogram added in v1.3.2 

func (h *HybridLogStore) GetModelHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ModelHistogramResult, error)

GetModelHistogram delegates to the inner store and returns a per-model request histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetModelRankings added in v1.3.2 

func (h *HybridLogStore) GetModelRankings(ctx context.Context, filters SearchFilters) (*ModelRankingResult, error)

GetModelRankings delegates to the inner store and returns ranked usage aggregates per model for the matching log rows.

func (*HybridLogStore) GetNodeUsageAfter added in v1.3.11 

func (h *HybridLogStore) GetNodeUsageAfter(ctx context.Context, nodeID string, cursor NodeUsageCursor) (*NodeUsageAggregate, error)

GetNodeUsageAfter delegates to the inner store and returns usage aggregates for the given node since cursor, used by the cluster gossip path to ship incremental usage to peers.

func (*HybridLogStore) GetProviderCostHistogram added in v1.3.2 

func (h *HybridLogStore) GetProviderCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderCostHistogramResult, error)

GetProviderCostHistogram delegates to the inner store and returns a per-provider cost histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetProviderLatencyHistogram added in v1.3.2 

func (h *HybridLogStore) GetProviderLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderLatencyHistogramResult, error)

GetProviderLatencyHistogram delegates to the inner store and returns a per-provider latency histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetProviderThroughputHistogram added in v1.5.3 

func (h *HybridLogStore) GetProviderThroughputHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderThroughputHistogramResult, error)

GetProviderThroughputHistogram delegates to the inner store and returns a per-provider throughput (tokens/sec) histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetProviderTokenHistogram added in v1.3.2 

func (h *HybridLogStore) GetProviderTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderTokenHistogramResult, error)

GetProviderTokenHistogram delegates to the inner store and returns a per-provider token histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetRelayFilterData added in v1.11.0 

func (h *HybridLogStore) GetRelayFilterData(ctx context.Context, dimensions []string, limit int, search string) (*RelayFilterData, error)

func (*HybridLogStore) GetRelayHistogram added in v1.11.0 

func (h *HybridLogStore) GetRelayHistogram(ctx context.Context, filters RelayLogFilters, bucketSizeSeconds int64) (*RelayHistogramResult, error)

func (*HybridLogStore) GetRelayLogStats added in v1.11.0 

func (h *HybridLogStore) GetRelayLogStats(ctx context.Context, filters RelayLogFilters) (*RelayLogStats, error)

func (*HybridLogStore) GetRelayTopEndpoints added in v1.11.0 

func (h *HybridLogStore) GetRelayTopEndpoints(ctx context.Context, filters RelayLogFilters, limit int) (*RelayTopResults, error)

func (*HybridLogStore) GetSessionLogs added in v1.3.2 

func (h *HybridLogStore) GetSessionLogs(ctx context.Context, sessionID string, pagination PaginationOptions) (*SessionDetailResult, error)

GetSessionLogs delegates to the inner store and returns the paginated logs belonging to the given session.

func (*HybridLogStore) GetSessionSummary added in v1.3.2 

func (h *HybridLogStore) GetSessionSummary(ctx context.Context, sessionID string) (*SessionSummaryResult, error)

GetSessionSummary delegates to the inner store and returns an aggregated summary for the given session.

func (*HybridLogStore) GetStats added in v1.3.2 

func (h *HybridLogStore) GetStats(ctx context.Context, filters SearchFilters) (*SearchStats, error)

GetStats delegates to the inner store and returns aggregate statistics for the matching log rows.

func (*HybridLogStore) GetThroughputHistogram added in v1.5.3 

func (h *HybridLogStore) GetThroughputHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ThroughputHistogramResult, error)

GetThroughputHistogram delegates to the inner store and returns a token-generation throughput (tokens/sec) histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetTokenHistogram added in v1.3.2 

func (h *HybridLogStore) GetTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*TokenHistogramResult, error)

GetTokenHistogram delegates to the inner store and returns a token-usage histogram bucketed by bucketSizeSeconds.

func (*HybridLogStore) GetUserRankings added in v1.3.2 

func (h *HybridLogStore) GetUserRankings(ctx context.Context, filters SearchFilters) (*UserRankingResult, error)

GetUserRankings delegates to the inner store and returns ranked usage aggregates per user for the matching log rows.

func (*HybridLogStore) GetUserSpend added in v1.9.0 

func (h *HybridLogStore) GetUserSpend(ctx context.Context, filters SearchFilters) ([]UserSpendEntry, error)

GetUserSpend delegates to the inner store and returns each user's total cost in the filter window.

func (*HybridLogStore) GetWarpConversation added in v1.9.0 

func (h *HybridLogStore) GetWarpConversation(ctx context.Context, ownerID, id string) (*WarpConversation, error)

GetWarpConversation returns one thread with its messages in order.

func (*HybridLogStore) HasLogs added in v1.3.2 

func (h *HybridLogStore) HasLogs(ctx context.Context) (bool, error)

HasLogs delegates to the inner store and reports whether any log rows exist. The object store is not consulted.

func (*HybridLogStore) HasMCPToolLogs added in v1.3.2 

func (h *HybridLogStore) HasMCPToolLogs(ctx context.Context) (bool, error)

HasMCPToolLogs returns whether there are any MCP tool logs in the store.

func (*HybridLogStore) HasRelayLogs added in v1.11.0 

func (h *HybridLogStore) HasRelayLogs(ctx context.Context) (bool, error)

func (*HybridLogStore) HydrateBillingChunk added in v1.5.5 

func (h *HybridLogStore) HydrateBillingChunk(ctx context.Context, logs []*Log) (BillingHydrationResult, error)

HydrateBillingChunk restores offloaded pricing inputs for a small slice of rows.

This exists because of a real mis-billing bug: a row whose token_usage was offloaded comes back with a stub rebuilt from denormalized columns, and because PromptTokens is inclusive of the cache buckets, pricing that stub charges every cache-read token at the full input rate — inflating a cache-heavy request several fold.

Two deliberate properties:

SEQUENTIAL — one object in flight at a time. A parallel fan-out multiplies peak memory by its width, since each in-flight fetch holds the whole object as a []byte plus the map[string]string that MergePayloadFromJSON unmarshals it into, and objects can carry full message histories and raw request/response bodies. This runs inside a checkpointed background job, so predictability beats throughput. Combined with the caller paging and chunking at BillingHydrationChunkSize, a recompute worker's payload memory is bounded by a handful of rows no matter how large the window.

SKIPS ROWS THAT DO NOT NEED IT — a row already carrying its pricing inputs costs no I/O at all. See billingRowNeedsHydration.

func (*HybridLogStore) IsLogEntryPresent added in v1.3.2 

func (h *HybridLogStore) IsLogEntryPresent(ctx context.Context, id string) (bool, error)

IsLogEntryPresent delegates to the inner store and reports whether a log row with the given ID exists.

func (*HybridLogStore) ListAgentLogHistory added in v1.9.0 

func (h *HybridLogStore) ListAgentLogHistory(ctx context.Context, filter AgentLogHistoryFilter, pagination PaginationOptions) (*AgentLogHistoryResult, error)

func (*HybridLogStore) ListAgentLogOperations added in v1.9.0 

func (h *HybridLogStore) ListAgentLogOperations(ctx context.Context, filter AgentLogHistoryFilter, pagination PaginationOptions) (*AgentLogOperationResult, error)

ListAgentLogOperations hydrates payload objects for the bounded operation page.

func (*HybridLogStore) ListLogsForWarpTopics added in v1.11.0 

func (h *HybridLogStore) ListLogsForWarpTopics(ctx context.Context, logIDs []string, from, to time.Time) ([]WarpTopicAssignment, error)

ListLogsForWarpTopics returns the assignment columns of the given logs.

func (*HybridLogStore) ListUserAgentMappings added in v1.5.0 

func (h *HybridLogStore) ListUserAgentMappings(ctx context.Context, activeOnly bool) ([]UserAgentMapping, error)

func (*HybridLogStore) ListWarpConversations added in v1.9.0 

func (h *HybridLogStore) ListWarpConversations(ctx context.Context, ownerID string, limit int) ([]WarpConversation, error)

ListWarpConversations returns an owner's threads, most recent first.

func (*HybridLogStore) ListWarpTopicAssignments added in v1.11.0 

func (h *HybridLogStore) ListWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter, limit int) ([]WarpTopicAssignment, error)

ListWarpTopicAssignments returns the selected assignments newest first.

func (*HybridLogStore) ListWarpTopicUnmatched added in v1.11.0 

func (h *HybridLogStore) ListWarpTopicUnmatched(ctx context.Context, embeddingSignature string, limit int) ([]WarpTopicUnmatched, error)

ListWarpTopicUnmatched returns the pool for one embedding model.

func (*HybridLogStore) ListWarpTopics added in v1.11.0 

func (h *HybridLogStore) ListWarpTopics(ctx context.Context, filter WarpTopicFilter) ([]WarpTopic, error)

ListWarpTopics returns the selected topics, oldest first.

func (*HybridLogStore) ListWarpVectorDeletes added in v1.11.0 

func (h *HybridLogStore) ListWarpVectorDeletes(ctx context.Context, limit int) ([]WarpVectorDelete, error)

ListWarpVectorDeletes returns up to limit pending vector deletes.

func (*HybridLogStore) MigrationInProgress added in v1.9.0 

func (h *HybridLogStore) MigrationInProgress(ctx context.Context) bool

MigrationInProgress implements MaintenanceGate by forwarding to the inner store when it has a gate; a wrapped store without one reports false.

func (*HybridLogStore) Ping added in v1.3.2 

func (h *HybridLogStore) Ping(ctx context.Context) error

Ping delegates to the inner store's health check.

func (*HybridLogStore) PruneWarpConversations added in v1.9.0 

func (h *HybridLogStore) PruneWarpConversations(ctx context.Context, ownerID string, keep int) (int64, error)

PruneWarpConversations drops an owner's oldest threads beyond keep.

func (*HybridLogStore) PruneWarpTopicUnmatched added in v1.11.0 

func (h *HybridLogStore) PruneWarpTopicUnmatched(ctx context.Context, olderThan time.Time, keep int) (int64, error)

PruneWarpTopicUnmatched bounds the pool by age and by count.

func (*HybridLogStore) ReconcileAgentCorrelation added in v1.9.0 

func (h *HybridLogStore) ReconcileAgentCorrelation(ctx context.Context, entries []*AgentLog) error

func (*HybridLogStore) ReconcileClickHouseTTL added in v1.9.0 

func (h *HybridLogStore) ReconcileClickHouseTTL(ctx context.Context, table, ttl string) error

ReconcileClickHouseTTL delegates to the ClickHouse logstore wrapped by hybrid object storage.

func (*HybridLogStore) ScopedDB added in v1.4.4 

func (h *HybridLogStore) ScopedDB(ctx context.Context) *gorm.DB

ScopedDB exposes the underlying RDB query surface when hybrid mode wraps a Postgres/SQLite logstore. Enterprise logstore extensions use this for their own logstore-owned tables, such as alert history.

func (*HybridLogStore) SearchLogs added in v1.3.2 

func (h *HybridLogStore) SearchLogs(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)

SearchLogs delegates to the inner store. Search operates on indexed DB columns (including ContentSummary); payloads are not hydrated here.

func (*HybridLogStore) SearchLogsForBilling added in v1.5.5 

func (h *HybridLogStore) SearchLogsForBilling(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)

SearchLogsForBilling delegates to the inner store. Hydration is deliberately NOT done here — see HydrateBillingChunk.

func (*HybridLogStore) SearchMCPToolLogs added in v1.3.2 

func (h *HybridLogStore) SearchMCPToolLogs(ctx context.Context, filters MCPToolLogSearchFilters, pagination PaginationOptions) (*MCPToolLogSearchResult, error)

SearchMCPToolLogs searches for MCP tool logs that match the given filters and returns the results.

func (*HybridLogStore) SearchRelayLogs added in v1.11.0 

func (h *HybridLogStore) SearchRelayLogs(ctx context.Context, filters RelayLogFilters, pagination PaginationOptions) (*RelayLogSearchResult, error)

func (*HybridLogStore) SearchWebhookDeliveries added in v1.5.3 

func (h *HybridLogStore) SearchWebhookDeliveries(ctx context.Context, filters *WebhookDeliverySearchFilters, pagination PaginationOptions) (*WebhookDeliverySearchResult, error)

SearchWebhookDeliveries returns one page of matching delivery history.

func (*HybridLogStore) SetDistributedLocker added in v1.9.0 

func (h *HybridLogStore) SetDistributedLocker(locker DistributedLocker)

SetDistributedLocker hands the locker to the inner store when it has use for one (ClickHouse); the SQL stores serialize with row locks instead.

func (*HybridLogStore) SumWarpMessageUsage added in v1.9.0 

func (h *HybridLogStore) SumWarpMessageUsage(ctx context.Context, conversationIDs []string) (map[string]WarpUsageTotals, error)

SumWarpMessageUsage returns each thread's total tokens and cost in one query.

func (*HybridLogStore) SummarizeWarpTopicAssignments added in v1.11.0 

func (h *HybridLogStore) SummarizeWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter) ([]WarpTopicUsage, error)

SummarizeWarpTopicAssignments adds up the selected assignments per topic.

func (*HybridLogStore) Update added in v1.3.2 

func (h *HybridLogStore) Update(ctx context.Context, id string, entry any) error

Update passes the update through to the inner store for index/scalar field updates. Payload-field changes are not re-offloaded here; the logging plugin owns that path and calls processUpload directly when it needs to.

func (*HybridLogStore) UpdateAgentLog added in v1.9.0 

func (h *HybridLogStore) UpdateAgentLog(ctx context.Context, id string, entry any) error

func (*HybridLogStore) UpdateAsyncJob added in v1.3.2 

func (h *HybridLogStore) UpdateAsyncJob(ctx context.Context, id string, updates map[string]interface{}) error

UpdateAsyncJob updates an async job with the given ID using the provided updates.

func (*HybridLogStore) UpdateMCPToolLog added in v1.3.2 

func (h *HybridLogStore) UpdateMCPToolLog(ctx context.Context, id string, entry any) error

UpdateMCPToolLog updates an existing MCP tool log with the given ID using the provided entry data.

func (*HybridLogStore) UpdateRelayLog added in v1.11.1 

func (h *HybridLogStore) UpdateRelayLog(ctx context.Context, id string, updates map[string]any) error

func (*HybridLogStore) UpdateUserAgentMapping added in v1.5.0 

func (h *HybridLogStore) UpdateUserAgentMapping(ctx context.Context, id string, mapping *UserAgentMapping) error

func (*HybridLogStore) UpsertWarpTopicAssignments added in v1.11.0 

func (h *HybridLogStore) UpsertWarpTopicAssignments(ctx context.Context, assignments []WarpTopicAssignment) error

UpsertWarpTopicAssignments writes one row per request.

func (*HybridLogStore) UpsertWarpTopics added in v1.11.0 

func (h *HybridLogStore) UpsertWarpTopics(ctx context.Context, topics []WarpTopic) error

UpsertWarpTopics writes topics whole.

type KeyPairResult added in v1.2.22 

type KeyPairResult struct {
	ID   string `gorm:"column:id"`
	Name string `gorm:"column:name"`
}

KeyPairResult represents an ID-Name pair returned from DISTINCT queries

type LatencyHistogramBucket added in v1.2.24 

type LatencyHistogramBucket struct {
	Timestamp     time.Time `json:"timestamp"`
	AvgLatency    float64   `json:"avg_latency"`
	P90Latency    float64   `json:"p90_latency"`
	P95Latency    float64   `json:"p95_latency"`
	P99Latency    float64   `json:"p99_latency"`
	AvgOverhead   float64   `json:"avg_overhead"`
	P90Overhead   float64   `json:"p90_overhead"`
	P95Overhead   float64   `json:"p95_overhead"`
	P99Overhead   float64   `json:"p99_overhead"`
	TotalRequests int64     `json:"total_requests"`
}

LatencyHistogramBucket represents a single time bucket for latency data

type LatencyHistogramResult added in v1.2.24 

type LatencyHistogramResult struct {
	Buckets           []LatencyHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                    `json:"bucket_size_seconds"`
}

LatencyHistogramResult represents the latency histogram query result

type Log 

type Log struct {
	ID                      string    `gorm:"primaryKey;type:varchar(255)" json:"id"`
	IncNumber               *int64    `gorm:"column:inc_number" json:"inc_number,omitempty"`
	ParentRequestID         *string   `gorm:"type:varchar(255);index" json:"parent_request_id"`
	Timestamp               time.Time ``                                                                         /* 432-byte string literal not displayed */
	Object                  string    `gorm:"type:varchar(255);index;not null;column:object_type" json:"object"` // text.completion, chat.completion, or embedding
	IsPassthrough           bool      `gorm:"not null;default:false" json:"is_passthrough,omitempty"`            // Row came from a passthrough route; Object is its inferred type, or passthrough when none is known
	Provider                string    `gorm:"type:varchar(255);index;index:idx_logs_ts_provider_status,priority:2;not null" json:"provider"`
	Model                   string    `gorm:"type:varchar(255);index;not null" json:"model"`
	Alias                   *string   `gorm:"type:varchar(255);index" json:"alias,omitempty"`          // Set when model was resolved via alias mapping; the original name the caller used
	CanonicalModelName      *string   `gorm:"type:varchar(255)" json:"canonical_model_name,omitempty"` // Canonical model name configured on the resolved alias, when set
	AliasModelFamily        *string   `gorm:"type:varchar(255)" json:"alias_model_family,omitempty"`   // Model family configured on the resolved alias, when set
	ServerSideFallbackModel *string   `gorm:"type:varchar(255)" json:"server_side_fallback_model,omitempty"`
	ServedModel             *string   `gorm:"type:varchar(255)" json:"served_model,omitempty"` // Model the provider named on the response body when it differs from Model
	NumberOfRetries         int       `gorm:"default:0" json:"number_of_retries"`
	FallbackIndex           int       `gorm:"default:0" json:"fallback_index"`
	SelectedKeyID           string    `gorm:"type:varchar(255);index:idx_logs_selected_key_ts,priority:1" json:"selected_key_id"` // (selected_key_id, timestamp) composite; replaces idx_logs_selected_key_id
	SelectedKeyName         string    `gorm:"type:varchar(255)" json:"selected_key_name"`
	AttemptTrail            string    `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.KeyAttemptRecord
	VirtualKeyID            *string   `gorm:"type:varchar(255);index:idx_logs_vk_ts,priority:1" json:"virtual_key_id"` // (virtual_key_id, timestamp) composite serves owner-filtered lists newest-first and every equality lookup on virtual_key_id
	VirtualKeyName          *string   `gorm:"type:varchar(255)" json:"virtual_key_name"`
	RoutingEnginesUsedStr   *string   `gorm:"type:varchar(255);column:routing_engines_used" json:"-"`                             // Comma-separated routing engines
	ToolCallNamesStr        *string   `gorm:"type:text;column:tool_call_names" json:"-"`                                          // Comma-separated distinct function names the response called. Not a payload field, so it stays on the row in hybrid mode and is filterable. Names are recorded regardless of content logging; arguments live in tool_calls and follow content policy.
	RoutingRuleID           *string   `gorm:"type:varchar(255);index:idx_logs_routing_rule_ts,priority:1" json:"routing_rule_id"` // (routing_rule_id, timestamp) composite; replaces idx_logs_routing_rule_id
	RoutingRuleName         *string   `gorm:"type:varchar(255)" json:"routing_rule_name"`
	ComplexityTier          *string   `gorm:"type:varchar(50);index:idx_logs_complexity_tier,where:complexity_tier IS NOT NULL" json:"complexity_tier,omitempty"` // Complexity tier used for routing ("SIMPLE", "MEDIUM", "COMPLEX"); NULL when no routing rule demanded complexity. Partial index, matching its performanceIndexes entry
	ComplexityMechanism     *string   ``                                                                                                                          // How the complexity tier was classified ("semantic", "decision", "llm", "session", "skipped"). NULL means no routing rule referenced complexity_tier, so classification never ran. Partial index, matching its performanceIndexes entry
	/* 136-byte string literal not displayed */
	ComplexityScore *float64 `gorm:"column:complexity_score" json:"complexity_score,omitempty"` // Raw complexity score behind the tier; unindexed (detail-view only)
	SessionID       *string  ``                                                                 // Raw opaque session identity resolved at ingress for key stickiness and log correlation
	/* 183-byte string literal not displayed */
	AgentCorrelationID *string `` // Caller-supplied correlation identity from x-bf-agent-correlation-id
	/* 137-byte string literal not displayed */
	SelectedPromptName    *string `gorm:"type:varchar(255)" json:"selected_prompt_name"`
	SelectedPromptVersion *string `gorm:"type:varchar(64)" json:"selected_prompt_version"`
	SelectedPromptID      *string `gorm:"type:varchar(36)" json:"selected_prompt_id"`
	UserID                *string `gorm:"type:varchar(255);index:idx_logs_user_ts,priority:1" json:"user_id"` // (user_id, timestamp) composite; replaces the single-column idx_logs_user_id
	UserName              *string `gorm:"type:varchar(255)" json:"user_name"`
	TeamID                *string `gorm:"type:varchar(255);index:idx_logs_team_ts,priority:1" json:"team_id"` // (team_id, timestamp) composite; replaces the single-column idx_logs_team_id
	TeamName              *string `gorm:"type:varchar(255)" json:"team_name"`
	CustomerID            *string `gorm:"type:varchar(255);index:idx_logs_customer_ts,priority:1" json:"customer_id"` // (customer_id, timestamp) composite; replaces idx_logs_customer_id
	CustomerName          *string `gorm:"type:varchar(255)" json:"customer_name"`
	BusinessUnitID        *string `gorm:"type:varchar(255);index:idx_logs_business_unit_ts,priority:1" json:"business_unit_id"` // (business_unit_id, timestamp) composite; replaces idx_logs_business_unit_id
	BusinessUnitName      *string `gorm:"type:varchar(255)" json:"business_unit_name"`
	ProjectID             *string `gorm:"type:varchar(255);index:idx_logs_project_ts,priority:1" json:"project_id"` // (project_id, timestamp) composite; replaces idx_logs_project_id
	ProjectName           *string `gorm:"type:varchar(255)" json:"project_name"`
	TeamIDs               *string `gorm:"type:text" json:"-"`
	TeamNames             *string `gorm:"type:text" json:"-"`
	CustomerIDs           *string `gorm:"type:text" json:"-"`
	CustomerNames         *string `gorm:"type:text" json:"-"`
	BusinessUnitIDs       *string `gorm:"type:text" json:"-"`
	BusinessUnitNames     *string `gorm:"type:text" json:"-"`
	UserAgent             *string `gorm:"type:varchar(512);index:idx_logs_user_agent" json:"user_agent,omitempty"` // Raw HTTP User-Agent of the calling client
	App                   *string `gorm:"type:varchar(128);index:idx_logs_app" json:"app,omitempty"`               // Backend-detected client app derived from user_agent
	InputHistory          string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.ChatMessage
	ResponsesInputHistory string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.ResponsesMessage
	OutputMessage         string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.ChatMessage
	ResponsesOutput       string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.ResponsesMessage
	EmbeddingInput        string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.EmbeddingInputItem
	EmbeddingOutput       string  `gorm:"type:text" json:"-"`                                                      // JSON serialized [][]float32
	RerankOutput          string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.RerankResult
	OCROutput             string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostOCRResponse
	Params                string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.ModelParameters
	Tools                 string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.Tool
	ToolCalls             string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.ToolCall (For backward compatibility, tool calls are now in the content)
	SpeechInput           string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.SpeechInput
	TranscriptionInput    string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.TranscriptionInput
	OCRInput              string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.OCRDocument
	ImageGenerationInput  string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.ImageGenerationInput
	ImageEditInput        string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.ImageEditInput
	ImageVariationInput   string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.ImageVariationInput
	VideoGenerationInput  string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.VideoGenerationInput
	VideoEditInput        string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.VideoEditInput
	SpeechOutput          string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostSpeech
	TranscriptionOutput   string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostTranscribe
	ImageGenerationOutput string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostImageGenerationResponse
	ListModelsOutput      string  `gorm:"type:text" json:"-"`                                                      // JSON serialized []schemas.Model
	VideoGenerationOutput string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostVideoGenerationResponse
	VideoRetrieveOutput   string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostVideoRetrieveResponse
	VideoDownloadOutput   string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostVideoDownloadResponse
	VideoListOutput       string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostVideoListResponse
	VideoDeleteOutput     string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.BifrostVideoDeleteResponse
	LiveSession           string  `gorm:"type:text" json:"-"`                                                      // JSON serialized *schemas.LiveSessionLog
	// Debug spelling is retained for the persisted cache and guardrail columns.
	CacheDebug        string   `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostCacheMetadata
	GuardrailDebug    string   `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostGuardrailMetadata
	RoutingMetadata   string   `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostRoutingMetadata
	Latency           *float64 `gorm:"index:idx_logs_latency" json:"latency,omitempty"`
	UpstreamLatency   *float64 `gorm:"index:idx_logs_upstream_latency" json:"upstream_latency,omitempty"` // Provider socket time for this row's call (with its retries), ms; nil = unmeasured
	OverheadLatency   *float64 `gorm:"index:idx_logs_overhead_latency" json:"overhead_latency,omitempty"` // Bifrost overhead (total minus upstream), ms; nil = unmeasured
	OverheadBreakdown string   `gorm:"type:text" json:"-"`                                                // JSON serialized []OverheadBucket: per-span self-time decomposition of overhead
	TokenUsage        string   `gorm:"type:text" json:"-"`                                                // JSON serialized *schemas.LLMUsage
	// Denormalized cost split for per-category quota aggregation. input + output +
	// additional reconcile to the cost column. Additional holds internal sidecar
	// costs with no input/output token category (guardrail, MCP).
	InputCost      float64  `gorm:"default:0" json:"-"`
	OutputCost     float64  `gorm:"default:0" json:"-"`
	AdditionalCost float64  `gorm:"default:0" json:"-"`
	Cost           *float64 `gorm:"index" json:"cost,omitempty"` // Cost in dollars (total cost of the request - includes cache lookup cost)
	// Virtual: one cost breakdown the UI reads across every row type. Assembled in
	// DeserializeFields from token_usage.cost when present (full detail), else from
	// the denormalized columns. Never stored.
	CostBreakdown           *schemas.BifrostCost `gorm:"-" json:"cost_breakdown,omitempty"`
	Status                  string               `gorm:"type:varchar(50);index;index:idx_logs_ts_provider_status,priority:3;not null" json:"status"` // "processing", "success", or "error"
	StopReason              *string              `gorm:"type:varchar(50);index:idx_logs_stop_reason" json:"stop_reason,omitempty"`                   // Why the model stopped: "stop", "length", "content_filter", "tool_calls", etc.
	ErrorDetails            string               `gorm:"type:text" json:"-"`                                                                         // JSON serialized *schemas.BifrostError
	Stream                  bool                 `gorm:"default:false" json:"stream"`                                                                // true if this was a streaming response
	ContentSummary          string               `gorm:"type:text" json:"content_summary,omitempty"`                                                 // Last user message preview; UI log-list display fallback when payload fields are offloaded to object storage
	RawRequest              string               `gorm:"type:text" json:"raw_request"`                                                               // Populated when `send-back-raw-request` is on
	RawResponse             string               `gorm:"type:text" json:"raw_response"`                                                              // Populated when `send-back-raw-response` is on
	PassthroughRequestBody  string               `gorm:"type:text" json:"passthrough_request_body,omitempty"`                                        // Raw body for passthrough requests (UTF-8)
	PassthroughResponseBody string               `gorm:"type:text" json:"passthrough_response_body,omitempty"`                                       // Raw body for passthrough responses (UTF-8)
	RoutingEngineLogs       string               `gorm:"type:text" json:"routing_engine_logs,omitempty"`                                             // Formatted routing engine decision logs
	PluginLogs              string               `gorm:"type:text" json:"plugin_logs,omitempty"`                                                     // JSON serialized plugin log entries grouped by plugin name
	Metadata                *string              `gorm:"type:text" json:"-"`                                                                         // JSON serialized map[string]interface{}
	IsLargePayloadRequest   bool                 `gorm:"default:false" json:"is_large_payload_request"`
	IsLargePayloadResponse  bool                 `gorm:"default:false" json:"is_large_payload_response"`
	HasObject               bool                 `gorm:"default:false" json:"-"`              // True when payload is stored in object storage
	ContentHidden           bool                 `gorm:"default:false" json:"content_hidden"` // True when content logging was disabled for the request, so the payload must never be served back through the API/UI (whether it was retained in object storage or dropped entirely)

	// Aggregates over this log's child rows (rows whose parent_request_id equals
	// this log's ID, i.e. fallback attempts). Populated only on roots_only list
	// queries so the UI can render an expandable chain row; never stored.
	ChildCount     int64   `gorm:"-" json:"child_count,omitempty"`
	ChildrenCost   float64 `gorm:"-" json:"children_cost,omitempty"`
	ChildrenTokens int64   `gorm:"-" json:"children_tokens,omitempty"`

	// Aggregates over every row sharing this row's session_id, under the same
	// filters that produced the page. Populated only on the session root of a
	// collapsed session; never stored. The count excludes this row (it is the
	// "N more" badge on the expander) while the totals include it, so the cells
	// can render them as-is without re-adding the root's own numbers.
	SessionChildCount  int64   `gorm:"-" json:"session_child_count,omitempty"`
	SessionTotalCost   float64 `gorm:"-" json:"session_total_cost,omitempty"`
	SessionTotalTokens int64   `gorm:"-" json:"session_total_tokens,omitempty"`

	DeferredGuardrail       *schemas.DeferredGuardrailResult `gorm:"-" json:"-"` // Transient: pending output-monitor guardrail result; the writer holds the row until it completes
	RealtimeInputCorrection *RealtimeInputCorrection         `gorm:"-" json:"-"` // Transient: merge one late transcript into the latest offloaded payload

	RedactionData            *schemas.RedactionData        `gorm:"-" json:"-"`                           // Transient guardrail redaction data consumed by enterprise logstore wrappers
	PassthroughParseFormat   schemas.ModelProvider         `gorm:"-" json:"-"`                           // Transient: base provider whose wire format the log writer parses passthrough bodies with; empty skips parsing
	PassthroughParseMaxBytes int64                         `gorm:"-" json:"-"`                           // Transient: large-payload request threshold applied to media parsed from passthrough bodies; 0 keeps everything
	RedactionMapping         string                        `gorm:"type:text" json:"-"`                   // Reversible redaction mapping (encrypted when an encryption key is set), written by enterprise logstore wrappers; deleted with the row
	RevealRedactionMapping   *schemas.RedactionMapsByPhase `gorm:"-" json:"redaction_mapping,omitempty"` // Virtual field populated only on permitted log-detail reads

	// Cluster governance fields - attached by the logging plugin when running in a cluster
	// so that leaders can recover disconnected node usage from the logs table.
	ClusterNodeID *string `gorm:"type:varchar(255)" json:"cluster_node_id,omitempty"`
	BudgetIDs     *string `gorm:"type:text" json:"-"` // JSON serialized []string of budget IDs applicable to this request
	RateLimitIDs  *string `gorm:"type:text" json:"-"` // JSON serialized []string of rate limit IDs applicable to this request

	// Denormalized token fields for easier querying. cached_read_tokens earns its
	// place because the matviews and token histograms SUM it (see matviews.go and
	// GetTokenHistogram). There is deliberately no cache-write counterpart: nothing
	// aggregates cache writes, and pricing reads the cache breakdown out of
	// token_usage rather than from a column, so it would have had no consumer.
	PromptTokens     int `gorm:"default:0" json:"-"`
	CompletionTokens int `gorm:"default:0" json:"-"`
	TotalTokens      int `gorm:"index:idx_logs_total_tokens;default:0" json:"-"`
	CachedReadTokens int `gorm:"default:0" json:"-"`

	// Served billing tier, denormalized so cost recomputation can reprice a row
	// at the rates it was actually served at. These are deliberately NOT payload
	// fields (see payload.go): they must survive hybrid object-storage offload
	// and content-hidden rows, both of which blank the token_usage column.
	//
	// token_usage cannot carry them — BifrostLLMUsage tags Speed and InferenceGeo
	// `json:"-"`, so they never appear in any serialized usage payload. Without
	// these columns tierFromResponse sees nothing and reprices flex traffic at
	// standard rates.
	// Batch detail for batch_create / batch_retrieve rows and for the aggregate
	// cost row. Like the served-tier fields below, this is deliberately NOT a
	// payload field (see payload.go): request counts and per-model pricing are
	// operational records rather than request content, so they must survive
	// object-storage offload and content-hidden rows.
	BatchDebug string `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostBatchDebug
	// VideoDebug carries the video job id and lifecycle status, and on the aggregate
	// cost row the pricing detail that distinguishes it from the submission it
	// settles. Operational, like BatchDebug — it must survive object-storage offload
	// and content-hidden rows.
	VideoDebug string `gorm:"type:text" json:"-"` // JSON serialized *schemas.BifrostVideoDebug

	ServiceTier  *string `gorm:"type:varchar(32)" json:"service_tier,omitempty"`  // OpenAI served tier, e.g. "priority", "fast", "flex", "ultrafast", or "default"
	Speed        *string `gorm:"type:varchar(32)" json:"speed,omitempty"`         // Anthropic served speed: "fast" / "standard"
	InferenceGeo *string `gorm:"type:varchar(32)" json:"inference_geo,omitempty"` // Anthropic data residency, e.g. "us"

	CreatedAt time.Time `gorm:"index;not null" json:"created_at"`

	// Virtual fields for JSON output - these will be populated when needed
	RoutingEnginesUsed          []string                                `gorm:"-" json:"routing_engines_used,omitempty"` // Virtual field deserialized from JSON
	ToolCallNames               []string                                `gorm:"-" json:"tool_call_names,omitempty"`      // Virtual field split from ToolCallNamesStr
	InputHistoryParsed          []schemas.ChatMessage                   `gorm:"-" json:"input_history,omitempty"`
	ResponsesInputHistoryParsed []schemas.ResponsesMessage              `gorm:"-" json:"responses_input_history,omitempty"`
	OutputMessageParsed         *schemas.ChatMessage                    `gorm:"-" json:"output_message,omitempty"`
	ResponsesOutputParsed       []schemas.ResponsesMessage              `gorm:"-" json:"responses_output,omitempty"`
	EmbeddingInputParsed        []schemas.EmbeddingInputItem            `gorm:"-" json:"embedding_input,omitempty"`
	EmbeddingOutputParsed       []schemas.EmbeddingData                 `gorm:"-" json:"embedding_output,omitempty"`
	RerankOutputParsed          []schemas.RerankResult                  `gorm:"-" json:"rerank_output,omitempty"`
	OCROutputParsed             *schemas.BifrostOCRResponse             `gorm:"-" json:"ocr_output,omitempty"`
	ParamsParsed                interface{}                             `gorm:"-" json:"params,omitempty"`
	ToolsParsed                 []schemas.ChatTool                      `gorm:"-" json:"tools,omitempty"`
	ToolCallsParsed             []schemas.ChatAssistantMessageToolCall  `gorm:"-" json:"tool_calls,omitempty"` // For backward compatibility, tool calls are now in the content
	TokenUsageParsed            *schemas.BifrostLLMUsage                `gorm:"-" json:"token_usage,omitempty"`
	ErrorDetailsParsed          *schemas.BifrostError                   `gorm:"-" json:"error_details,omitempty"`
	SpeechInputParsed           *schemas.SpeechInput                    `gorm:"-" json:"speech_input,omitempty"`
	TranscriptionInputParsed    *schemas.TranscriptionInput             `gorm:"-" json:"transcription_input,omitempty"`
	OCRInputParsed              *schemas.OCRDocument                    `gorm:"-" json:"ocr_input,omitempty"`
	ImageGenerationInputParsed  *schemas.ImageGenerationInput           `gorm:"-" json:"image_generation_input,omitempty"`
	ImageEditInputParsed        *schemas.ImageEditInput                 `gorm:"-" json:"image_edit_input,omitempty"`
	ImageVariationInputParsed   *schemas.ImageVariationInput            `gorm:"-" json:"image_variation_input,omitempty"`
	SpeechOutputParsed          *schemas.BifrostSpeechResponse          `gorm:"-" json:"speech_output,omitempty"`
	TranscriptionOutputParsed   *schemas.BifrostTranscriptionResponse   `gorm:"-" json:"transcription_output,omitempty"`
	ImageGenerationOutputParsed *schemas.BifrostImageGenerationResponse `gorm:"-" json:"image_generation_output,omitempty"`
	// Debug spelling is retained for the established cache and guardrail Go/JSON contracts.
	CacheDebugParsed            *schemas.BifrostCacheMetadata           `gorm:"-" json:"cache_debug,omitempty"`
	BatchDebugParsed            *schemas.BifrostBatchDebug              `gorm:"-" json:"batch_debug,omitempty"`
	VideoDebugParsed            *schemas.BifrostVideoDebug              `gorm:"-" json:"video_debug,omitempty"`
	GuardrailDebugParsed        *schemas.BifrostGuardrailMetadata       `gorm:"-" json:"guardrail_debug,omitempty"`
	RoutingMetadataParsed       *schemas.BifrostRoutingMetadata         `gorm:"-" json:"routing_metadata,omitempty"`
	ListModelsOutputParsed      []schemas.Model                         `gorm:"-" json:"list_models_output,omitempty"`
	MetadataParsed              map[string]interface{}                  `gorm:"-" json:"metadata,omitempty"`
	VideoGenerationInputParsed  *schemas.VideoGenerationInput           `gorm:"-" json:"video_generation_input,omitempty"`
	VideoEditInputParsed        *schemas.VideoEditInput                 `gorm:"-" json:"video_edit_input,omitempty"`
	VideoGenerationOutputParsed *schemas.BifrostVideoGenerationResponse `gorm:"-" json:"video_generation_output,omitempty"`
	VideoRetrieveOutputParsed   *schemas.BifrostVideoGenerationResponse `gorm:"-" json:"video_retrieve_output,omitempty"`
	VideoDownloadOutputParsed   *schemas.BifrostVideoDownloadResponse   `gorm:"-" json:"video_download_output,omitempty"`
	VideoListOutputParsed       *schemas.BifrostVideoListResponse       `gorm:"-" json:"video_list_output,omitempty"`
	VideoDeleteOutputParsed     *schemas.BifrostVideoDeleteResponse     `gorm:"-" json:"video_delete_output,omitempty"`
	LiveSessionParsed           *schemas.LiveSessionLog                 `gorm:"-" json:"live_session,omitempty"`
	AttemptTrailParsed          []schemas.KeyAttemptRecord              `gorm:"-" json:"attempt_trail,omitempty"`
	OverheadBreakdownParsed     []OverheadBucket                        `gorm:"-" json:"overhead_breakdown,omitempty"`
	BudgetIDsParsed             []string                                `gorm:"-" json:"budget_ids,omitempty"`
	RateLimitIDsParsed          []string                                `gorm:"-" json:"rate_limit_ids,omitempty"`
	TeamIDsParsed               []string                                `gorm:"-" json:"team_ids,omitempty"`
	TeamNamesParsed             []string                                `gorm:"-" json:"team_names,omitempty"`
	CustomerIDsParsed           []string                                `gorm:"-" json:"customer_ids,omitempty"`
	CustomerNamesParsed         []string                                `gorm:"-" json:"customer_names,omitempty"`
	BusinessUnitIDsParsed       []string                                `gorm:"-" json:"business_unit_ids,omitempty"`
	BusinessUnitNamesParsed     []string                                `gorm:"-" json:"business_unit_names,omitempty"`

	// Populated in handlers after find using the virtual key id and key id
	VirtualKey  *tables.TableVirtualKey  `gorm:"-" json:"virtual_key,omitempty"`  // redacted
	SelectedKey *schemas.Key             `gorm:"-" json:"selected_key,omitempty"` // redacted
	RoutingRule *tables.TableRoutingRule `gorm:"-" json:"routing_rule,omitempty"` // redacted
	// contains filtered or unexported fields
}

Log represents a complete log entry for a request/response cycle This is the GORM model with appropriate tags

func NewLogEntryFromMap added in v1.2.9 

func NewLogEntryFromMap(entry map[string]interface{}) *Log

NewLogEntryFromMap creates a new Log from a map[string]interface{}

func (*Log) AfterFind 

func (l *Log) AfterFind(tx *gorm.DB) error

AfterFind GORM hook to deserialize JSON fields

func (*Log) BeforeCreate 

func (l *Log) BeforeCreate(tx *gorm.DB) error

BeforeCreate GORM hook to set created_at and serialize JSON fields

func (*Log) BuildContentSummary 

func (l *Log) BuildContentSummary() string

BuildContentSummary creates a searchable text summary

func (*Log) BuildInputContentSummary added in v1.3.2 

func (l *Log) BuildInputContentSummary() string

BuildInputContentSummary extracts the last user message text from input fields. This is used in hybrid mode for the content_summary column, which powers full-text search and serves as a display fallback in the log list table. Only the last message is kept — the full conversation history lives in object storage and is merged back on FindByID.

func (*Log) DeserializeFields 

func (l *Log) DeserializeFields() error

DeserializeFields converts JSON strings back to Go structs

func (*Log) IsUsageDegraded added in v1.5.5 

func (l *Log) IsUsageDegraded() bool

IsUsageDegraded reports whether TokenUsageParsed is the lossy stub rebuilt from denormalized columns instead of the real token_usage payload.

It exists for billing. The stub carries only prompt/completion/total plus the cached read/write totals, and PromptTokens is inclusive of the cache buckets — so pricing a stub charges every cached token at the full input rate and can inflate a cache-heavy request several fold. Callers that compute money must skip these rows rather than price them; callers that render tokens (the log list, the UI) are free to use the stub, which is what it was built for.

func (*Log) PassthroughObjectType added in v1.10.0 

func (l *Log) PassthroughObjectType() string

PassthroughObjectType returns the object type a row had before passthrough typing: passthrough or passthrough_stream for a passthrough row stored under its inferred type, Object otherwise. Settings keyed by request type (object-storage exclusions) use it so an exclusion of passthrough keeps covering every passthrough call.

func (*Log) SerializeFields 

func (l *Log) SerializeFields() error

SerializeFields converts Go structs to JSON strings for storage

func (Log) TableName 

func (Log) TableName() string

TableName sets the table name for GORM

type LogRetentionManager added in v1.1.36 

type LogRetentionManager interface {
	DeleteLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
}

LogRetentionManager defines the interface for managing log retention and deletion

type LogStore 

type LogStore interface {
	// WarpConversationStore is Warp's saved-chat surface. Transcripts live here
	// rather than in the config store because they are user-generated content
	// that grows with use, not settings an install depends on.
	WarpConversationStore
	// WarpTopicStore is where Warp's topics, and each request's place among
	// them, are kept. See warptopics.go.
	WarpTopicStore

	Ping(ctx context.Context) error
	Create(ctx context.Context, entry *Log) error
	CreateIfNotExists(ctx context.Context, entry *Log) error
	BatchCreateIfNotExists(ctx context.Context, entries []*Log) error
	FindByID(ctx context.Context, id string) (*Log, error)
	IsLogEntryPresent(ctx context.Context, id string) (bool, error)
	FindFirst(ctx context.Context, query any, fields ...string) (*Log, error)
	FindAll(ctx context.Context, query any, fields ...string) ([]*Log, error)
	FindAllDistinct(ctx context.Context, query any, fields ...string) ([]*Log, error)
	HasLogs(ctx context.Context) (bool, error)
	SearchLogs(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)
	// SearchLogsForBilling is SearchLogs projected for cost recomputation: exactly the
	// columns pricing reads and nothing else, with each modality payload pulled only
	// for the request types that bill on it.
	//
	// It does NOT hydrate offloaded payloads — that would put every row's payload in
	// memory at once. Callers walk the result in BillingHydrationChunkSize slices,
	// calling HydrateBillingChunk and then ReleaseBillingPayloads on each.
	SearchLogsForBilling(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)
	// HydrateBillingChunk restores offloaded pricing inputs for a small slice of rows.
	// It skips rows that already carry everything pricing needs, so a store with
	// nothing offloaded performs no I/O at all.
	//
	// BillingHydrationResult.Unpriceable carries the IDs whose inputs could not be
	// recovered — for example, a missing object or unavailable object storage. Callers
	// must skip those rather than price them: the
	// denormalized fallback usage omits the cache breakdown, and pricing it charges
	// every cached token at the full input rate. Hydrated carries the IDs actually
	// fetched, which are the only rows worth passing to BulkBackfillBillingPayloads.
	//
	// Pass at most BillingHydrationChunkSize rows and release them before requesting
	// more; the whole point is to bound how many payloads are resident at once.
	HydrateBillingChunk(ctx context.Context, logs []*Log) (BillingHydrationResult, error)
	// BulkBackfillBillingPayloads writes pricing inputs recovered from object storage
	// back into their rows, so a later recompute reads them from the database instead
	// of fetching the object again.
	//
	// This makes recompute self-healing: the first pass over a window pays the object
	// fetches, and every pass after it is served entirely from the DB. It is
	// opportunistic by design — only rows that were actually fetched get backfilled, so
	// there is no table-wide migration and no scan.
	//
	// Callers should treat a failure as non-fatal: the cost update is the job's real
	// output, and a missed backfill only means the next run fetches again.
	BulkBackfillBillingPayloads(ctx context.Context, updates map[string]BillingPayloadBackfill) error
	GetSessionLogs(ctx context.Context, sessionID string, pagination PaginationOptions) (*SessionDetailResult, error)
	GetSessionSummary(ctx context.Context, sessionID string) (*SessionSummaryResult, error)
	GetStats(ctx context.Context, filters SearchFilters) (*SearchStats, error)
	GetHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*HistogramResult, error)
	GetTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*TokenHistogramResult, error)
	GetCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*CostHistogramResult, error)
	GetModelHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ModelHistogramResult, error)
	GetLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*LatencyHistogramResult, error)
	GetProviderCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderCostHistogramResult, error)
	GetProviderTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderTokenHistogramResult, error)
	GetProviderLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderLatencyHistogramResult, error)
	// GetThroughputHistogram returns time-bucketed token-generation throughput (tokens/sec).
	GetThroughputHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ThroughputHistogramResult, error)
	// GetProviderThroughputHistogram returns time-bucketed tokens/sec with provider breakdown.
	GetProviderThroughputHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderThroughputHistogramResult, error)
	GetModelRankings(ctx context.Context, filters SearchFilters) (*ModelRankingResult, error)
	GetUserRankings(ctx context.Context, filters SearchFilters) (*UserRankingResult, error)
	// GetUserSpend returns each user's total cost inside the filter window in one
	// query: no previous-period comparison, no ordering, no row limit. It is the cheap
	// read for jobs that rank every user by spend.
	GetUserSpend(ctx context.Context, filters SearchFilters) ([]UserSpendEntry, error)
	GetDimensionRankings(ctx context.Context, filters SearchFilters, dimension RankingDimension) (*DimensionRankingResult, error)
	// GetDimensionUsage returns each entity's requests, tokens and cost on a rollup
	// dimension in one read, attributed exactly as GetDimensionRankings attributes
	// them. It skips what the rankings add for the dashboard (ordering, row limit,
	// request totals, the "Other" bucket); with compare set, the same read covers
	// the previous window and fills each entry's Trend.
	GetDimensionUsage(ctx context.Context, filters SearchFilters, dimension RankingDimension, compare bool) ([]DimensionUsageEntry, error)
	// GetDimensionModelUsage returns requests and cost per (entity, model,
	// provider) on a rollup dimension in one read, for callers that need the model
	// mix of many entities at once.
	GetDimensionModelUsage(ctx context.Context, filters SearchFilters, dimension RankingDimension) ([]DimensionModelUsageEntry, error)
	// GetDimensionCostHistogram returns time-bucketed cost data grouped by the specified dimension (e.g., team_id, customer_id).
	GetDimensionCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionCostHistogramResult, error)
	// GetDimensionTokenHistogram returns time-bucketed token usage grouped by the specified dimension.
	GetDimensionTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionTokenHistogramResult, error)
	// GetDimensionLatencyHistogram returns time-bucketed latency percentiles grouped by the specified dimension.
	GetDimensionLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionLatencyHistogramResult, error)
	// GetNodeUsageAfter returns cumulative usage for rows after the provided stable
	// cursor. When the cursor has both timestamp and log ID, rows with the same
	// timestamp but greater log ID are included to avoid skipping same-timestamp rows.
	GetNodeUsageAfter(ctx context.Context, nodeID string, cursor NodeUsageCursor) (*NodeUsageAggregate, error)
	Update(ctx context.Context, id string, entry any) error
	// BatchUpdate applies the non-zero fields of each entry onto the existing row
	// with that ID; rows that do not exist are skipped, never inserted.
	// content_hidden is the exception: it is always written from the entry, since
	// it carries the request's final visibility decision and must be able to
	// clear a flag saved earlier.
	BatchUpdate(ctx context.Context, entries []*Log) error
	BulkUpdateCost(ctx context.Context, updates map[string]CostUpdate) error
	Flush(ctx context.Context, since time.Time) error
	Close(ctx context.Context) error
	DeleteLog(ctx context.Context, id string) error
	DeleteLogs(ctx context.Context, ids []string) error
	DeleteLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)

	CreateUserAgentMapping(ctx context.Context, mapping *UserAgentMapping) error
	UpdateUserAgentMapping(ctx context.Context, id string, mapping *UserAgentMapping) error
	DeleteUserAgentMapping(ctx context.Context, id string) error
	ListUserAgentMappings(ctx context.Context, activeOnly bool) ([]UserAgentMapping, error)

	// Distinct value methods for filter data
	GetDistinctModels(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctAliases(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctKeyPairs(ctx context.Context, idCol, nameCol string, limit int, query string) ([]KeyPairResult, error)
	GetDistinctRoutingEngines(ctx context.Context, limit int, query string) ([]string, error)
	// GetDistinctToolCallNames returns distinct function names that responses called, for the "Tool calls" filter.
	GetDistinctToolCallNames(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctStopReasons(ctx context.Context, limit int, query string) ([]string, error)
	// GetDistinctUserAgents returns distinct raw User-Agent strings from logs for the "App" filter.
	GetDistinctUserAgents(ctx context.Context, limit int, query string) ([]string, error)
	// GetDistinctApps returns distinct backend-detected app labels from logs.
	GetDistinctApps(ctx context.Context, limit int, query string) ([]string, error)
	GetDistinctMetadataKeys(ctx context.Context, limit int, query string) (map[string][]string, error)

	// MCP Tool Log histogram methods
	GetMCPHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPHistogramResult, error)
	GetMCPCostHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPCostHistogramResult, error)
	GetMCPTopTools(ctx context.Context, filters MCPToolLogSearchFilters, limit int) (*MCPTopToolsResult, error)
	// GetMCPToolCountsByDimension returns how many distinct tools each user,
	// team, customer or business unit called, in one read.
	GetMCPToolCountsByDimension(ctx context.Context, filters MCPToolLogSearchFilters, dimension RankingDimension) (map[string]int, error)

	// MCP Tool Log methods
	CreateMCPToolLog(ctx context.Context, entry *MCPToolLog) error
	BatchCreateMCPToolLogsIfNotExists(ctx context.Context, entries []*MCPToolLog) error
	FindMCPToolLog(ctx context.Context, id string) (*MCPToolLog, error)
	UpdateMCPToolLog(ctx context.Context, id string, entry any) error
	SearchMCPToolLogs(ctx context.Context, filters MCPToolLogSearchFilters, pagination PaginationOptions) (*MCPToolLogSearchResult, error)
	GetMCPToolLogStats(ctx context.Context, filters MCPToolLogSearchFilters) (*MCPToolLogStats, error)
	HasMCPToolLogs(ctx context.Context) (bool, error)
	DeleteMCPToolLogs(ctx context.Context, ids []string) error
	// DeleteMCPToolLogsBatch deletes up to batchSize MCP tool logs older than
	// cutoff, oldest first, for the retention cleaner (see LogsCleaner).
	DeleteMCPToolLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
	FlushMCPToolLogs(ctx context.Context, since time.Time) error
	GetAvailableToolNames(ctx context.Context, limit int, query string) ([]string, error)
	GetAvailableServerLabels(ctx context.Context, limit int, query string) ([]string, error)
	// GetAvailableMCPUserAgents returns distinct raw User-Agent strings from MCP tool logs for the "App" filter.
	GetAvailableMCPUserAgents(ctx context.Context, limit int, query string) ([]string, error)
	// GetAvailableMCPApps returns distinct backend-detected app labels from MCP tool logs.
	GetAvailableMCPApps(ctx context.Context, limit int, query string) ([]string, error)
	GetAvailableMCPVirtualKeys(ctx context.Context, limit int, query string) ([]MCPToolLog, error)

	// Agent Gateway log methods.
	BatchCreateAgentLogsIfNotExists(ctx context.Context, entries []*AgentLog) ([]string, error)
	// ReconcileAgentCorrelation fills missing task and context IDs from persisted
	// rows related to the inserted entries. Existing values are never changed.
	ReconcileAgentCorrelation(ctx context.Context, entries []*AgentLog) error
	FindAgentLog(ctx context.Context, id string) (*AgentLog, error)
	FindAgentLogsForDeletion(ctx context.Context, ids []string) ([]*AgentLog, error)
	ListAgentLogHistory(ctx context.Context, filter AgentLogHistoryFilter, pagination PaginationOptions) (*AgentLogHistoryResult, error)
	ListAgentLogOperations(ctx context.Context, filter AgentLogHistoryFilter, pagination PaginationOptions) (*AgentLogOperationResult, error)
	FindAgentLogOperation(ctx context.Context, id string) (*AgentLogOperation, error)
	GetAgentLogStats(ctx context.Context, filter AgentLogHistoryFilter) (*AgentLogStats, error)
	GetAgentHistogram(ctx context.Context, filter AgentLogHistoryFilter, bucketSizeSeconds int64) (*AgentHistogramResult, error)
	GetAgentTopAgents(ctx context.Context, filter AgentLogHistoryFilter, limit int) (*AgentTopAgentsResult, error)
	GetAgentFilterData(ctx context.Context, dimensions []string, limit int, query string) (*AgentFilterData, error)
	UpdateAgentLog(ctx context.Context, id string, entry any) error
	// DeleteAgentLogs deletes the identified rows together with every row sharing
	// their request IDs, so an operation's correlated stream events never
	// outlive the aggregate request row shown in the UI.
	DeleteAgentLogs(ctx context.Context, ids []string) error
	FlushAgentLogs(ctx context.Context, since time.Time) error

	// Relay log methods (Relay Logs).
	BatchCreateRelayLogsIfNotExists(ctx context.Context, entries []*RelayLog) ([]string, error)
	FindRelayLog(ctx context.Context, id string) (*RelayLog, error)
	FindRelayLogsForDeletion(ctx context.Context, ids []string) ([]*RelayLog, error)
	UpdateRelayLog(ctx context.Context, id string, updates map[string]any) error
	SearchRelayLogs(ctx context.Context, filters RelayLogFilters, pagination PaginationOptions) (*RelayLogSearchResult, error)
	GetRelayLogStats(ctx context.Context, filters RelayLogFilters) (*RelayLogStats, error)
	GetRelayHistogram(ctx context.Context, filters RelayLogFilters, bucketSizeSeconds int64) (*RelayHistogramResult, error)
	GetRelayTopEndpoints(ctx context.Context, filters RelayLogFilters, limit int) (*RelayTopResults, error)
	GetRelayFilterData(ctx context.Context, dimensions []string, limit int, search string) (*RelayFilterData, error)
	HasRelayLogs(ctx context.Context) (bool, error)
	DeleteRelayLogs(ctx context.Context, ids []string) error
	DeleteRelayLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

	// Async Job methods
	CreateAsyncJob(ctx context.Context, job *AsyncJob) error
	FindAsyncJobByID(ctx context.Context, id string) (*AsyncJob, error)
	UpdateAsyncJob(ctx context.Context, id string, updates map[string]interface{}) error
	DeleteExpiredAsyncJobs(ctx context.Context) (int64, error)
	DeleteStaleAsyncJobs(ctx context.Context, staleSince time.Time) (int64, error)

	// Webhook Delivery methods
	CreateWebhookDelivery(ctx context.Context, delivery *WebhookDelivery) error
	FindWebhookDeliveryByID(ctx context.Context, id string) (*WebhookDelivery, error)
	SearchWebhookDeliveries(ctx context.Context, filters *WebhookDeliverySearchFilters, pagination PaginationOptions) (*WebhookDeliverySearchResult, error)
	DeleteExpiredWebhookDeliveries(ctx context.Context) (int64, error)
}

LogStore is the interface for the log store.

func NewLogStore 

func NewLogStore(ctx context.Context, config *Config, logger schemas.Logger) (LogStore, error)

NewLogStore creates a new log store based on the configuration. When ObjectStorage is configured, the returned store is wrapped with a HybridLogStore that offloads payloads to S3-compatible object storage.

type LogStoreType 

type LogStoreType string

LogStoreType represents the type of log store. 

const (
	LogStoreTypeSQLite     LogStoreType = "sqlite"
	LogStoreTypePostgres   LogStoreType = "postgres"
	LogStoreTypeClickHouse LogStoreType = "clickhouse"
)

LogStoreTypeSQLite is the type of log store for SQLite.

type LogsCleaner added in v1.1.36 

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

LogsCleaner manages the cleanup of old logs

func NewLogsCleaner added in v1.1.36 

func NewLogsCleaner(manager LogRetentionManager, config CleanerConfig, logger schemas.Logger) *LogsCleaner

NewLogsCleaner creates a new LogsCleaner instance

func (*LogsCleaner) RetentionDays added in v1.11.0 

func (c *LogsCleaner) RetentionDays() int

RetentionDays is the retention period the next cleanup pass will use.

func (*LogsCleaner) StartCleanupRoutine added in v1.1.36 

func (c *LogsCleaner) StartCleanupRoutine()

StartCleanupRoutine starts a goroutine that periodically cleans up old logs

func (*LogsCleaner) StopCleanupRoutine added in v1.1.36 

func (c *LogsCleaner) StopCleanupRoutine()

StopCleanupRoutine gracefully stops the cleanup goroutine

func (*LogsCleaner) UpdateRetentionDays added in v1.9.0 

func (c *LogsCleaner) UpdateRetentionDays(retentionDays int)

UpdateRetentionDays updates the retention period used by subsequent cleanup passes. A pass already in progress keeps its cutoff for both log tables.

type MCPCostHistogramBucket added in v1.2.31 

type MCPCostHistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	TotalCost float64   `json:"total_cost"`
}

MCPCostHistogramBucket represents a single time bucket for MCP cost data

type MCPCostHistogramResult added in v1.2.31 

type MCPCostHistogramResult struct {
	Buckets           []MCPCostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                    `json:"bucket_size_seconds"`
}

MCPCostHistogramResult represents the MCP cost histogram query result

type MCPHistogramBucket added in v1.2.31 

type MCPHistogramBucket struct {
	Timestamp time.Time `json:"timestamp"`
	Count     int64     `json:"count"`
	Success   int64     `json:"success"`
	Error     int64     `json:"error"`
}

MCPHistogramBucket represents a single time bucket for MCP tool call volume

type MCPHistogramResult added in v1.2.31 

type MCPHistogramResult struct {
	Buckets           []MCPHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                `json:"bucket_size_seconds"`
}

MCPHistogramResult represents the MCP tool call volume histogram query result

type MCPToolLog added in v1.2.17 

type MCPToolLog struct {
	// Governance names are snapshots recorded beside their IDs at ingestion, the
	// way the logs table records them. They are what the entity was called when
	// the call was made, so a later rename or deletion leaves the row readable.
	UserName         *string `gorm:"type:varchar(255)" json:"user_name,omitempty"`
	TeamName         *string `gorm:"type:varchar(255)" json:"team_name,omitempty"`
	CustomerName     *string `gorm:"type:varchar(255)" json:"customer_name,omitempty"`
	BusinessUnitName *string `gorm:"type:varchar(255)" json:"business_unit_name,omitempty"`

	// Multi-valued attribution, mirroring the logs table. Each names column is
	// index-aligned with its ids column — names[i] names ids[i] — which is what
	// lets a reader filter the two together; they are always written as a pair.
	// Budgets and rate limits are ids only here, as they are on logs: neither
	// carries a display name.
	TeamIDs           *string `gorm:"type:text" json:"-"` // JSON serialized []string
	TeamNames         *string `gorm:"type:text" json:"-"` // JSON serialized []string
	CustomerIDs       *string `gorm:"type:text" json:"-"` // JSON serialized []string
	CustomerNames     *string `gorm:"type:text" json:"-"` // JSON serialized []string
	BusinessUnitIDs   *string `gorm:"type:text" json:"-"` // JSON serialized []string
	BusinessUnitNames *string `gorm:"type:text" json:"-"` // JSON serialized []string
	BudgetIDs         *string `gorm:"type:text" json:"-"` // JSON serialized []string
	RateLimitIDs      *string `gorm:"type:text" json:"-"` // JSON serialized []string

	ID                 string    `gorm:"primaryKey;type:varchar(255)" json:"id"`
	RequestID          string    `gorm:"type:varchar(255);column:request_id;index:idx_mcp_logs_request_id" json:"request_id,omitempty"`             // The original request ID from context
	LLMRequestID       *string   `gorm:"type:varchar(255);column:llm_request_id;index:idx_mcp_logs_llm_request_id" json:"llm_request_id,omitempty"` // Links to the LLM request that triggered this tool call
	SessionID          *string   `gorm:"type:varchar(255);index:idx_mcp_logs_session_id,where:session_id IS NOT NULL" json:"session_id,omitempty"`
	AgentCorrelationID *string   `` /* 141-byte string literal not displayed */
	Timestamp          time.Time `` /* 150-byte string literal not displayed */
	ToolName           string    `gorm:"type:varchar(255);index:idx_mcp_logs_tool_name;not null" json:"tool_name"`
	ServerLabel        string    `gorm:"type:varchar(255);index:idx_mcp_logs_server_label" json:"server_label,omitempty"` // MCP server that provided the tool
	VirtualKeyID       *string   `gorm:"type:varchar(255);index:idx_mcp_logs_vk_ts,priority:1" json:"virtual_key_id"`     // (virtual_key_id, timestamp) composite; replaces idx_mcp_logs_virtual_key_id
	VirtualKeyName     *string   `gorm:"type:varchar(255)" json:"virtual_key_name"`
	UserID             *string   `gorm:"type:varchar(255);index:idx_mcp_logs_user_ts,priority:1" json:"user_id"` // (user_id, timestamp) composite; replaces idx_mcp_logs_user_id
	TeamID             *string   `gorm:"type:varchar(255);index:idx_mcp_logs_team_ts,priority:1" json:"team_id"` // (team_id, timestamp) composite; replaces idx_mcp_logs_team_id
	CustomerID         *string   `gorm:"type:varchar(255);index:idx_mcp_logs_customer_id" json:"customer_id"`
	BusinessUnitID     *string   `gorm:"type:varchar(255);index:idx_mcp_logs_business_unit_id" json:"business_unit_id"`
	ProjectID          *string   `gorm:"type:varchar(255);index:idx_mcp_logs_project_id" json:"project_id"`
	ProjectName        *string   `gorm:"type:varchar(255)" json:"project_name"`
	UserAgent          *string   `gorm:"type:varchar(512);index:idx_mcp_logs_user_agent" json:"user_agent,omitempty"` // Raw HTTP User-Agent of the calling client
	App                *string   `gorm:"type:varchar(128);index:idx_mcp_logs_app" json:"app,omitempty"`               // Backend-detected client app derived from user_agent
	Arguments          string    `gorm:"type:text" json:"-"`                                                          // JSON serialized tool arguments
	Result             string    `gorm:"type:text" json:"-"`                                                          // JSON serialized tool result
	ErrorDetails       string    `gorm:"type:text" json:"-"`                                                          // JSON serialized *schemas.BifrostError
	Latency            *float64  `gorm:"index:idx_mcp_logs_latency" json:"latency,omitempty"`                         // Execution time in milliseconds
	Cost               *float64  `gorm:"index:idx_mcp_logs_cost" json:"cost,omitempty"`                               // Cost in dollars (per execution cost)
	Status             string    `gorm:"type:varchar(50);index:idx_mcp_logs_status;not null" json:"status"`           // "processing", "success", or "error"
	Metadata           string    `gorm:"type:text" json:"-"`                                                          // JSON serialized map[string]interface{}
	PluginLogs         string    `gorm:"type:text" json:"plugin_logs,omitempty"`                                      // JSON serialized plugin logs grouped by plugin name
	HasObject          bool      `gorm:"default:false" json:"-"`                                                      // True when payload is stored in object storage
	CreatedAt          time.Time `gorm:"index;not null" json:"created_at"`

	RedactionData          *schemas.RedactionData        `gorm:"-" json:"-"`                           // Transient guardrail redaction data consumed by enterprise logstore wrappers
	RedactionMapping       string                        `gorm:"type:text" json:"-"`                   // Reversible redaction mapping written by enterprise logstore wrappers; deleted with the row
	RevealRedactionMapping *schemas.RedactionMapsByPhase `gorm:"-" json:"redaction_mapping,omitempty"` // Virtual field populated only on permitted MCP log-detail reads

	// Endpoint-agent context. These are populated for tool calls observed on a
	// developer machine by the Bifrost Edge agent (rather than proxied by the
	// gateway). Source distinguishes the origin: empty/null for gateway-proxied
	// calls, "endpoint" for agent-observed MCP calls, "native" for harness tools.
	DeviceID *string `gorm:"type:varchar(255);index:idx_mcp_logs_device_id" json:"device_id,omitempty"`
	AppKey   *string `gorm:"type:varchar(64)" json:"app_key,omitempty"` // Canonical policy key of the detected client app (schemas.AppKeyFromName), e.g. "claude-code"; a slug like App, not a secret or credential
	Decision *string `gorm:"type:varchar(16)" json:"decision,omitempty"`
	Source   *string `gorm:"type:varchar(16);index:idx_mcp_logs_source" json:"source,omitempty"`

	// Method is the MCP method for a prompt or resource read ("prompts/get", "resources/read"),
	// whose prompt name or resource URI is in ToolName; nil for a tool call.
	Method *string `gorm:"type:varchar(32)" json:"method,omitempty"`

	// Virtual fields for JSON output - populated when needed
	TeamIDsParsed           []string                `gorm:"-" json:"team_ids,omitempty"`
	TeamNamesParsed         []string                `gorm:"-" json:"team_names,omitempty"`
	CustomerIDsParsed       []string                `gorm:"-" json:"customer_ids,omitempty"`
	CustomerNamesParsed     []string                `gorm:"-" json:"customer_names,omitempty"`
	BusinessUnitIDsParsed   []string                `gorm:"-" json:"business_unit_ids,omitempty"`
	BusinessUnitNamesParsed []string                `gorm:"-" json:"business_unit_names,omitempty"`
	BudgetIDsParsed         []string                `gorm:"-" json:"budget_ids,omitempty"`
	RateLimitIDsParsed      []string                `gorm:"-" json:"rate_limit_ids,omitempty"`
	ArgumentsParsed         interface{}             `gorm:"-" json:"arguments,omitempty"`
	ResultParsed            interface{}             `gorm:"-" json:"result,omitempty"`
	ErrorDetailsParsed      *schemas.BifrostError   `gorm:"-" json:"error_details,omitempty"`
	MetadataParsed          map[string]interface{}  `gorm:"-" json:"metadata,omitempty"`
	VirtualKey              *tables.TableVirtualKey `gorm:"-" json:"virtual_key,omitempty"`
}

MCPToolLog represents a log entry for MCP tool executions This is separate from the main Log table since MCP tool calls have different fields

func (*MCPToolLog) AfterFind added in v1.2.17 

func (l *MCPToolLog) AfterFind(tx *gorm.DB) error

AfterFind GORM hook to deserialize JSON fields

func (*MCPToolLog) ApplyGovernanceContext added in v1.7.0 

func (l *MCPToolLog) ApplyGovernanceContext(ctx *schemas.BifrostContext)

ApplyGovernanceContext records the request's governance attribution on the entry: every id the request settled, and the name that id had at the time.

The names are snapshots, not a cache of the current directory. That is the whole point of writing them here rather than resolving them when the log is read: a row keeps saying who made the call after the team is renamed or the key is deleted, and it says it without a lookup.

Two rules follow from that. A value the context does not carry leaves whatever is already on the entry alone, so a later hook stamping a partially settled identity cannot blank what an earlier one knew. And changing an id clears the name beside it, because a name belongs to the id it was read with — an id paired with some other entity's name is worse than an id with no name at all.

func (*MCPToolLog) BeforeCreate added in v1.2.17 

func (l *MCPToolLog) BeforeCreate(tx *gorm.DB) error

BeforeCreate GORM hook to set created_at and serialize JSON fields

func (*MCPToolLog) DeserializeFields added in v1.2.17 

func (l *MCPToolLog) DeserializeFields() error

DeserializeFields converts JSON strings back to Go structs

func (*MCPToolLog) SerializeFields added in v1.2.17 

func (l *MCPToolLog) SerializeFields() error

SerializeFields converts Go structs to JSON strings for storage

func (MCPToolLog) TableName added in v1.2.17 

func (MCPToolLog) TableName() string

TableName sets the table name for GORM

type MCPToolLogRetentionManager added in v1.9.0 

type MCPToolLogRetentionManager interface {
	DeleteMCPToolLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
}

MCPToolLogRetentionManager is implemented by stores that can also expire mcp_tool_logs rows. It is a separate, optional interface so wrappers that only implement LogRetentionManager keep compiling; the cleaner applies MCP retention when the manager it was given implements this too.

type MCPToolLogSearchFilters added in v1.2.17 

type MCPToolLogSearchFilters struct {
	UserIDs         []string `json:"user_ids,omitempty"`
	TeamIDs         []string `json:"team_ids,omitempty"`
	CustomerIDs     []string `json:"customer_ids,omitempty"`
	BusinessUnitIDs []string `json:"business_unit_ids,omitempty"`
	ProjectIDs      []string `json:"project_ids,omitempty"`
	DeviceIDs       []string `json:"device_ids,omitempty"`

	ToolNames          []string   `json:"tool_names,omitempty"`
	ServerLabels       []string   `json:"server_labels,omitempty"`
	Status             []string   `json:"status,omitempty"`
	VirtualKeyIDs      []string   `json:"virtual_key_ids,omitempty"`
	LLMRequestIDs      []string   `json:"llm_request_ids,omitempty"`
	AgentNames         []string   `json:"agent_names,omitempty"`
	SessionID          string     `json:"session_id,omitempty"`
	AgentCorrelationID string     `json:"agent_correlation_id,omitempty"`
	Apps               []string   `json:"apps,omitempty"`        // Backend-detected client apps
	UserAgents         []string   `json:"user_agents,omitempty"` // Raw User-Agent strings; kept for compatibility/debug filtering
	StartTime          *time.Time `json:"start_time,omitempty"`
	EndTime            *time.Time `json:"end_time,omitempty"`
	MinLatency         *float64   `json:"min_latency,omitempty"`
	MaxLatency         *float64   `json:"max_latency,omitempty"`
	ContentSearch      string     `json:"content_search,omitempty"`
}

MCPToolLogSearchFilters represents the available filters for MCP tool log searches

type MCPToolLogSearchResult added in v1.2.17 

type MCPToolLogSearchResult struct {
	Logs       []MCPToolLog      `json:"logs"`
	Pagination PaginationOptions `json:"pagination"`
	HasLogs    bool              `json:"has_logs"`
}

MCPToolLogSearchResult represents the result of an MCP tool log search

type MCPToolLogStats added in v1.2.17 

type MCPToolLogStats struct {
	TotalExecutions int64   `json:"total_executions"`
	SuccessRate     float64 `json:"success_rate"`
	AverageLatency  float64 `json:"average_latency"`
	TotalCost       float64 `json:"total_cost"` // Total cost in dollars
}

MCPToolLogStats represents statistics for MCP tool log searches

type MCPTopToolResult added in v1.2.31 

type MCPTopToolResult struct {
	ToolName string  `json:"tool_name"`
	Count    int64   `json:"count"`
	Cost     float64 `json:"cost"`
}

MCPTopToolResult represents a single tool's aggregated stats

type MCPTopToolsResult added in v1.2.31 

type MCPTopToolsResult struct {
	Tools []MCPTopToolResult `json:"tools"`
}

MCPTopToolsResult represents the top N MCP tools by call count

type MaintenanceGate added in v1.9.0 

type MaintenanceGate interface {
	// MigrationInProgress reports whether the migration advisory lock is held
	// by some session. It never blocks for long and fails open: any error,
	// timeout, or non-Postgres dialect reports false.
	MigrationInProgress(ctx context.Context) bool
}

MaintenanceGate is implemented by stores that can tell whether another node is currently running logstore schema migrations. Background writers consult it before touching the logs table so their statements do not queue behind a pending ALTER TABLE and turn one node's rollout into a cluster-wide stall.

It is deliberately NOT part of LogStore: callers type-assert for it, so a store (or a test double embedding LogStore) that lacks it simply has no gate and behaves exactly as before.

type MatViewPauseOptions added in v1.10.0 

type MatViewPauseOptions struct {
	// CancelAfter is how long to wait for a running refresh pass before
	// cancelling its REFRESH statements. Zero or negative never cancels: the
	// pause then waits for the pass to finish on its own.
	CancelAfter time.Duration
}

MatViewPauseOptions tunes PauseMatViewMaintenance.

func MigrationMatViewPauseOptions added in v1.10.0 

func MigrationMatViewPauseOptions(cfg *Config, logger schemas.Logger) MatViewPauseOptions

MigrationMatViewPauseOptions returns the matview pause options a log store config asks for: its migration_matview_cancel_after when cfg is a Postgres log store, and the defaults otherwise. Other stores' migrations (the config store, enterprise tables) share the database with the log store and call this so the one setting governs every migration's pause.

type ModelHistogramBucket added in v1.2.13 

type ModelHistogramBucket struct {
	Timestamp time.Time                  `json:"timestamp"`
	ByModel   map[string]ModelUsageStats `json:"by_model"`
}

ModelHistogramBucket represents a single time bucket for model usage

type ModelHistogramResult added in v1.2.13 

type ModelHistogramResult struct {
	Buckets           []ModelHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                  `json:"bucket_size_seconds"`
	Models            []string               `json:"models"`
}

ModelHistogramResult represents the model histogram query result

type ModelRankingEntry added in v1.2.31 

type ModelRankingEntry struct {
	Model              string  `json:"model"`
	CanonicalModelName *string `json:"canonical_model_name,omitempty"`
	Provider           string  `json:"provider"`
	TotalRequests      int64   `json:"total_requests"`
	SuccessCount       int64   `json:"success_count"`
	SuccessRate        float64 `json:"success_rate"`
	TotalTokens        int64   `json:"total_tokens"`
	TotalCost          float64 `json:"total_cost"`
	// Per-category cost split; sums to TotalCost. AdditionalCost holds internal
	// sidecar costs with no input/output token category (guardrail, MCP).
	InputCost      float64 `json:"input_cost"`
	OutputCost     float64 `json:"output_cost"`
	AdditionalCost float64 `json:"additional_cost"`
	AvgLatency     float64 `json:"avg_latency"`
	// Throughput is aggregate token-generation rate (tokens/sec) for this model:
	// SUM(completion_tokens) / (SUM(latency_ms)/1000) over successful rows with
	// latency > 0 — the same definition as the throughput histogram.
	Throughput float64 `json:"throughput"`
}

ModelRankingEntry represents aggregated stats for a single model over a time period.

type ModelRankingResult added in v1.2.31 

type ModelRankingResult struct {
	Rankings []ModelRankingWithTrend `json:"rankings"`
}

ModelRankingResult is the response for the model rankings endpoint.

type ModelRankingTrend added in v1.2.31 

type ModelRankingTrend struct {
	HasPreviousPeriod bool     `json:"has_previous_period"`
	RequestsTrend     float64  `json:"requests_trend"`
	TokensTrend       *float64 `json:"tokens_trend"`
	CostTrend         *float64 `json:"cost_trend"`
	LatencyTrend      float64  `json:"latency_trend"`
	ThroughputTrend   float64  `json:"throughput_trend"`
}

ModelRankingTrend represents the percentage change compared to the previous period. TokensTrend and CostTrend are nil when the previous period had none of that metric but this one does - there is no percentage to report, and 0 would claim the metric held steady.

type ModelRankingWithTrend added in v1.2.31 

type ModelRankingWithTrend struct {
	ModelRankingEntry
	Trend ModelRankingTrend `json:"trend"`
}

ModelRankingWithTrend combines ranking entry with trend data.

type ModelUsageStats added in v1.2.13 

type ModelUsageStats struct {
	Total     int64 `json:"total"`
	Success   int64 `json:"success"`
	Error     int64 `json:"error"`
	Cancelled int64 `json:"cancelled"`
}

ModelUsageStats represents usage statistics for a single model

type NodeUsageAggregate added in v1.3.11 

type NodeUsageAggregate struct {
	BudgetCosts       map[string]float64 `json:"budget_costs"`        // budget_id -> cumulative cost
	RateLimitRequests map[string]int64   `json:"rate_limit_requests"` // rate_limit_id -> successful request count
	RateLimitTokens   map[string]int64   `json:"rate_limit_tokens"`   // rate_limit_id -> total tokens
	RowCount          int                `json:"row_count"`           // number of log rows included in the aggregate
	MaxTimestamp      time.Time          `json:"max_timestamp"`       // highest log timestamp included in the aggregate
	MaxLogID          string             `json:"max_log_id"`          // log ID tiebreaker for MaxTimestamp
	NextCursor        NodeUsageCursor    `json:"next_cursor"`         // stable cursor for the next incremental query
}

NodeUsageAggregate represents aggregated usage for a specific node from the logs table, broken down by the budget and rate-limit IDs that each log entry was tagged with. This ensures usage is attributed to the correct governance resource rather than spread uniformly across all resources the node was tracking.

type NodeUsageCursor added in v1.3.11 

type NodeUsageCursor struct {
	Timestamp time.Time `json:"timestamp"`
	LogID     string    `json:"log_id"`
	IncNumber *int64    `json:"inc_number,omitempty"`
}

NodeUsageCursor identifies the last log row included in a node usage scan. The initial scan uses Timestamp + LogID because each ghost has a timestamp lower bound. Once rows written with IncNumber are seen, subsequent scans use IncNumber because it is assigned by the database at insert time and therefore does not skip late async log writes.

type OverheadBucket added in v1.6.0 

type OverheadBucket struct {
	Name string `json:"name"` // e.g. "key.selection", "plugin.governance", "mcp", "core"
	// Not serialized: derivable from Name (plugin spans carry the "plugin." prefix), and
	// 27% of the persisted column. In-memory only, for MetricComponent.
	Kind       string  `json:"-"`
	DurationUs float64 `json:"duration_us"`
}

OverheadBucket is one slice of the Bifrost overhead, attributed to a span (or group of spans) by self-time: the span's own wall duration minus the wall duration of its direct children. Self-times across the whole span tree are non-overlapping and sum to the root duration, so summing the overhead-side buckets gives an independent measure of overhead that does not rely on the upstream socket accumulator. DurationUs is microseconds (overhead runs small).

type PaginationOptions 

type PaginationOptions struct {
	Limit          int    `json:"limit"`
	Offset         int    `json:"offset"`
	SortBy         string `json:"sort_by"`     // "timestamp", "latency", "tokens", "cost"
	Order          string `json:"order"`       // "asc", "desc"
	TotalCount     int64  `json:"total_count"` // Total number of items matching the query
	SelectedOffset *int64 `json:"selected_offset,omitempty"`
	SelectedID     string `json:"-"`
	// SkipCount skips the total count entirely; TotalCount is left at zero. For
	// callers that page through a window and never read the total. Honoured by
	// SearchLogs, SearchLogsForBilling and SearchMCPToolLogs.
	SkipCount bool `json:"-"`
	// AfterTimestamp and AfterID form a keyset cursor for SortBy "timestamp": only
	// rows strictly after (AfterTimestamp, AfterID) in the requested order are
	// returned. Both must be set; AfterID alone is ignored. Honoured by SearchLogs
	// and SearchLogsForBilling only: SearchMCPToolLogs ignores the cursor and
	// pages by Offset, ordered by timestamp alone as before.
	AfterTimestamp *time.Time `json:"-"`
	AfterID        string     `json:"-"`
	// OmitBillingPayloads makes SearchLogsForBilling return NULL for the modality
	// payload columns, so a large page carries only scalar pricing inputs. Rows
	// whose object type needs a payload (BillingPayloadRequired) must be re-read
	// individually before pricing.
	OmitBillingPayloads bool `json:"-"`
}

PaginationOptions represents pagination parameters

type PostgresConfig added in v1.1.0 

type PostgresConfig struct {
	postgresconn.Config
	// MatViewRefreshInterval controls how often the materialized views backing
	// /api/logs/stats and the dashboard histograms are refreshed. Accepts any
	// Go duration string ("30s", "5m", "1h"). Empty / unset uses the default
	// (defaultMatViewRefreshInterval). Raise this when refresh CPU cost is
	// material on the database instance — the matview path already has
	// activity-gated short-circuiting (see matViewRefreshGate), so the longer
	// interval mostly affects how quickly idle clusters notice the rolling
	// 30-day filter window has aged. Set "off" (or any non-positive duration)
	// to disable materialized-view maintenance entirely: views are neither
	// created nor refreshed and dashboard queries use the raw tables.
	MatViewRefreshInterval string `json:"matview_refresh_interval,omitempty"`

	// MatViewRefreshTimeout bounds a single refresh pass. A refresh holds a pooled
	// connection and a session-scoped advisory lock across every view; if it never
	// finishes, every replica's pg_try_advisory_lock fails from then on and the
	// views go permanently stale while still being served. Empty / unset derives a
	// budget from MatViewRefreshInterval.
	MatViewRefreshTimeout string `json:"matview_refresh_timeout,omitempty"`

	// MigrationMatViewCancelAfter is how long schema migrations wait for an
	// in-flight materialized-view refresh pass (from any replica, of any version)
	// before cancelling its REFRESH statements. Migrations pause refreshes for
	// their whole run; a long pass on a large logs table otherwise blocks their
	// CREATE INDEX CONCURRENTLY and ALTER TABLE logs statements. Accepts a Go
	// duration string; empty uses 60s; "off" never cancels and only waits.
	MigrationMatViewCancelAfter string `json:"migration_matview_cancel_after,omitempty"`

	// MatViewRefreshTempFileLimit caps the temp files one materialized-view
	// statement may write (Postgres temp_file_limit, for example "20GB"). A
	// refresh over a very large logs table can spill tens of GB, and a full disk
	// fails every query on the server. The statement that hits the cap fails and
	// the view keeps its previous contents. Empty leaves the server setting
	// alone. The database role needs superuser or
	// GRANT SET ON PARAMETER temp_file_limit; without it the cap is skipped with
	// a warning.
	MatViewRefreshTempFileLimit string `json:"matview_refresh_temp_file_limit,omitempty"`
}

type ProviderCostHistogramBucket added in v1.2.25 

type ProviderCostHistogramBucket struct {
	Timestamp  time.Time          `json:"timestamp"`
	TotalCost  float64            `json:"total_cost"`
	ByProvider map[string]float64 `json:"by_provider"`
}

ProviderCostHistogramBucket represents a single time bucket for provider cost data

type ProviderCostHistogramResult added in v1.2.25 

type ProviderCostHistogramResult struct {
	Buckets           []ProviderCostHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                         `json:"bucket_size_seconds"`
	Providers         []string                      `json:"providers"`
}

ProviderCostHistogramResult represents the provider cost histogram query result

type ProviderLatencyHistogramBucket added in v1.2.25 

type ProviderLatencyHistogramBucket struct {
	Timestamp  time.Time                       `json:"timestamp"`
	ByProvider map[string]ProviderLatencyStats `json:"by_provider"`
}

ProviderLatencyHistogramBucket represents a single time bucket for provider latency data

type ProviderLatencyHistogramResult added in v1.2.25 

type ProviderLatencyHistogramResult struct {
	Buckets           []ProviderLatencyHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                            `json:"bucket_size_seconds"`
	Providers         []string                         `json:"providers"`
}

ProviderLatencyHistogramResult represents the provider latency histogram query result

type ProviderLatencyStats added in v1.2.25 

type ProviderLatencyStats struct {
	AvgLatency    float64 `json:"avg_latency"`
	P90Latency    float64 `json:"p90_latency"`
	P95Latency    float64 `json:"p95_latency"`
	P99Latency    float64 `json:"p99_latency"`
	TotalRequests int64   `json:"total_requests"`
}

ProviderLatencyStats represents latency statistics for a single provider

type ProviderThroughputHistogramBucket added in v1.5.3 

type ProviderThroughputHistogramBucket struct {
	Timestamp  time.Time                          `json:"timestamp"`
	ByProvider map[string]ProviderThroughputStats `json:"by_provider"`
}

ProviderThroughputHistogramBucket represents a single time bucket for provider throughput data

type ProviderThroughputHistogramResult added in v1.5.3 

type ProviderThroughputHistogramResult struct {
	Buckets           []ProviderThroughputHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                               `json:"bucket_size_seconds"`
	Providers         []string                            `json:"providers"`
}

ProviderThroughputHistogramResult represents the provider throughput histogram query result

type ProviderThroughputStats added in v1.5.3 

type ProviderThroughputStats struct {
	TokensPerSecond       float64 `json:"tokens_per_second"`
	TotalCompletionTokens int64   `json:"total_completion_tokens"`
	TotalRequests         int64   `json:"total_requests"`
}

ProviderThroughputStats represents throughput statistics for a single provider

type ProviderTokenHistogramBucket added in v1.2.25 

type ProviderTokenHistogramBucket struct {
	Timestamp  time.Time                     `json:"timestamp"`
	ByProvider map[string]ProviderTokenStats `json:"by_provider"`
}

ProviderTokenHistogramBucket represents a single time bucket for provider token data

type ProviderTokenHistogramResult added in v1.2.25 

type ProviderTokenHistogramResult struct {
	Buckets           []ProviderTokenHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                          `json:"bucket_size_seconds"`
	Providers         []string                       `json:"providers"`
}

ProviderTokenHistogramResult represents the provider token histogram query result

type ProviderTokenStats added in v1.2.25 

type ProviderTokenStats struct {
	PromptTokens     int64 `json:"prompt_tokens"`
	CompletionTokens int64 `json:"completion_tokens"`
	TotalTokens      int64 `json:"total_tokens"`
}

ProviderTokenStats represents token statistics for a single provider

type RDBLogStore added in v1.1.0 

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

RDBLogStore represents a log store that uses a SQLite database.

func (*RDBLogStore) AddWarpTopicUnmatched added in v1.11.0 

func (s *RDBLogStore) AddWarpTopicUnmatched(ctx context.Context, rows []WarpTopicUnmatched) error

AddWarpTopicUnmatched puts requests in the unmatched pool.

func (*RDBLogStore) AddWarpVectorDeletes added in v1.11.0 

func (s *RDBLogStore) AddWarpVectorDeletes(ctx context.Context, rows []WarpVectorDelete) error

AddWarpVectorDeletes records deleted logs whose vector delete failed.

func (*RDBLogStore) AppendWarpMessages added in v1.9.0 

func (s *RDBLogStore) AppendWarpMessages(ctx context.Context, ownerID, conversationID string, messages []WarpMessage) error

AppendWarpMessages adds turns to a thread and bumps its updated time.

Both happen in one transaction. A thread whose messages landed but whose timestamp did not would sink down the history list despite being the most recent, which reads as the save having failed.

The conversation row is locked FOR UPDATE where the dialect has row locks, and the timestamps are assigned after the lock is held rather than by the caller.

Position is scoped to this append (see WarpMessage), so ordinals cannot collide - but that never serialized anything. Two replicas could read the same row and the append that committed second could write the older precomputed timestamp, which moves an active conversation down a list ordered by updated_at DESC and can put it below the retention cutoff while it is still in use.

SQLite needs no lock: it serializes writers at the database level. ClickHouse has its own implementation of this method.

func (*RDBLogStore) BatchCreateAgentLogsIfNotExists added in v1.9.0 

func (s *RDBLogStore) BatchCreateAgentLogsIfNotExists(ctx context.Context, entries []*AgentLog) ([]string, error)

BatchCreateAgentLogsIfNotExists inserts A2A records idempotently and returns the inserted IDs.

func (*RDBLogStore) BatchCreateIfNotExists added in v1.2.24 

func (s *RDBLogStore) BatchCreateIfNotExists(ctx context.Context, entries []*Log) error

BatchCreateIfNotExists inserts multiple log entries in a single transaction. Uses ON CONFLICT DO NOTHING for idempotency. Entries are written in chunks sized by insertBatchSize so no single INSERT exceeds the parameter limit.

func (*RDBLogStore) BatchCreateMCPToolLogsIfNotExists added in v1.3.9 

func (s *RDBLogStore) BatchCreateMCPToolLogsIfNotExists(ctx context.Context, entries []*MCPToolLog) error

BatchCreateMCPToolLogsIfNotExists inserts multiple MCP tool log entries in a single transaction. Uses ON CONFLICT DO NOTHING for idempotency. Entries are written in chunks sized by insertBatchSize so no single INSERT exceeds the parameter limit.

func (*RDBLogStore) BatchCreateRelayLogsIfNotExists added in v1.11.0 

func (s *RDBLogStore) BatchCreateRelayLogsIfNotExists(ctx context.Context, entries []*RelayLog) ([]string, error)

BatchCreateRelayLogsIfNotExists inserts the rows whose id is not stored yet and returns the ids it inserted.

func (*RDBLogStore) BatchUpdate added in v1.9.0 

func (s *RDBLogStore) BatchUpdate(ctx context.Context, entries []*Log) error

BatchUpdate applies partial updates to multiple existing log rows in a single transaction. Each entry must carry an ID; only its non-zero fields are written (GORM Updates semantics), so output columns can be reconciled onto an existing row while its input columns are left intact.

Unlike the single-row Update, a row that does not match is silently skipped rather than returning ErrNotFound: this is a best-effort batch reconciliation (e.g. evicted-pending recovery), and the absence of a row is not a failure of the whole batch. Callers that enqueue a partial-row insert before the matching update rely on insert-before-update ordering so the row is present by the time the update runs.

func (*RDBLogStore) BucketWarpTopicAssignments added in v1.11.0 

func (s *RDBLogStore) BucketWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter, bucketSizeSeconds int64) ([]WarpTopicBucket, error)

BucketWarpTopicAssignments adds up the selected assignments per topic and per bucket, oldest bucket first, within the caller's access scope.

The bucket is the same per-dialect expression the log histograms use, so a topic's series lines up with the request series the dashboard draws over the same window.

func (*RDBLogStore) BulkBackfillBillingPayloads added in v1.5.5 

func (s *RDBLogStore) BulkBackfillBillingPayloads(ctx context.Context, updates map[string]BillingPayloadBackfill) error

BulkBackfillBillingPayloads writes recovered token_usage / cache_debug back into their rows so later recomputes need no object fetch.

Only ever called with rows whose payload was actually fetched, which in a pure RDB store is never — this exists for the hybrid store layered on top, which delegates here.

func (*RDBLogStore) BulkUpdateCost added in v1.1.49 

func (s *RDBLogStore) BulkUpdateCost(ctx context.Context, updates map[string]CostUpdate) error

BulkUpdateCost updates log costs in bulk, using a PostgreSQL-specific batched VALUES update when available and per-row updates for other dialects.

func (*RDBLogStore) Close added in v1.1.0 

func (s *RDBLogStore) Close(ctx context.Context) error

Close stops matview maintenance and closes the log store.

func (*RDBLogStore) CountWarpMessages added in v1.9.0 

func (s *RDBLogStore) CountWarpMessages(ctx context.Context, conversationIDs []string) (map[string]int, error)

CountWarpMessages returns message counts for the given threads in one query, so the list view does not issue a count per row.

func (*RDBLogStore) CountWarpTopicUnmatched added in v1.11.0 

func (s *RDBLogStore) CountWarpTopicUnmatched(ctx context.Context, embeddingSignature string) (int64, error)

CountWarpTopicUnmatched reports the pool's size for one embedding model.

func (*RDBLogStore) Create added in v1.1.0 

func (s *RDBLogStore) Create(ctx context.Context, entry *Log) error

Create inserts a new log entry into the database.

func (*RDBLogStore) CreateAsyncJob added in v1.2.22 

func (s *RDBLogStore) CreateAsyncJob(ctx context.Context, job *AsyncJob) error

CreateAsyncJob creates a new async job record in the database.

func (*RDBLogStore) CreateIfNotExists added in v1.1.40 

func (s *RDBLogStore) CreateIfNotExists(ctx context.Context, entry *Log) error

CreateIfNotExists inserts a new log entry only if it doesn't already exist. Uses ON CONFLICT DO NOTHING to handle duplicate key errors gracefully.

func (*RDBLogStore) CreateMCPToolLog added in v1.2.17 

func (s *RDBLogStore) CreateMCPToolLog(ctx context.Context, entry *MCPToolLog) error

CreateMCPToolLog inserts a new MCP tool log entry into the database.

func (*RDBLogStore) CreateUserAgentMapping added in v1.5.0 

func (s *RDBLogStore) CreateUserAgentMapping(ctx context.Context, mapping *UserAgentMapping) error

CreateUserAgentMapping persists a custom User-Agent to app mapping.

func (*RDBLogStore) CreateWarpConversation added in v1.9.0 

func (s *RDBLogStore) CreateWarpConversation(ctx context.Context, conversation *WarpConversation) error

CreateWarpConversation starts a thread.

func (*RDBLogStore) CreateWebhookDelivery added in v1.5.3 

func (s *RDBLogStore) CreateWebhookDelivery(ctx context.Context, delivery *WebhookDelivery) error

CreateWebhookDelivery appends one webhook delivery attempt record. The history table is insert-only: rows are never updated after creation.

func (*RDBLogStore) DeleteAgentLogs added in v1.9.0 

func (s *RDBLogStore) DeleteAgentLogs(ctx context.Context, ids []string) error

DeleteAgentLogs deletes the identified A2A log rows together with every row sharing their request IDs, so a deleted operation's correlated stream events do not survive as orphans invisible to the request-only main list.

func (*RDBLogStore) DeleteExpiredAsyncJobs added in v1.2.22 

func (s *RDBLogStore) DeleteExpiredAsyncJobs(ctx context.Context) (int64, error)

DeleteExpiredAsyncJobs deletes async jobs whose expires_at has passed. Only deletes jobs that have a non-null expires_at (i.e., completed or failed jobs). Deletes in batches to avoid long-running transactions that hold row locks.

func (*RDBLogStore) DeleteExpiredWebhookDeliveries added in v1.5.3 

func (s *RDBLogStore) DeleteExpiredWebhookDeliveries(ctx context.Context) (int64, error)

DeleteExpiredWebhookDeliveries deletes delivery history whose expires_at has passed. Rows with a null expires_at are kept. Deletes in batches to avoid long-running transactions that hold row locks.

func (*RDBLogStore) DeleteLog added in v1.1.36 

func (s *RDBLogStore) DeleteLog(ctx context.Context, id string) error

DeleteLog deletes a log entry from the database by its ID, and with it what Warp's topic tables hold about it, in one transaction.

func (*RDBLogStore) DeleteLogs added in v1.1.36 

func (s *RDBLogStore) DeleteLogs(ctx context.Context, ids []string) error

DeleteLogs deletes multiple log entries from the database by their IDs, and with them what Warp's topic tables hold about them, in one transaction.

func (*RDBLogStore) DeleteLogsBatch added in v1.1.36 

func (s *RDBLogStore) DeleteLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)

DeleteLogsBatch deletes up to batchSize logs whose created_at is older than cutoff, oldest first, in one statement. The cutoff column is created_at, the same retention semantics as before; ordering by it lets each batch walk idx_logs_created_at from its low end instead of scanning for matches.

func (*RDBLogStore) DeleteMCPToolLogs added in v1.2.17 

func (s *RDBLogStore) DeleteMCPToolLogs(ctx context.Context, ids []string) error

DeleteMCPToolLogs deletes multiple MCP tool log entries from the database by their IDs.

func (*RDBLogStore) DeleteMCPToolLogsBatch added in v1.9.0 

func (s *RDBLogStore) DeleteMCPToolLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)

DeleteMCPToolLogsBatch deletes up to batchSize MCP tool logs whose timestamp is older than cutoff, oldest first, in one statement through the timestamp index (idx_mcp_logs_timestamp on Postgres). Before this, mcp_tool_logs had no time-based retention at all.

ClickHouse is not handled here: the embedded RDB statement shape is not valid there, so the call is a no-op until ClickHouseLogStore overrides it with a lightweight delete (the same shape as its DeleteLogsBatch).

func (*RDBLogStore) DeleteRelayLogs added in v1.11.0 

func (s *RDBLogStore) DeleteRelayLogs(ctx context.Context, ids []string) error

DeleteRelayLogs deletes the identified rows, with the job rows that settle them.

func (*RDBLogStore) DeleteRelayLogsBatch added in v1.11.0 

func (s *RDBLogStore) DeleteRelayLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteRelayLogsBatch deletes up to batchSize rows older than cutoff, oldest first, for the retention cleaner.

func (*RDBLogStore) DeleteStaleAsyncJobs added in v1.2.22 

func (s *RDBLogStore) DeleteStaleAsyncJobs(ctx context.Context, staleSince time.Time) (int64, error)

DeleteStaleAsyncJobs deletes async jobs stuck in "processing" status since before the given time. This handles edge cases like marshal failures or server crashes that leave jobs permanently stuck.

func (*RDBLogStore) DeleteUserAgentMapping added in v1.5.0 

func (s *RDBLogStore) DeleteUserAgentMapping(ctx context.Context, id string) error

DeleteUserAgentMapping removes a custom User-Agent mapping by ID.

func (*RDBLogStore) DeleteWarpConversation added in v1.9.0 

func (s *RDBLogStore) DeleteWarpConversation(ctx context.Context, ownerID, id string) error

DeleteWarpConversation removes a thread and its messages.

func (*RDBLogStore) DeleteWarpConversationIfEmpty added in v1.9.0 

func (s *RDBLogStore) DeleteWarpConversationIfEmpty(ctx context.Context, ownerID, id string) (bool, error)

DeleteWarpConversationIfEmpty removes a thread only if it has no messages.

The conversation row is locked FOR UPDATE on postgres, the same lock AppendWarpMessages takes before inserting, so an append either commits first and the count sees its messages, or waits and then finds the thread gone. SQLite needs no lock: it serializes writers at the database level.

func (*RDBLogStore) DeleteWarpConversationsOlderThan added in v1.9.0 

func (s *RDBLogStore) DeleteWarpConversationsOlderThan(ctx context.Context, cutoff time.Time) (int64, error)

DeleteWarpConversationsOlderThan drops threads last touched before the cutoff, across all owners, and returns how many it removed.

At most one batch of 1,000 per call - see the interface for why - so a caller clearing a backlog loops until a call returns zero. Service.SweepHistory does exactly that, and checks ctx between batches.

This is the age-based half of retention, driven by Warp's own history_retention_days rather than logs_store.retention_days. The two are deliberately separate settings: how long you keep request telemetry and how long you keep somebody's saved chats are different questions, and answering them with one number means either transcripts vanish with the logs or logs are kept as long as transcripts.

func (*RDBLogStore) DeleteWarpTopicAssignments added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopicAssignments(ctx context.Context, logIDs []string) error

DeleteWarpTopicAssignments removes the given requests' assignments.

func (*RDBLogStore) DeleteWarpTopicAssignmentsBatch added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopicAssignmentsBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteWarpTopicAssignmentsBatch deletes up to batchSize assignments whose log was created before cutoff, oldest first.

func (*RDBLogStore) DeleteWarpTopicAssignmentsUnmatchedSince added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopicAssignmentsUnmatchedSince(ctx context.Context, since time.Time) error

DeleteWarpTopicAssignmentsUnmatchedSince removes the rows filed under no topic at or after since.

func (*RDBLogStore) DeleteWarpTopicUnmatched added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopicUnmatched(ctx context.Context, logIDs []string) error

DeleteWarpTopicUnmatched removes requests from the pool.

func (*RDBLogStore) DeleteWarpTopicUnmatchedBatch added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopicUnmatchedBatch(ctx context.Context, cutoff time.Time, batchSize int) (int64, error)

DeleteWarpTopicUnmatchedBatch deletes up to batchSize pool rows whose log was created before cutoff, oldest first.

func (*RDBLogStore) DeleteWarpTopicUnmatchedExcept added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopicUnmatchedExcept(ctx context.Context, embeddingSignature string) (int64, error)

DeleteWarpTopicUnmatchedExcept drops the pool rows of every other embedding model.

func (*RDBLogStore) DeleteWarpTopics added in v1.11.0 

func (s *RDBLogStore) DeleteWarpTopics(ctx context.Context, ids []string) error

DeleteWarpTopics removes topic and theme rows outright.

func (*RDBLogStore) DeleteWarpVectorDeletes added in v1.11.0 

func (s *RDBLogStore) DeleteWarpVectorDeletes(ctx context.Context, logIDs []string) error

DeleteWarpVectorDeletes removes the rows of logs whose vector is gone.

func (*RDBLogStore) FindAgentLog added in v1.9.0 

func (s *RDBLogStore) FindAgentLog(ctx context.Context, id string) (*AgentLog, error)

func (*RDBLogStore) FindAgentLogOperation added in v1.9.0 

func (s *RDBLogStore) FindAgentLogOperation(ctx context.Context, id string) (*AgentLogOperation, error)

FindAgentLogOperation returns the request operation containing the identified row.

func (*RDBLogStore) FindAgentLogsForDeletion added in v1.9.0 

func (s *RDBLogStore) FindAgentLogsForDeletion(ctx context.Context, ids []string) ([]*AgentLog, error)

func (*RDBLogStore) FindAll added in v1.1.0 

func (s *RDBLogStore) FindAll(ctx context.Context, query any, fields ...string) ([]*Log, error)

FindAll finds all log entries from the database.

func (*RDBLogStore) FindAllDistinct added in v1.2.24 

func (s *RDBLogStore) FindAllDistinct(ctx context.Context, query any, fields ...string) ([]*Log, error)

FindAllDistinct finds all distinct log entries for the given fields. Uses SQL DISTINCT to return only unique combinations, avoiding loading all rows when only unique values are needed (e.g., for filter dropdowns).

func (*RDBLogStore) FindAsyncJobByID added in v1.2.22 

func (s *RDBLogStore) FindAsyncJobByID(ctx context.Context, id string) (*AsyncJob, error)

FindAsyncJobByID retrieves an async job by its ID.

func (*RDBLogStore) FindByID added in v1.2.9 

func (s *RDBLogStore) FindByID(ctx context.Context, id string) (*Log, error)

FindByID gets a log entry from the database by its ID. When ctx carries a QueryScope (for example, Enterprise DAC), ScopedDB applies it so out-of-scope IDs return ErrNotFound. Contexts without a QueryScope stay unscoped as before.

func (*RDBLogStore) FindFirst added in v1.1.0 

func (s *RDBLogStore) FindFirst(ctx context.Context, query any, fields ...string) (*Log, error)

FindFirst gets a log entry from the database.

func (*RDBLogStore) FindMCPToolLog added in v1.2.17 

func (s *RDBLogStore) FindMCPToolLog(ctx context.Context, id string) (*MCPToolLog, error)

FindMCPToolLog retrieves a single MCP tool log entry by its ID. When ctx carries a QueryScope, ScopedDB applies it so out-of-scope IDs return ErrNotFound. Contexts without a QueryScope stay unscoped as before.

func (*RDBLogStore) FindRelayLog added in v1.11.0 

func (s *RDBLogStore) FindRelayLog(ctx context.Context, id string) (*RelayLog, error)

FindRelayLog loads one row, ErrNotFound when it does not exist or is out of scope.

func (*RDBLogStore) FindRelayLogsForDeletion added in v1.11.1 

func (s *RDBLogStore) FindRelayLogsForDeletion(ctx context.Context, ids []string) ([]*RelayLog, error)

FindRelayLogsForDeletion loads the rows DeleteRelayLogs removes for these ids: the rows themselves and the job rows that settle them.

func (*RDBLogStore) FindWebhookDeliveryByID added in v1.5.3 

func (s *RDBLogStore) FindWebhookDeliveryByID(ctx context.Context, id string) (*WebhookDelivery, error)

FindWebhookDeliveryByID retrieves a webhook delivery attempt by its ID.

func (*RDBLogStore) Flush added in v1.1.0 

func (s *RDBLogStore) Flush(ctx context.Context, since time.Time) error

Flush deletes old log entries from the database.

func (*RDBLogStore) FlushAgentLogs added in v1.9.0 

func (s *RDBLogStore) FlushAgentLogs(ctx context.Context, since time.Time) error

func (*RDBLogStore) FlushMCPToolLogs added in v1.2.17 

func (s *RDBLogStore) FlushMCPToolLogs(ctx context.Context, since time.Time) error

FlushMCPToolLogs deletes old processing MCP tool log entries from the database.

func (*RDBLogStore) GetAgentFilterData added in v1.9.0 

func (s *RDBLogStore) GetAgentFilterData(ctx context.Context, dimensions []string, limit int, search string) (*AgentFilterData, error)

func (*RDBLogStore) GetAgentHistogram added in v1.9.0 

func (s *RDBLogStore) GetAgentHistogram(ctx context.Context, filter AgentLogHistoryFilter, bucketSizeSeconds int64) (*AgentHistogramResult, error)

GetAgentHistogram returns time-bucketed A2A volume for the given filter, split into success and error so the chart can stack them.

func (*RDBLogStore) GetAgentLogStats added in v1.9.0 

func (s *RDBLogStore) GetAgentLogStats(ctx context.Context, filter AgentLogHistoryFilter) (*AgentLogStats, error)

GetAgentLogStats aggregates the A2A history rows matching filter. Success rate is measured over terminal entries only, so in-flight rows do not depress it.

func (*RDBLogStore) GetAgentTopAgents added in v1.9.0 

func (s *RDBLogStore) GetAgentTopAgents(ctx context.Context, filter AgentLogHistoryFilter, limit int) (*AgentTopAgentsResult, error)

GetAgentTopAgents ranks Agents by operation count for the given filter. Only request rows are counted, so an operation's stream events do not inflate its Agent's total. The request-row restriction is part of the filter, like the operation list, so task-state and search filters that match child events still select their parent operation.

func (*RDBLogStore) GetAvailableMCPApps added in v1.5.0 

func (s *RDBLogStore) GetAvailableMCPApps(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableMCPApps returns unique non-empty backend-detected app labels from MCP tool logs.

func (*RDBLogStore) GetAvailableMCPUserAgents added in v1.5.0 

func (s *RDBLogStore) GetAvailableMCPUserAgents(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableMCPUserAgents returns unique non-empty user_agent values from MCP tool logs. The UI maps each raw User-Agent to a client app for the MCP logs "App" filter.

func (*RDBLogStore) GetAvailableMCPVirtualKeys added in v1.2.17 

func (s *RDBLogStore) GetAvailableMCPVirtualKeys(ctx context.Context, limit int, query string) ([]MCPToolLog, error)

GetAvailableMCPVirtualKeys lists virtual keys represented in visible MCP logs.

func (*RDBLogStore) GetAvailableServerLabels added in v1.2.17 

func (s *RDBLogStore) GetAvailableServerLabels(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableServerLabels lists MCP server labels matching the filter search.

func (*RDBLogStore) GetAvailableToolNames added in v1.2.17 

func (s *RDBLogStore) GetAvailableToolNames(ctx context.Context, limit int, query string) ([]string, error)

GetAvailableToolNames returns all unique tool names from the MCP tool logs. Scoped to recent data to avoid full table scans.

func (*RDBLogStore) GetCommaListDimensionRankings added in v1.9.0 

func (s *RDBLogStore) GetCommaListDimensionRankings(ctx context.Context, filters SearchFilters, dimension RankingDimension) (*DimensionRankingResult, error)

GetCommaListDimensionRankings ranks a comma-list dimension by requests, with the same trend against the preceding period every other ranking carries.

func (*RDBLogStore) GetCostHistogram added in v1.2.13 

func (s *RDBLogStore) GetCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*CostHistogramResult, error)

GetCostHistogram returns time-bucketed cost data with model breakdown for the given filters.

func (*RDBLogStore) GetDimensionCostHistogram added in v1.3.1 

func (s *RDBLogStore) GetDimensionCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionCostHistogramResult, error)

GetDimensionCostHistogram returns time-bucketed cost data grouped by the specified dimension. Uses the mv_logs_hourly materialized view on PostgreSQL when eligible; falls back to raw queries otherwise.

func (*RDBLogStore) GetDimensionLatencyHistogram added in v1.3.1 

func (s *RDBLogStore) GetDimensionLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionLatencyHistogramResult, error)

GetDimensionLatencyHistogram returns time-bucketed latency percentiles grouped by the specified dimension. Uses the mv_logs_hourly materialized view on PostgreSQL when eligible; falls back to raw queries otherwise. The fallback path computes AVG latency only (no percentiles) since percentile_cont is Postgres-specific.

func (*RDBLogStore) GetDimensionModelUsage added in v1.11.0 

func (s *RDBLogStore) GetDimensionModelUsage(ctx context.Context, filters SearchFilters, dimension RankingDimension) ([]DimensionModelUsageEntry, error)

GetDimensionModelUsage returns requests and cost per (entity, model, provider) in one grouped read, read like GetDimensionUsage. It replaces one GetModelRankings call per entity for callers that only need each entity's model mix: no previous window, no ordering and no row limit.

func (*RDBLogStore) GetDimensionRankings added in v1.3.14 

func (s *RDBLogStore) GetDimensionRankings(ctx context.Context, filters SearchFilters, dimension RankingDimension) (*DimensionRankingResult, error)

GetDimensionRankings returns entities ranked by usage with trend comparison, grouped by the given dimension.

func (*RDBLogStore) GetDimensionTokenHistogram added in v1.3.1 

func (s *RDBLogStore) GetDimensionTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64, dimension HistogramDimension) (*DimensionTokenHistogramResult, error)

GetDimensionTokenHistogram returns time-bucketed token usage grouped by the specified dimension. Uses the mv_logs_hourly materialized view on PostgreSQL when eligible; falls back to raw queries otherwise.

func (*RDBLogStore) GetDimensionUsage added in v1.11.0 

func (s *RDBLogStore) GetDimensionUsage(ctx context.Context, filters SearchFilters, dimension RankingDimension, compare bool) ([]DimensionUsageEntry, error)

GetDimensionUsage returns each entity's requests, tokens and cost in one grouped read, read the way usageReadFor describes. With compare set and a bounded window, the same read also covers the equally long window before and fills each entry's Trend the way GetDimensionRankings does, instead of a second read over the previous window. Entities active only in the previous window are left out.

func (*RDBLogStore) GetDistinctAliases added in v1.3.1 

func (s *RDBLogStore) GetDistinctAliases(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctAliases returns all unique non-empty alias values using SELECT DISTINCT. Scoped to recent data to avoid full table scans. Matview path is DAC-aware (see GetDistinctModels). Scoped to recent data to avoid full table scans.

func (*RDBLogStore) GetDistinctApps added in v1.5.0 

func (s *RDBLogStore) GetDistinctApps(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctApps returns all unique non-empty backend-detected app labels.

func (*RDBLogStore) GetDistinctKeyPairs added in v1.2.22 

func (s *RDBLogStore) GetDistinctKeyPairs(ctx context.Context, idCol, nameCol string, limit int, query string) ([]KeyPairResult, error)

GetDistinctKeyPairs returns unique non-empty ID-Name pairs for the given columns using SELECT DISTINCT. idCol and nameCol must be valid column names (e.g., "selected_key_id", "selected_key_name").

Matview path is DAC-aware: each per-dimension matview carries every visibility column a scope can predicate on (see scopeProjection), so a QueryScope on ctx applies on the matview directly. Until matViewsReady the raw-table fallback (also ScopedDB-aware) serves requests.

func (*RDBLogStore) GetDistinctMetadataKeys added in v1.2.28 

func (s *RDBLogStore) GetDistinctMetadataKeys(ctx context.Context, limit int, query string) (map[string][]string, error)

GetDistinctMetadataKeys returns unique metadata keys and their distinct values from recent logs. It scans a bounded number of recent rows to avoid memory bloat on large tables.

func (*RDBLogStore) GetDistinctModels added in v1.2.22 

func (s *RDBLogStore) GetDistinctModels(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctModels returns all unique non-empty model values using SELECT DISTINCT. Scoped to recent data to avoid full table scans.

func (*RDBLogStore) GetDistinctRoutingEngines added in v1.2.22 

func (s *RDBLogStore) GetDistinctRoutingEngines(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctRoutingEngines returns all unique routing engine values from the comma-separated column. Scoped to recent data to avoid full table scans. Matview path is DAC-aware (see GetDistinctModels). Scoped to recent data to avoid full table scans.

func (*RDBLogStore) GetDistinctStopReasons added in v1.3.6 

func (s *RDBLogStore) GetDistinctStopReasons(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctStopReasons returns all unique non-empty stop_reason values using SELECT DISTINCT. Scoped to recent data to avoid full table scans. Matview path is DAC-aware (see GetDistinctModels). Scoped to recent data to avoid full table scans.

func (*RDBLogStore) GetDistinctToolCallNames added in v1.6.1 

func (s *RDBLogStore) GetDistinctToolCallNames(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctToolCallNames returns the distinct function names recorded in tool_call_names, split out of the comma-separated column and deduplicated in Go. Matview path is DAC-aware (see GetDistinctModels); falls back to a recency-scoped raw-table scan.

func (*RDBLogStore) GetDistinctUserAgents added in v1.5.0 

func (s *RDBLogStore) GetDistinctUserAgents(ctx context.Context, limit int, query string) ([]string, error)

GetDistinctUserAgents returns all unique non-empty user_agent values using SELECT DISTINCT. The UI maps each raw User-Agent to a client app. Matview path is DAC-aware (see GetDistinctModels); falls back to a recency-scoped raw-table scan.

func (*RDBLogStore) GetHistogram added in v1.2.13 

func (s *RDBLogStore) GetHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*HistogramResult, error)

GetHistogram returns time-bucketed request counts for the given filters.

func (*RDBLogStore) GetJSONFieldDimensionRankings added in v1.9.0 

func (s *RDBLogStore) GetJSONFieldDimensionRankings(ctx context.Context, filters SearchFilters, dimension RankingDimension) (*DimensionRankingResult, error)

GetJSONFieldDimensionRankings ranks a JSON-extracted dimension (error_type, error_code, fail_reason, guardrail_rule, guardrail_action) the same way GetDimensionRankings ranks a column-backed one: grouped, ordered by request count, limited, with a trend against the immediately preceding period. It is its own function rather than a branch threaded through GetDimensionRankings because these dimensions diverge from every column-backed one in two ways that would otherwise need an extra parameter on nearly every line of that function: there is no Postgres materialized-view fast path (the matviews carry no JSON-extracted values), and there is no Unassigned bucket - a row with nothing to contribute here (never failed, never guardrailed) is excluded, not counted as unassigned.

Actual/attributed request counts are computed the same way for every dimension here, not only the array-shaped ones (fail_reason, guardrail_rule, guardrail_action): error_type and error_code are single-valued per row, so for them the two numbers always come out equal - the same relationship user/virtual_key already have in the column-backed path despite also going through the "compute both" branch there.

func (*RDBLogStore) GetLatencyHistogram added in v1.2.24 

func (s *RDBLogStore) GetLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*LatencyHistogramResult, error)

GetLatencyHistogram returns time-bucketed latency percentiles (avg, p90, p95, p99) for the given filters. PostgreSQL uses database-level percentile_cont aggregation (returns 1 row per bucket). MySQL and SQLite fall back to Go-based percentile computation (loads individual latency values).

func (*RDBLogStore) GetMCPCostHistogram added in v1.2.31 

func (s *RDBLogStore) GetMCPCostHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPCostHistogramResult, error)

GetMCPCostHistogram returns time-bucketed MCP cost data for the given filters.

func (*RDBLogStore) GetMCPHistogram added in v1.2.31 

func (s *RDBLogStore) GetMCPHistogram(ctx context.Context, filters MCPToolLogSearchFilters, bucketSizeSeconds int64) (*MCPHistogramResult, error)

GetMCPHistogram returns time-bucketed MCP tool call volume for the given filters.

func (*RDBLogStore) GetMCPToolCountsByDimension added in v1.11.0 

func (s *RDBLogStore) GetMCPToolCountsByDimension(ctx context.Context, filters MCPToolLogSearchFilters, dimension RankingDimension) (map[string]int, error)

GetMCPToolCountsByDimension returns how many distinct tools each entity called inside the filter window, in one grouped read over the tool calls GetMCPTopTools counts. It replaces one GetMCPTopTools call per entity. An entity the caller's dimension ceiling hides is left out.

func (*RDBLogStore) GetMCPToolLogStats added in v1.2.17 

func (s *RDBLogStore) GetMCPToolLogStats(ctx context.Context, filters MCPToolLogSearchFilters) (*MCPToolLogStats, error)

GetMCPToolLogStats calculates statistics for MCP tool logs matching the given filters.

func (*RDBLogStore) GetMCPTopTools added in v1.2.31 

func (s *RDBLogStore) GetMCPTopTools(ctx context.Context, filters MCPToolLogSearchFilters, limit int) (*MCPTopToolsResult, error)

GetMCPTopTools returns the top N MCP tools by call count for the given filters.

func (*RDBLogStore) GetModelHistogram added in v1.2.13 

func (s *RDBLogStore) GetModelHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ModelHistogramResult, error)

GetModelHistogram returns time-bucketed model usage with success/error breakdown for the given filters.

func (*RDBLogStore) GetModelRankings added in v1.2.31 

func (s *RDBLogStore) GetModelRankings(ctx context.Context, filters SearchFilters) (*ModelRankingResult, error)

GetModelRankings returns models ranked by usage with trend comparison to the previous period. Uses the same fresh-aggregate matview gate as GetStats: short windows go to the raw table because mv_logs_hourly rounds the window out to full hour buckets, which visibly inflates rankings against the raw-path stats and cost-histogram totals shown on the same dashboard.

func (*RDBLogStore) GetNodeUsageAfter added in v1.3.11 

func (s *RDBLogStore) GetNodeUsageAfter(ctx context.Context, nodeID string, cursor NodeUsageCursor) (*NodeUsageAggregate, error)

GetNodeUsageAfter returns per-budget cost and per-rate-limit request/token usage for a specific cluster node after a stable cursor. The first scan uses the timestamp/log-id lower bound for the ghost's detection point. Once DB-assigned inc_number values are observed, subsequent scans use inc_number so rows flushed late by the async log writer are not skipped.

func (*RDBLogStore) GetProviderCostHistogram added in v1.2.25 

func (s *RDBLogStore) GetProviderCostHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderCostHistogramResult, error)

GetProviderCostHistogram returns time-bucketed cost data with provider breakdown for the given filters.

func (*RDBLogStore) GetProviderLatencyHistogram added in v1.2.25 

func (s *RDBLogStore) GetProviderLatencyHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderLatencyHistogramResult, error)

GetProviderLatencyHistogram returns time-bucketed latency percentiles with provider breakdown for the given filters. PostgreSQL uses database-level percentile_cont aggregation. MySQL and SQLite fall back to Go-based percentile computation.

func (*RDBLogStore) GetProviderThroughputHistogram added in v1.5.3 

func (s *RDBLogStore) GetProviderThroughputHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderThroughputHistogramResult, error)

GetProviderThroughputHistogram returns time-bucketed tokens/sec with a per-provider breakdown for the given filters. See GetThroughputHistogram for the throughput definition.

func (*RDBLogStore) GetProviderTokenHistogram added in v1.2.25 

func (s *RDBLogStore) GetProviderTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ProviderTokenHistogramResult, error)

GetProviderTokenHistogram returns time-bucketed token usage with provider breakdown for the given filters.

func (*RDBLogStore) GetRelayFilterData added in v1.11.0 

func (s *RDBLogStore) GetRelayFilterData(ctx context.Context, dimensions []string, limit int, search string) (*RelayFilterData, error)

GetRelayFilterData lists the distinct values of the asked-for dimensions (every dimension when none is named), each narrowed by search and bounded by limit, so a sidebar section loads only what it shows, as the Agent and MCP filter data do. Names are searched, ids are returned.

func (*RDBLogStore) GetRelayHistogram added in v1.11.0 

func (s *RDBLogStore) GetRelayHistogram(ctx context.Context, filters RelayLogFilters, bucketSizeSeconds int64) (*RelayHistogramResult, error)

GetRelayHistogram returns time-bucketed volume and spend for the filters.

func (*RDBLogStore) GetRelayLogStats added in v1.11.0 

func (s *RDBLogStore) GetRelayLogStats(ctx context.Context, filters RelayLogFilters) (*RelayLogStats, error)

GetRelayLogStats aggregates the rows matching the filters.

func (*RDBLogStore) GetRelayTopEndpoints added in v1.11.0 

func (s *RDBLogStore) GetRelayTopEndpoints(ctx context.Context, filters RelayLogFilters, limit int) (*RelayTopResults, error)

GetRelayTopEndpoints ranks endpoints by request count for the filters.

func (*RDBLogStore) GetSessionLogs added in v1.3.1 

func (s *RDBLogStore) GetSessionLogs(ctx context.Context, sessionID string, pagination PaginationOptions) (*SessionDetailResult, error)

GetSessionLogs returns paginated logs for a single parent_request_id session.

func (*RDBLogStore) GetSessionSummary added in v1.3.1 

func (s *RDBLogStore) GetSessionSummary(ctx context.Context, sessionID string) (*SessionSummaryResult, error)

GetSessionSummary returns aggregate totals for a single parent_request_id session.

func (*RDBLogStore) GetStats added in v1.1.31 

func (s *RDBLogStore) GetStats(ctx context.Context, filters SearchFilters) (*SearchStats, error)

GetStats calculates statistics for logs matching the given filters.

func (*RDBLogStore) GetThroughputHistogram added in v1.5.3 

func (s *RDBLogStore) GetThroughputHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*ThroughputHistogramResult, error)

GetThroughputHistogram returns time-bucketed token-generation throughput (tokens/sec) for the given filters. TokensPerSecond is the aggregate rate for each bucket: SUM(completion_tokens) / (SUM(latency_ms)/1000), computed over successful inference rows (throughputObjectTypes) that recorded a latency > 0.

func (*RDBLogStore) GetTokenHistogram added in v1.2.13 

func (s *RDBLogStore) GetTokenHistogram(ctx context.Context, filters SearchFilters, bucketSizeSeconds int64) (*TokenHistogramResult, error)

GetTokenHistogram returns time-bucketed token usage for the given filters.

func (*RDBLogStore) GetUserRankings added in v1.3.1 

func (s *RDBLogStore) GetUserRankings(ctx context.Context, filters SearchFilters) (*UserRankingResult, error)

GetUserRankings returns users ranked by usage with trend comparison to the previous period. Uses the same fresh-aggregate matview gate as GetStats: short windows go to the raw table because mv_logs_hourly rounds the window out to full hour buckets, which visibly inflates rankings against the raw-path stats and cost-histogram totals shown on the same dashboard.

func (*RDBLogStore) GetUserSpend added in v1.9.0 

func (s *RDBLogStore) GetUserSpend(ctx context.Context, filters SearchFilters) ([]UserSpendEntry, error)

GetUserSpend returns each user's total cost inside the filter window. Unlike GetUserRankings it reads no previous period, sends no user id list and sorts nothing, so its cost does not grow with the number of users. Postgres windows of a day or more read whole hours from the hourly matview and the partial boundary hours from the raw table, so the totals stay exactly inside the window; everything else reads the raw logs table with the same status and user filters as GetUserRankings.

func (*RDBLogStore) GetWarpConversation added in v1.9.0 

func (s *RDBLogStore) GetWarpConversation(ctx context.Context, ownerID, id string) (*WarpConversation, error)

GetWarpConversation returns one thread with its newest messages in order, bounded at WarpMaxTranscriptMessages.

func (*RDBLogStore) HasLogs added in v1.1.36 

func (s *RDBLogStore) HasLogs(ctx context.Context) (bool, error)

HasLogs checks if there are any logs in the database.

func (*RDBLogStore) HasMCPToolLogs added in v1.2.17 

func (s *RDBLogStore) HasMCPToolLogs(ctx context.Context) (bool, error)

HasMCPToolLogs checks if there are any MCP tool logs in the database.

func (*RDBLogStore) HasRelayLogs added in v1.11.0 

func (s *RDBLogStore) HasRelayLogs(ctx context.Context) (bool, error)

HasRelayLogs reports whether any row is stored, for the empty state.

func (*RDBLogStore) HydrateBillingChunk added in v1.5.5 

func (s *RDBLogStore) HydrateBillingChunk(_ context.Context, _ []*Log) (BillingHydrationResult, error)

HydrateBillingChunk is a no-op for a pure RDB store: nothing is offloaded, so every pricing input is already in the row. The hybrid store overrides this to fetch.

func (*RDBLogStore) IsLogEntryPresent added in v1.3.0 

func (s *RDBLogStore) IsLogEntryPresent(ctx context.Context, id string) (bool, error)

IsLogEntryPresent checks if a log entry is present in the database. Here we dont load entire log entry in memory - just check if it exists.

func (*RDBLogStore) ListAgentLogHistory added in v1.9.0 

func (s *RDBLogStore) ListAgentLogHistory(ctx context.Context, filter AgentLogHistoryFilter, pagination PaginationOptions) (*AgentLogHistoryResult, error)

func (*RDBLogStore) ListAgentLogOperations added in v1.9.0 

func (s *RDBLogStore) ListAgentLogOperations(ctx context.Context, filter AgentLogHistoryFilter, pagination PaginationOptions) (*AgentLogOperationResult, error)

ListAgentLogOperations returns a bounded page of request rows with correlated events.

func (*RDBLogStore) ListLogsForWarpTopics added in v1.11.0 

func (s *RDBLogStore) ListLogsForWarpTopics(ctx context.Context, logIDs []string, from, to time.Time) ([]WarpTopicAssignment, error)

ListLogsForWarpTopics returns the assignment columns of the given logs, within the caller's access scope.

func (*RDBLogStore) ListUserAgentMappings added in v1.5.0 

func (s *RDBLogStore) ListUserAgentMappings(ctx context.Context, activeOnly bool) ([]UserAgentMapping, error)

ListUserAgentMappings returns custom User-Agent mappings ordered by creation time.

func (*RDBLogStore) ListWarpConversations added in v1.9.0 

func (s *RDBLogStore) ListWarpConversations(ctx context.Context, ownerID string, limit int) ([]WarpConversation, error)

ListWarpConversations returns an owner's threads, most recent first.

Messages are deliberately not preloaded: the list renders a title and a count, and pulling every transcript to draw a sidebar would make opening the history cost more than the conversation it lists. These use s.db directly rather than scopedLogsDB. That helper composes the dashboard's hidden-request-types filter with the caller's log access scope, both of which are about log rows: it adds an object_type predicate to a table that has no such column, and applies a row filter built for telemetry to content whose access control is owner_id. Conversations scope themselves, on every read and write, by the owner derived from the caller's identity.

func (*RDBLogStore) ListWarpTopicAssignments added in v1.11.0 

func (s *RDBLogStore) ListWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter, limit int) ([]WarpTopicAssignment, error)

ListWarpTopicAssignments returns the selected assignments newest first, within the caller's access scope.

func (*RDBLogStore) ListWarpTopicUnmatched added in v1.11.0 

func (s *RDBLogStore) ListWarpTopicUnmatched(ctx context.Context, embeddingSignature string, limit int) ([]WarpTopicUnmatched, error)

ListWarpTopicUnmatched returns the pool for one embedding model, newest first.

func (*RDBLogStore) ListWarpTopics added in v1.11.0 

func (s *RDBLogStore) ListWarpTopics(ctx context.Context, filter WarpTopicFilter) ([]WarpTopic, error)

ListWarpTopics returns the selected topics, oldest first.

This reads through s.db, not ScopedDB: the access scope is a predicate over ownership columns this table does not have.

func (*RDBLogStore) ListWarpVectorDeletes added in v1.11.0 

func (s *RDBLogStore) ListWarpVectorDeletes(ctx context.Context, limit int) ([]WarpVectorDelete, error)

ListWarpVectorDeletes returns up to limit pending vector deletes, oldest first.

func (*RDBLogStore) MigrationInProgress added in v1.9.0 

func (s *RDBLogStore) MigrationInProgress(ctx context.Context) bool

MigrationInProgress implements MaintenanceGate.

func (*RDBLogStore) Ping added in v1.1.8 

func (s *RDBLogStore) Ping(ctx context.Context) error

Ping checks if the database is reachable.

func (*RDBLogStore) PruneWarpConversations added in v1.9.0 

func (s *RDBLogStore) PruneWarpConversations(ctx context.Context, ownerID string, keep int) (int64, error)

PruneWarpConversations drops an owner's oldest threads beyond keep.

Warp's history is a convenience, not a record of account. Without a cap the table grows for the life of the deployment, and nobody scrolls back past the last few dozen threads anyway.

func (*RDBLogStore) PruneWarpTopicUnmatched added in v1.11.0 

func (s *RDBLogStore) PruneWarpTopicUnmatched(ctx context.Context, olderThan time.Time, keep int) (int64, error)

PruneWarpTopicUnmatched bounds the pool by age and by count.

func (*RDBLogStore) ReconcileAgentCorrelation added in v1.9.0 

func (s *RDBLogStore) ReconcileAgentCorrelation(ctx context.Context, entries []*AgentLog) error

ReconcileAgentCorrelation fills missing correlation values from persisted A2A rows. Request-scoped facts are applied first, then context IDs are propagated across rows for the same task. Both updates are fill-only.

func (*RDBLogStore) ScopedDB added in v1.3.11 

func (s *RDBLogStore) ScopedDB(ctx context.Context) *gorm.DB

ScopedDB returns the underlying DB bound to ctx with any QueryScope on ctx pre-applied. Use this in read paths that should respect caller-driven row visibility; use s.db.WithContext(ctx) for writes and internal lookups that must bypass scoping.

func (*RDBLogStore) SearchLogs added in v1.1.0 

func (s *RDBLogStore) SearchLogs(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)

SearchLogs searches for logs in the database without calculating statistics.

func (*RDBLogStore) SearchLogsForBilling added in v1.5.5 

func (s *RDBLogStore) SearchLogsForBilling(ctx context.Context, filters SearchFilters, pagination PaginationOptions) (*SearchResult, error)

SearchLogsForBilling searches with the billing projection.

With pagination.OmitBillingPayloads the modality payload columns come back NULL, so a large page holds only scalar pricing inputs; the caller re-reads each row for which BillingPayloadRequired is true before pricing it.

func (*RDBLogStore) SearchMCPToolLogs added in v1.2.17 

func (s *RDBLogStore) SearchMCPToolLogs(ctx context.Context, filters MCPToolLogSearchFilters, pagination PaginationOptions) (*MCPToolLogSearchResult, error)

SearchMCPToolLogs searches for MCP tool logs in the database.

func (*RDBLogStore) SearchRelayLogs added in v1.11.0 

func (s *RDBLogStore) SearchRelayLogs(ctx context.Context, filters RelayLogFilters, pagination PaginationOptions) (*RelayLogSearchResult, error)

SearchRelayLogs returns one page of rows matching the filters, newest first by default.

func (*RDBLogStore) SearchWebhookDeliveries added in v1.5.3 

func (s *RDBLogStore) SearchWebhookDeliveries(ctx context.Context, filters *WebhookDeliverySearchFilters, pagination PaginationOptions) (*WebhookDeliverySearchResult, error)

SearchWebhookDeliveries returns one page of matching delivery history. Pagination is by delivery group (webhook_id), not by individual attempt: a page holds every attempt of the webhook_ids it covers, so a delivery run never straddles a page boundary and the caller can group attempts into runs without losing any. Groups are ordered by their most recent attempt, and attempts within the page are returned newest first.

Filters select delivery groups, not attempts: a group is on the page if ANY of its attempts matches. The attempts themselves are then fetched unfiltered, so a run selected by, say, outcome=exhausted still reports its full attempt sequence rather than only the exhausted tail.

func (*RDBLogStore) SumWarpMessageUsage added in v1.9.0 

func (s *RDBLogStore) SumWarpMessageUsage(ctx context.Context, conversationIDs []string) (map[string]WarpUsageTotals, error)

SumWarpMessageUsage returns each thread's total tokens and cost in one grouped query. Threads with no messages, or that do not exist, are absent from the result rather than reported as zero.

func (*RDBLogStore) SummarizeWarpTopicAssignments added in v1.11.0 

func (s *RDBLogStore) SummarizeWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter) ([]WarpTopicUsage, error)

SummarizeWarpTopicAssignments adds up the selected assignments per topic, largest first, within the caller's access scope.

func (*RDBLogStore) Update added in v1.1.0 

func (s *RDBLogStore) Update(ctx context.Context, id string, entry any) error

Update updates a log entry in the database.

func (*RDBLogStore) UpdateAgentLog added in v1.9.0 

func (s *RDBLogStore) UpdateAgentLog(ctx context.Context, id string, entry any) error

func (*RDBLogStore) UpdateAsyncJob added in v1.2.22 

func (s *RDBLogStore) UpdateAsyncJob(ctx context.Context, id string, updates map[string]interface{}) error

UpdateAsyncJob updates an async job record with the provided fields.

func (*RDBLogStore) UpdateMCPToolLog added in v1.2.17 

func (s *RDBLogStore) UpdateMCPToolLog(ctx context.Context, id string, entry any) error

UpdateMCPToolLog updates an MCP tool log entry in the database.

func (*RDBLogStore) UpdateRelayLog added in v1.11.1 

func (s *RDBLogStore) UpdateRelayLog(ctx context.Context, id string, updates map[string]any) error

UpdateRelayLog applies column updates to one row, ErrNotFound when it does not exist.

func (*RDBLogStore) UpdateUserAgentMapping added in v1.5.0 

func (s *RDBLogStore) UpdateUserAgentMapping(ctx context.Context, id string, mapping *UserAgentMapping) error

UpdateUserAgentMapping updates an existing custom User-Agent mapping by ID.

func (*RDBLogStore) UpsertWarpTopicAssignments added in v1.11.0 

func (s *RDBLogStore) UpsertWarpTopicAssignments(ctx context.Context, assignments []WarpTopicAssignment) error

UpsertWarpTopicAssignments writes one row per request, replacing any row already written for the same request.

func (*RDBLogStore) UpsertWarpTopics added in v1.11.0 

func (s *RDBLogStore) UpsertWarpTopics(ctx context.Context, topics []WarpTopic) error

UpsertWarpTopics writes topics whole, replacing any row with the same ID.

type RankingDimension added in v1.3.14 

type RankingDimension string

RankingDimension is the column used for grouping in dimension rankings. 

const (
	RankingDimensionErrorType       RankingDimension = "error_type"
	RankingDimensionErrorCode       RankingDimension = "error_code"
	RankingDimensionFailReason      RankingDimension = "fail_reason"
	RankingDimensionGuardrailRule   RankingDimension = "guardrail_rule"
	RankingDimensionGuardrailAction RankingDimension = "guardrail_action"
	RankingDimensionStatusCode      RankingDimension = "status_code"
)

JSON-extracted ranking dimensions: labels that live inside a JSON blob column instead of a real, indexed column - error classification, retry fail reasons, guardrail decisions. There is no migration or backfill behind any of this: the data already exists on every row (see Log.AfterFind / DeserializeFields), this only teaches GetDimensionRankings a second way to GROUP BY a value that was always stored there.

This generalizes two precedents already in this package rather than inventing a third style:

  • The cache_hit_type filter (rdb.go, applyFilters) proved that filtering on a value buried in a JSON-in-text column works without a migration. It uses a loose regex because hit_type is a unique, top-level key; the dimensions here sit one level deeper (error_details.error.type, guardrail_debug.judge_calls[].rule_name), where a flat regex cannot reliably tell which "type" or which array it found. So extraction here uses real JSON functions instead: Postgres's `::jsonb` cast guarded by the `IS JSON` predicate (Postgres 16+), SQLite's json1 extension, and ClickHouse's JSON functions.
  • teamOrBUFanoutFrom / dimensionFanoutFrom (dialectsql.go) proved the fan-out shape: a FROM subquery, aliased AS logs, that turns one row with an array into one row per array element, so the same GetDimensionRankings grouping machinery (Group/Order/applyRankingLimit) works unchanged. That precedent fans out a JSON array of *strings* (team_ids) with a parallel name array; the dimensions here fan out a JSON array of *objects* (attempt_trail, guardrail_debug.judge_calls) and extract one field per element - the array shape differs, but the "pre-sanitize the argument to a safe empty array rather than filtering after" discipline is carried over unchanged, since that is what makes the fan-out safe against malformed or absent JSON without depending on any particular WHERE/FROM evaluation order.

None of these dimensions is bucketed: a row that never failed has no error_type, and a row nothing guardrailed has no guardrail_rule. That is a real, useful "not applicable" rather than "Unassigned" - a caller who wants a breakdown of errors already filters to status=error, so a bucketed "99% Unassigned" row would only be noise. 

const (
	RankingDimensionTeam         RankingDimension = "team"
	RankingDimensionCustomer     RankingDimension = "customer"
	RankingDimensionBusinessUnit RankingDimension = "business_unit"
	RankingDimensionProject      RankingDimension = "project"
	RankingDimensionUser         RankingDimension = "user"
	RankingDimensionVirtualKey   RankingDimension = "virtual_key"
	RankingDimensionApp          RankingDimension = "app"
	RankingDimensionUserAgent    RankingDimension = "user_agent"
	// The routing dimensions: which rule, provider key, alias or complexity tier
	// handled a request. Each has been filterable on the Logs page for as long as
	// it has existed and could be ranked by nothing, so "which rule takes the most
	// traffic" had a filter to check one guess at a time and no way to ask.
	RankingDimensionRoutingRule         RankingDimension = "routing_rule"
	RankingDimensionSelectedKey         RankingDimension = "selected_key"
	RankingDimensionAlias               RankingDimension = "alias"
	RankingDimensionComplexityTier      RankingDimension = "complexity_tier"
	RankingDimensionComplexityMechanism RankingDimension = "complexity_mechanism"
	// Stored as a comma-separated list on the row, so one request can count
	// under several values (see commalistdimensions.go).
	RankingDimensionRoutingEngine RankingDimension = "routing_engine"
	RankingDimensionToolCallName  RankingDimension = "tool_call_name"
)

type RealtimeInputCorrection added in v1.11.0 

type RealtimeInputCorrection struct {
	Index      int    `json:"index"`
	ItemID     string `json:"item_id"`
	Transcript string `json:"transcript"`
	Raw        string `json:"raw,omitempty"`
	Summary    string `json:"-"` // DB summary written before the ordered object merge is queued
}

RealtimeInputCorrection identifies one input position to patch on the ordered object writer. It is transient and never adds a database column or an object payload field.

type RelayFilterData added in v1.11.0 

type RelayFilterData struct {
	EndpointNames []string            `json:"relay_names,omitempty"`
	Methods       []string            `json:"methods,omitempty"`
	Apps          []string            `json:"apps,omitempty"`
	VirtualKeys   []RelayFilterOption `json:"virtual_keys,omitempty"`
	Users         []RelayFilterOption `json:"users,omitempty"`
	Teams         []RelayFilterOption `json:"teams,omitempty"`
	Customers     []RelayFilterOption `json:"customers,omitempty"`
	BusinessUnits []RelayFilterOption `json:"business_units,omitempty"`
	Projects      []RelayFilterOption `json:"projects,omitempty"`
}

RelayFilterData lists the values the Relay Logs filters can offer. RelayFilterData is the subset of filter dimensions a caller asked for; a dimension not asked for is absent. Mirrors AgentFilterData and the MCP filter data.

type RelayFilterOption added in v1.11.0 

type RelayFilterOption struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

RelayFilterOption is an id with the name recorded for it.

type RelayHistogramBucket added in v1.11.0 

type RelayHistogramBucket struct {
	Timestamp  time.Time `json:"timestamp"`
	Count      int64     `json:"count"`
	Success    int64     `json:"success"`
	Error      int64     `json:"error"`
	Cancelled  int64     `json:"cancelled"` // calls the caller hung up on, as in the LLM logs histogram
	Cost       float64   `json:"cost"`
	AvgLatency float64   `json:"avg_latency"` // milliseconds, 0 when nothing was timed
	Units      float64   `json:"units"`       // billed units
	BytesOut   int64     `json:"bytes_out"`
}

RelayHistogramBucket is one time bucket of volume, latency, units and spend, so the page's metric strip can draw the same sparklines the LLM logs page draws.

type RelayHistogramResult added in v1.11.0 

type RelayHistogramResult struct {
	Buckets           []RelayHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                  `json:"bucket_size_seconds"`
}

RelayHistogramResult is a time-bucketed Relay Logs histogram.

type RelayLog added in v1.11.0 

type RelayLog struct {
	ID        string    `gorm:"primaryKey;type:varchar(255)" json:"id"`
	Timestamp time.Time `gorm:"index:idx_relay_logs_timestamp;not null" json:"timestamp"`
	CreatedAt time.Time `gorm:"index:idx_relay_logs_created_at;not null;autoCreateTime:false;default:CURRENT_TIMESTAMP" json:"created_at"`

	RelayName  string `gorm:"type:varchar(64);index:idx_relay_logs_relay_name;not null" json:"relay_name"`
	Kind       string `gorm:"type:varchar(16);index:idx_relay_logs_kind;not null;default:'call'" json:"kind"` // call | job
	Method     string `gorm:"type:varchar(10);index:idx_relay_logs_method" json:"method"`
	Path       string `gorm:"type:text" json:"path"`
	RoutePath  string `gorm:"type:text" json:"route_path,omitempty"`                               // matched route glob, "" for none
	Status     string `gorm:"type:varchar(32);index:idx_relay_logs_status;not null" json:"status"` // success | error | cancelled
	StatusCode int    `json:"status_code"`
	Streamed   bool   `json:"streamed"`
	Billable   bool   `json:"billable"`
	Model      string `gorm:"type:varchar(255)" json:"model,omitempty"`

	Latency           *float64 `json:"latency,omitempty"`          // milliseconds, pre-hooks to the end of the reply
	UpstreamLatency   *float64 `json:"upstream_latency,omitempty"` // milliseconds blocked on the upstream socket; nil = unmeasured
	OverheadLatency   *float64 `json:"overhead_latency,omitempty"` // Bifrost overhead (total minus upstream), ms; nil = unmeasured
	OverheadBreakdown string   `gorm:"type:text" json:"-"`         // Name-keyed JSON object, mirroring Log.OverheadBreakdown
	BytesOut          int64    `json:"bytes_out"`

	// Cost is the figure charged to budgets; the rest explains it.
	Cost           *float64 `gorm:"index:idx_relay_logs_cost" json:"cost,omitempty"`
	CostPerRequest *float64 `json:"cost_per_request,omitempty"`
	CostPerUnit    *float64 `json:"cost_per_unit,omitempty"`
	ExtractedCost  *float64 `json:"extracted_cost,omitempty"`
	Units          *float64 `json:"units,omitempty"`
	BilledUnits    *float64 `json:"billed_units,omitempty"`
	InputTokens    int      `json:"input_tokens,omitempty"`
	OutputTokens   int      `json:"output_tokens,omitempty"`
	TotalTokens    int      `json:"total_tokens,omitempty"`

	JobID       *string `gorm:"type:varchar(255);index:idx_relay_logs_job_id" json:"job_id,omitempty"`
	JobStatus   *string `gorm:"type:varchar(64)" json:"job_status,omitempty"`
	ParentLogID *string `gorm:"type:varchar(255);index:idx_relay_logs_parent_log_id" json:"parent_log_id,omitempty"` // a job row's start call

	UserID           *string `gorm:"type:varchar(255);index:idx_relay_logs_user_id" json:"user_id,omitempty"`
	UserName         *string `gorm:"type:varchar(255)" json:"user_name,omitempty"`
	VirtualKeyID     *string `gorm:"type:varchar(255);index:idx_relay_logs_virtual_key_id" json:"virtual_key_id,omitempty"`
	VirtualKeyName   *string `gorm:"type:varchar(255)" json:"virtual_key_name,omitempty"`
	TeamID           *string `gorm:"type:varchar(255);index:idx_relay_logs_team_id" json:"team_id,omitempty"`
	TeamName         *string `gorm:"type:varchar(255)" json:"team_name,omitempty"`
	CustomerID       *string `gorm:"type:varchar(255);index:idx_relay_logs_customer_id" json:"customer_id,omitempty"`
	CustomerName     *string `gorm:"type:varchar(255)" json:"customer_name,omitempty"`
	BusinessUnitID   *string `gorm:"type:varchar(255);index:idx_relay_logs_business_unit_id" json:"business_unit_id,omitempty"`
	BusinessUnitName *string `gorm:"type:varchar(255)" json:"business_unit_name,omitempty"`
	ProjectID        *string `gorm:"type:varchar(255);index:idx_relay_logs_project_id" json:"project_id,omitempty"`
	ProjectName      *string `gorm:"type:varchar(255)" json:"project_name,omitempty"`
	UserAgent        *string `gorm:"type:varchar(512);index:idx_relay_logs_user_agent" json:"user_agent,omitempty"` // Raw HTTP User-Agent of the calling client
	App              *string `gorm:"type:varchar(128);index:idx_relay_logs_app" json:"app,omitempty"`               // Backend-detected client app derived from user_agent
	// Every team, customer and business unit the call settled, as on logs and mcp_tool_logs: the
	// scalar columns keep the first, these keep them all, and the dimension filters read both.
	TeamIDs                 *string               `gorm:"type:text" json:"-"` // JSON serialized []string
	TeamNames               *string               `gorm:"type:text" json:"-"` // JSON serialized []string
	CustomerIDs             *string               `gorm:"type:text" json:"-"` // JSON serialized []string
	CustomerNames           *string               `gorm:"type:text" json:"-"` // JSON serialized []string
	BusinessUnitIDs         *string               `gorm:"type:text" json:"-"` // JSON serialized []string
	BusinessUnitNames       *string               `gorm:"type:text" json:"-"` // JSON serialized []string
	BudgetIDs               *string               `gorm:"type:text" json:"-"`
	RateLimitIDs            *string               `gorm:"type:text" json:"-"`
	RequestID               string                `gorm:"type:varchar(255);index:idx_relay_logs_request_id;not null" json:"request_id"`
	Metadata                *string               `gorm:"type:text" json:"-"` // JSON map: logging headers, x-bf-lh-* labels, x-bf-dim-* dimensions and the key's metadata, as on LLM and MCP rows
	RequestHeaders          *string               `gorm:"type:text" json:"-"`
	ResponseHeaders         *string               `gorm:"type:text" json:"-"`
	RequestBody             *string               `gorm:"type:text" json:"request_body,omitempty"`
	ResponseBody            *string               `gorm:"type:text" json:"response_body,omitempty"`
	ErrorDetails            string                `gorm:"type:text" json:"-"`
	ContentHidden           bool                  `gorm:"default:false" json:"content_hidden"`
	PayloadReference        *string               `gorm:"type:varchar(1024)" json:"-"` // object key of the full bodies in hybrid mode
	HasObject               bool                  `gorm:"default:false" json:"-"`
	PluginLogs              string                `gorm:"type:text" json:"plugin_logs,omitempty"`
	BudgetIDsParsed         []string              `gorm:"-" json:"budget_ids,omitempty"`
	RateLimitIDsParsed      []string              `gorm:"-" json:"rate_limit_ids,omitempty"`
	MetadataParsed          map[string]any        `gorm:"-" json:"metadata,omitempty"`
	RequestHeadersParsed    map[string]string     `gorm:"-" json:"request_headers,omitempty"`
	ResponseHeadersParsed   map[string]string     `gorm:"-" json:"response_headers,omitempty"`
	ErrorDetailsParsed      *schemas.BifrostError `gorm:"-" json:"error_details,omitempty"`
	OverheadBreakdownParsed []OverheadBucket      `gorm:"-" json:"overhead_breakdown,omitempty"`
	TeamIDsParsed           []string              `gorm:"-" json:"team_ids,omitempty"`
	TeamNamesParsed         []string              `gorm:"-" json:"team_names,omitempty"`
	CustomerIDsParsed       []string              `gorm:"-" json:"customer_ids,omitempty"`
	CustomerNamesParsed     []string              `gorm:"-" json:"customer_names,omitempty"`
	BusinessUnitIDsParsed   []string              `gorm:"-" json:"business_unit_ids,omitempty"`
	BusinessUnitNamesParsed []string              `gorm:"-" json:"business_unit_names,omitempty"`
}

RelayLog records one call to a relay (/relay/{endpoint}/{path}), or the settlement of an async job one started. It is a table of its own, as MCP tool and Agent Gateway logs are, because a relay call has no provider or model: its cost is the endpoint's pricing formula, recorded here broken down.

func (*RelayLog) AfterFind added in v1.11.0 

func (l *RelayLog) AfterFind(_ *gorm.DB) error

func (*RelayLog) ApplyGovernanceContext added in v1.11.0 

func (l *RelayLog) ApplyGovernanceContext(ctx *schemas.BifrostContext)

ApplyGovernanceContext records the request's governance attribution on a Relay Logs row: the virtual key, user, team, customer, business unit and project, and the budgets and rate limits the call was charged against. The multi-valued team, customer and business unit sets are not stored on this table; the primary of each is.

func (*RelayLog) BeforeCreate added in v1.11.0 

func (l *RelayLog) BeforeCreate(_ *gorm.DB) error

func (*RelayLog) DeserializeFields added in v1.11.0 

func (l *RelayLog) DeserializeFields() error

DeserializeFields reads the stored columns back into their parsed fields. A malformed column is left unparsed rather than failing the read.

func (*RelayLog) SerializeFields added in v1.11.0 

func (l *RelayLog) SerializeFields() error

SerializeFields writes the parsed fields into their stored columns.

func (RelayLog) TableName added in v1.11.0 

func (RelayLog) TableName() string

type RelayLogFilters added in v1.11.0 

type RelayLogFilters struct {
	EndpointNames   []string   `json:"relay_names,omitempty"`
	Methods         []string   `json:"methods,omitempty"`
	Statuses        []string   `json:"statuses,omitempty"`
	Kinds           []string   `json:"kinds,omitempty"`
	VirtualKeyIDs   []string   `json:"virtual_key_ids,omitempty"`
	UserIDs         []string   `json:"user_ids,omitempty"`
	TeamIDs         []string   `json:"team_ids,omitempty"`
	CustomerIDs     []string   `json:"customer_ids,omitempty"`
	BusinessUnitIDs []string   `json:"business_unit_ids,omitempty"`
	ProjectIDs      []string   `json:"project_ids,omitempty"`
	Apps            []string   `json:"apps,omitempty"`
	Billable        *bool      `json:"billable,omitempty"`
	StartTime       *time.Time `json:"start_time,omitempty"`
	EndTime         *time.Time `json:"end_time,omitempty"`
	MinCost         *float64   `json:"min_cost,omitempty"`
	MaxCost         *float64   `json:"max_cost,omitempty"`
	RequestID       string     `json:"request_id,omitempty"`
	JobID           string     `json:"job_id,omitempty"`
	// Search matches the path, route, model and request id: metadata columns only, never bodies.
	Search string `json:"search,omitempty"`
}

RelayLogFilters narrows a Relay Logs search. Slice fields match any of their values; every populated field must match.

type RelayLogRetentionManager added in v1.11.0 

type RelayLogRetentionManager interface {
	DeleteRelayLogsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
}

RelayLogRetentionManager is implemented by stores that can expire relay_logs rows. Optional for the same reason MCPToolLogRetentionManager is.

type RelayLogSearchResult added in v1.11.0 

type RelayLogSearchResult struct {
	Logs       []*RelayLog       `json:"logs"`
	Pagination PaginationOptions `json:"pagination"`
	HasLogs    bool              `json:"has_logs"`
}

RelayLogSearchResult is one page of a Relay Logs search.

type RelayLogStats added in v1.11.0 

type RelayLogStats struct {
	TotalRequests  int64   `json:"total_requests"`
	SuccessCount   int64   `json:"success_count"`
	ErrorCount     int64   `json:"error_count"`
	SuccessRate    float64 `json:"success_rate"`    // percentage of requests that succeeded
	AverageLatency float64 `json:"average_latency"` // milliseconds
	TotalCost      float64 `json:"total_cost"`
	TotalUnits     float64 `json:"total_units"`
	TotalBytesOut  int64   `json:"total_bytes_out"`
}

RelayLogStats aggregates a Relay Logs search.

type RelayTopResult added in v1.11.0 

type RelayTopResult struct {
	RelayName      string  `json:"relay_name"`
	Count          int64   `json:"count"`
	ErrorCount     int64   `json:"error_count"`
	Cost           float64 `json:"cost"`
	AverageLatency float64 `json:"average_latency"`
}

RelayTopResult is one endpoint's totals in a top-endpoints ranking.

type RelayTopResults added in v1.11.0 

type RelayTopResults struct {
	Endpoints []RelayTopResult `json:"endpoints"`
}

RelayTopResults ranks endpoints by request count.

type SQLiteConfig 

type SQLiteConfig struct {
	Path string `json:"path"`
}

SQLiteConfig represents the configuration for a SQLite database.

type SearchFilters 

type SearchFilters struct {
	// RealtimeInputItemID is an internal lookup of an item in a saved turn's metadata.
	RealtimeInputItemID  string     `json:"-"`
	Providers            []string   `json:"providers,omitempty"`
	Models               []string   `json:"models,omitempty"`
	Aliases              []string   `json:"aliases,omitempty"`
	Status               []string   `json:"status,omitempty"`
	StopReasons          []string   `json:"stop_reasons,omitempty"`    // For filtering by stop reason (stop, length, content_filter, refusal, tool_calls, etc.)
	ToolCallNames        []string   `json:"tool_call_names,omitempty"` // Requests whose response called ANY of these function names (matched against the tool_call_names column)
	Objects              []string   `json:"objects,omitempty"`         // For filtering by request type (chat.completion, text.completion, embedding)
	ParentRequestID      string     `json:"parent_request_id,omitempty"`
	RequestID            string     `json:"request_id,omitempty"`     // Exact match on the log primary key, which is the request ID. Time-range filters are skipped for it so a unique ID is never hidden by the selected window.
	RootsOnly            bool       `json:"roots_only,omitempty"`     // Hide rows whose parent_request_id points at another row matching these same filters, so each chain lists as its root request only. Ignored when ParentRequestID is set.
	GroupSessions        bool       `json:"group_sessions,omitempty"` // Collapse every row sharing a session_id into that session's earliest chain-root row. Layered on top of RootsOnly; see SessionGroupingActive for when it applies.
	SelectedKeyIDs       []string   `json:"selected_key_ids,omitempty"`
	VirtualKeyIDs        []string   `json:"virtual_key_ids,omitempty"`
	RoutingRuleIDs       []string   `json:"routing_rule_ids,omitempty"`
	ComplexityTiers      []string   `json:"complexity_tiers,omitempty"`      // For filtering by routing complexity tier (SIMPLE, MEDIUM, COMPLEX)
	ComplexityMechanisms []string   `json:"complexity_mechanisms,omitempty"` // For filtering by complexity decision mechanism (semantic, decision, llm, session, skipped)
	AgentNames           []string   `json:"agent_names,omitempty"`           // Registered Agents whose context IDs correlate the matching LLM logs
	SessionID            string     `json:"session_id,omitempty"`            // Exact Bifrost session ID used for key stickiness and request correlation
	AgentCorrelationID   string     `json:"agent_correlation_id,omitempty"`  // Exact caller-supplied agent correlation ID
	TeamIDs              []string   `json:"team_ids,omitempty"`
	CustomerIDs          []string   `json:"customer_ids,omitempty"`
	UserIDs              []string   `json:"user_ids,omitempty"`
	BusinessUnitIDs      []string   `json:"business_unit_ids,omitempty"`
	ProjectIDs           []string   `json:"project_ids,omitempty"`
	TopicIDs             []string   `json:"topic_ids,omitempty"`           // Warp topics the request was filed under; a topic merged into one of these counts as it (see applyTopicFilter)
	RoutingEngineUsed    []string   `json:"routing_engine_used,omitempty"` // For filtering by routing engine (routing-rule, governance, loadbalancing)
	Apps                 []string   `json:"apps,omitempty"`                // Backend-detected client apps
	UserAgents           []string   `json:"user_agents,omitempty"`         // Raw User-Agent strings; kept for compatibility/debug filtering
	StartTime            *time.Time `json:"start_time,omitempty"`
	EndTime              *time.Time `json:"end_time,omitempty"`
	MinLatency           *float64   `json:"min_latency,omitempty"`
	MaxLatency           *float64   `json:"max_latency,omitempty"`
	MinTokens            *int       `json:"min_tokens,omitempty"`
	MaxTokens            *int       `json:"max_tokens,omitempty"`
	MinCost              *float64   `json:"min_cost,omitempty"`
	MaxCost              *float64   `json:"max_cost,omitempty"`
	MissingCostOnly      bool       `json:"missing_cost_only,omitempty"`
	CacheHitTypes        []string   `json:"cache_hit_types,omitempty"` // For filtering by local-cache hit type ("direct", "semantic")
	// ErrorTypes and ErrorCodes filter on the provider's error classification
	// inside error_details (error.type, error.code) - the same values the
	// error_type and error_code ranking dimensions group by, so a ranking row can
	// be opened as the rows it counted. Like those dimensions they only ever
	// match failed requests.
	ErrorTypes []string `json:"error_types,omitempty"`
	ErrorCodes []string `json:"error_codes,omitempty"`
	// StatusCodes filters on the HTTP status the failure came back with
	// (error_details.status_code). It is the error field every provider
	// populates: error.code is empty for most of them, so "what kind of 400s are
	// these" is usually a question about the status, not the code.
	StatusCodes []int `json:"status_codes,omitempty"`
	// GuardrailOutcomes keeps requests a guardrail acted on: "blocked" matches
	// a guardrail_intervention error or a recorded intervention, "detected" a
	// detect-only match in guardrail_debug. Several values are OR-ed together.
	GuardrailOutcomes []string          `json:"guardrail_outcomes,omitempty"`
	ContentSearch     string            `json:"content_search,omitempty"`
	MetadataFilters   map[string]string `json:"metadata_filters,omitempty"` // key=metadataKey, value=metadataValue for filtering by metadata
	// RankingLimit caps the number of rows returned by the ranking queries
	// (GetModelRankings / GetUserRankings / GetDimensionRankings). nil means
	// "use the store default" (defaultMaxRankingsLimit); a value <= 0 means
	// "return every ranked entity", which is what the dashboard export uses.
	RankingLimit *int `json:"ranking_limit,omitempty"`
}

SearchFilters represents the available filters for log searches

func (SearchFilters) EffectiveRankingLimit added in v1.5.5 

func (f SearchFilters) EffectiveRankingLimit(defaultLimit int) int

EffectiveRankingLimit resolves the ranking row cap: the store default when the caller did not specify one, 0 when the caller explicitly asked for an uncapped result.

func (SearchFilters) SessionGroupingActive added in v1.9.0 

func (f SearchFilters) SessionGroupingActive() bool

SessionGroupingActive reports whether this query should collapse each session_id to a single row. Session grouping sits on top of chain grouping: the row it keeps is the session's earliest *chain root*, so it is meaningless without RootsOnly. It is also skipped for the three queries that are already scoped to one group or one row — listing a session, listing a chain, or looking up an ID — where collapsing would hide the rows the caller asked for.

type SearchResult 

type SearchResult struct {
	Logs       []Log             `json:"logs"`
	Pagination PaginationOptions `json:"pagination"`
	Stats      SearchStats       `json:"stats"`
	HasLogs    bool              `json:"has_logs"`
}

SearchResult represents the result of a log search

type SearchStats 

type SearchStats struct {
	TotalRequests             int64   `json:"total_requests"`
	SuccessRate               float64 `json:"success_rate"`                            // Percentage of individual attempts that succeeded
	UserFacingSuccessRate     float64 `json:"user_facing_success_rate"`                // Percentage of user requests that ultimately succeeded (fallback chains counted as one request)
	UserFacingTotalRequests   int64   `json:"user_facing_total_requests"`              // Count of root requests (fallback_index = 0) used as denominator for UserFacingSuccessRate
	AverageLatency            float64 `json:"average_latency"`                         // Average latency in milliseconds
	TotalTokens               int64   `json:"total_tokens"`                            // Total tokens used
	PromptTokens              int64   `json:"prompt_tokens"`                           // Input tokens used
	CompletionTokens          int64   `json:"completion_tokens"`                       // Output tokens used
	TotalCost                 float64 `json:"total_cost"`                              // Total cost in dollars
	CacheHitRateTotalRequests *int64  `json:"cache_hit_rate_total_requests,omitempty"` // Completed requests used as local-cache hit-rate denominator
	DirectCacheHits           *int64  `json:"direct_cache_hits,omitempty"`             // Number of direct (exact) semantic cache hits
	SemanticCacheHits         *int64  `json:"semantic_cache_hits,omitempty"`           // Number of semantic (fuzzy) cache hits
}

type SessionDetailResult added in v1.3.1 

type SessionDetailResult struct {
	SessionID     string            `json:"session_id"`
	Logs          []Log             `json:"logs"`
	Pagination    PaginationOptions `json:"pagination"`
	Count         int64             `json:"count"`
	ReturnedCount int               `json:"returned_count"`
	HasMore       bool              `json:"has_more"`
}

type SessionSummaryResult added in v1.3.1 

type SessionSummaryResult struct {
	SessionID   string  `json:"session_id"`
	Count       int64   `json:"count"`
	TotalCost   float64 `json:"total_cost"`
	TotalTokens int64   `json:"total_tokens"`
	StartedAt   string  `json:"started_at,omitempty"`
	LatestAt    string  `json:"latest_at,omitempty"`
	DurationMs  int64   `json:"duration_ms"`
}

type SortBy 

type SortBy string
const (
	SortByTimestamp SortBy = "timestamp"
	SortByLatency   SortBy = "latency"
	SortByTokens    SortBy = "tokens"
	SortByCost      SortBy = "cost"
)

type SortOrder 

type SortOrder string
const (
	SortAsc  SortOrder = "asc"
	SortDesc SortOrder = "desc"
)

type ThroughputHistogramBucket added in v1.5.3 

type ThroughputHistogramBucket struct {
	Timestamp             time.Time `json:"timestamp"`
	TokensPerSecond       float64   `json:"tokens_per_second"`
	TotalCompletionTokens int64     `json:"total_completion_tokens"`
	TotalRequests         int64     `json:"total_requests"`
}

ThroughputHistogramBucket represents a single time bucket for token-generation throughput

type ThroughputHistogramResult added in v1.5.3 

type ThroughputHistogramResult struct {
	Buckets           []ThroughputHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                       `json:"bucket_size_seconds"`
}

ThroughputHistogramResult represents the throughput histogram query result

type TokenHistogramBucket added in v1.2.13 

type TokenHistogramBucket struct {
	Timestamp        time.Time `json:"timestamp"`
	PromptTokens     int64     `json:"prompt_tokens"`
	CompletionTokens int64     `json:"completion_tokens"`
	TotalTokens      int64     `json:"total_tokens"`
	CachedReadTokens int64     `json:"cached_read_tokens"`
}

TokenHistogramBucket represents a single time bucket for token usage

type TokenHistogramResult added in v1.2.13 

type TokenHistogramResult struct {
	Buckets           []TokenHistogramBucket `json:"buckets"`
	BucketSizeSeconds int64                  `json:"bucket_size_seconds"`
}

TokenHistogramResult represents the token histogram query result

type UserAgentMapping added in v1.5.0 

type UserAgentMapping struct {
	ID        string    `gorm:"primaryKey;type:varchar(36)" json:"id"`
	Pattern   string    `gorm:"type:varchar(512);not null" json:"pattern"`
	MatchType string    `gorm:"type:varchar(32);not null;index" json:"match_type"`
	App       string    `gorm:"type:varchar(128);not null;index" json:"app"`
	LogoMime  *string   `gorm:"type:varchar(128)" json:"logo_mime,omitempty"`
	IsActive  bool      `gorm:"index" json:"is_active"`
	CreatedAt time.Time `gorm:"index;not null" json:"created_at"`
	UpdatedAt time.Time `gorm:"not null" json:"updated_at"`
}

UserAgentMapping stores a custom rule for mapping User-Agent values to app labels.

func (*UserAgentMapping) BeforeCreate added in v1.5.0 

func (u *UserAgentMapping) BeforeCreate(tx *gorm.DB) error

BeforeCreate enforces a non-empty primary key before insert, guarding against callers that bypass the plugin layer's UUID assignment.

type UserRankingEntry added in v1.3.1 

type UserRankingEntry struct {
	UserID        string  `json:"user_id"`
	TotalRequests int64   `json:"total_requests"`
	TotalTokens   int64   `json:"total_tokens"`
	TotalCost     float64 `json:"total_cost"`
}

UserRankingEntry represents a single user's usage statistics.

type UserRankingResult added in v1.3.1 

type UserRankingResult struct {
	Rankings []UserRankingWithTrend `json:"rankings"`
}

UserRankingResult is the response for the user rankings endpoint.

type UserRankingTrend added in v1.3.1 

type UserRankingTrend struct {
	HasPreviousPeriod bool     `json:"has_previous_period"`
	RequestsTrend     float64  `json:"requests_trend"`
	TokensTrend       *float64 `json:"tokens_trend"`
	CostTrend         *float64 `json:"cost_trend"`
}

UserRankingTrend represents the percentage change compared to the previous period. TokensTrend and CostTrend follow ModelRankingTrend's nil convention.

type UserRankingWithTrend added in v1.3.1 

type UserRankingWithTrend struct {
	UserRankingEntry
	Trend UserRankingTrend `json:"trend"`
}

UserRankingWithTrend combines ranking entry with trend data.

type UserSpendEntry added in v1.9.0 

type UserSpendEntry struct {
	UserID    string  `json:"user_id"`
	TotalCost float64 `json:"total_cost"`
}

UserSpendEntry is one user's total cost inside a window.

type WarpConversation added in v1.9.0 

type WarpConversation struct {
	ID string `gorm:"type:varchar(36);primaryKey" json:"id"`
	// Indexed together with UpdatedAt because the only list query is "this
	// owner's threads, most recent first".
	OwnerID string `gorm:"type:varchar(255);not null;index:idx_warp_conversations_owner,priority:1" json:"owner_id"`
	Title   string `gorm:"type:varchar(255);not null" json:"title"`

	CreatedAt time.Time `gorm:"not null" json:"created_at"`
	// Two indexes, because there are two shapes of read. The composite one leads
	// with owner_id and serves the list ("this owner's threads, newest first").
	// The retention sweep filters on updated_at alone and crosses owners, so the
	// composite cannot serve it - a leading column it does not constrain forces a
	// full scan of a table that only grows.
	UpdatedAt time.Time `` /* 139-byte string literal not displayed */

	// Messages is loaded only for a detail read, bounded at
	// WarpMaxTranscriptMessages. The list view reports a count instead, so
	// opening the history does not pull every transcript.
	Messages []WarpMessage `gorm:"foreignKey:ConversationID;constraint:OnDelete:CASCADE" json:"messages,omitempty"`
	// TotalMessages is the thread's real message count, which can exceed
	// len(Messages) once the transcript bound applies. Populated on a detail
	// read; never stored.
	TotalMessages int `gorm:"-" json:"-"`
}

WarpConversation is one saved Warp thread.

OwnerID is the whole access-control story: reads always filter by it, and it is derived server-side from the caller's identity, never accepted from the request. On a deployment without authentication every conversation shares the global owner, which makes the history common to the deployment - the same query, just a different owner.

func (WarpConversation) TableName added in v1.9.0 

func (WarpConversation) TableName() string

TableName sets the table name for the Warp conversation model.

type WarpConversationStore added in v1.9.0 

type WarpConversationStore interface {
	// ListWarpConversations returns an owner's threads, most recent first.
	ListWarpConversations(ctx context.Context, ownerID string, limit int) ([]WarpConversation, error)
	// GetWarpConversation returns one thread with its messages in order, or
	// ErrWarpConversationNotFound when it does not exist for this owner.
	GetWarpConversation(ctx context.Context, ownerID, id string) (*WarpConversation, error)
	// CreateWarpConversation starts a thread.
	CreateWarpConversation(ctx context.Context, conversation *WarpConversation) error
	// AppendWarpMessages adds turns to a thread, bumping its updated time so it
	// sorts to the top of the list.
	AppendWarpMessages(ctx context.Context, ownerID, conversationID string, messages []WarpMessage) error
	// DeleteWarpConversation removes a thread and its messages.
	DeleteWarpConversation(ctx context.Context, ownerID, id string) error
	// DeleteWarpConversationIfEmpty removes a thread only if it has no messages,
	// checking and deleting as one operation, and reports whether it did. It is
	// the cleanup for a thread whose first append failed: a separate count and
	// delete let a concurrent append land in between and be deleted with it.
	DeleteWarpConversationIfEmpty(ctx context.Context, ownerID, id string) (bool, error)
	// PruneWarpConversations drops an owner's oldest threads beyond keep.
	PruneWarpConversations(ctx context.Context, ownerID string, keep int) (int64, error)
	// DeleteWarpConversationsOlderThan drops threads last touched before the
	// cutoff, across all owners, and returns how many it removed.
	//
	// One call deletes at most one bounded batch, so a caller clearing a backlog
	// must loop until a call returns zero - which is what Service.SweepHistory
	// does. The batch bound is deliberate: it keeps a single statement's lock and
	// transaction small on a table that can hold a deployment's whole chat
	// history, and it gives the caller a place to check ctx between batches.
	DeleteWarpConversationsOlderThan(ctx context.Context, cutoff time.Time) (int64, error)
	// CountWarpMessages returns message counts for the given threads in one
	// query, so a list view does not issue a count per row.
	CountWarpMessages(ctx context.Context, conversationIDs []string) (map[string]int, error)
	// SumWarpMessageUsage returns each thread's total tokens and cost in one
	// query, for the same reason as CountWarpMessages.
	SumWarpMessageUsage(ctx context.Context, conversationIDs []string) (map[string]WarpUsageTotals, error)
}

WarpConversationStore is the history surface, named as a group so a reader can see all of it at once and so warp can depend on this rather than on the whole LogStore.

It is embedded in LogStore rather than left optional and type-asserted for. An optional interface fails by disabling the feature silently: a store that forgot a method still compiles, still starts, and Warp simply serves no history, which surfaces as "my chats disappeared" long after the change that caused it. Embedding turns the same mistake into a build error.

type WarpMessage added in v1.9.0 

type WarpMessage struct {
	ID             string `gorm:"type:varchar(36);primaryKey" json:"id"`
	ConversationID string `gorm:"type:varchar(36);not null;index:idx_warp_messages_thread,priority:1" json:"conversation_id"`

	CreatedAt time.Time `gorm:"not null;index:idx_warp_messages_thread,priority:2" json:"created_at"`
	Position  int       `gorm:"not null;index:idx_warp_messages_thread,priority:3" json:"position"`

	Role    string `gorm:"type:varchar(16);not null" json:"role"`
	Content string `gorm:"type:text" json:"content"`
	// ToolCallsJSON records what Warp queried, so a reopened thread shows the
	// same provenance the live one did. Serialised rather than a child table:
	// it is only ever read and written whole, alongside its message.
	ToolCallsJSON string `gorm:"type:text" json:"-"`
	// QuestionJSON is the structured clarifying question a turn ended with,
	// serialised whole like the tool trace: a reopened thread rebuilds the same
	// selectable card the live turn showed, hints included.
	QuestionJSON string `gorm:"type:text" json:"-"`
	Error        string `gorm:"type:text" json:"error,omitempty"`
	// FinishReason records how the turn ended ("partial" when Warp ran out of
	// research steps and answered with what it had). Empty for user turns and
	// for answers that settled normally.
	FinishReason string `gorm:"type:varchar(32)" json:"finish_reason,omitempty"`
	// TotalTokens and Cost are what the answer cost to produce. Filed per
	// message so the history list can sum a thread's spend in one query.
	TotalTokens int     `gorm:"not null;default:0" json:"total_tokens,omitempty"`
	Cost        float64 `gorm:"not null;default:0" json:"cost,omitempty"`
}

WarpMessage is one persisted turn.

Ordering is (CreatedAt, Position), and Position is the index of the message within the append that wrote it - not a running count across the thread.

That distinction is what makes this lock-free. A dense count has to be read and reserved atomically, which on Postgres meant holding a row lock for the whole append and on ClickHouse is not expressible at all. Turns are always written as a pair by one caller that knows their order, so CreatedAt orders the appends and Position orders within one - and an answer can never be shown above the question it answers, which is the property that actually matters.

func (WarpMessage) TableName added in v1.9.0 

func (WarpMessage) TableName() string

TableName sets the table name for the Warp message model.

type WarpTopic added in v1.11.0 

type WarpTopic struct {
	ID                 string    `gorm:"type:varchar(36);primaryKey" json:"id"`
	Kind               string    `gorm:"type:varchar(16);not null" json:"kind"`
	ParentID           string    `gorm:"type:varchar(36);not null" json:"parent_id,omitempty"` // theme this topic belongs to
	Label              string    `gorm:"type:varchar(255);not null" json:"label"`
	Centroid           []byte    `json:"-"`
	AssignFloor        float64   `gorm:"not null" json:"assign_floor"`
	Cohesion           float64   `gorm:"not null" json:"cohesion"`
	ExampleLogIDsJSON  string    `gorm:"column:example_log_ids;type:text" json:"-"` // JSON array; the examples the label was written from, with members drawn at random
	EmbeddingSignature string    `gorm:"type:varchar(255);not null" json:"embedding_signature"`
	Status             string    `gorm:"type:varchar(16);not null;index:idx_warp_topics_status" json:"status"`
	MergedInto         string    `gorm:"type:varchar(36);not null" json:"merged_into,omitempty"`
	CreatedAt          time.Time `gorm:"not null" json:"created_at"`
	UpdatedAt          time.Time `gorm:"not null" json:"updated_at"`
}

WarpTopic is one topic or theme.

Centroid is the unit direction requests are compared against, encoded by EncodeWarpVector. AssignFloor is the similarity below which a request does not belong to the topic, measured when the topic was built. Both are only meaningful for vectors from the model named by EmbeddingSignature, which is why the signature is stored on the row: a changed embedding model must not compare its vectors against centroids from the old one.

func (*WarpTopic) ExampleLogIDs added in v1.11.0 

func (t *WarpTopic) ExampleLogIDs() []string

ExampleLogIDs returns the topic's example requests.

func (*WarpTopic) SetExampleLogIDs added in v1.11.0 

func (t *WarpTopic) SetExampleLogIDs(ids []string) error

SetExampleLogIDs records the topic's example requests.

func (WarpTopic) TableName added in v1.11.0 

func (WarpTopic) TableName() string

TableName sets the table name for the Warp topic model.

type WarpTopicAssignment added in v1.11.0 

type WarpTopicAssignment struct {
	LogID           string    `gorm:"type:varchar(255);primaryKey" json:"log_id"`
	Timestamp       time.Time `gorm:"not null;index:idx_warp_topic_assignments_ts;index:idx_warp_topic_assignments_topic_ts,priority:2" json:"timestamp"`
	TopicID         string    `gorm:"type:varchar(36);not null;index:idx_warp_topic_assignments_topic_ts,priority:1" json:"topic_id"`
	Similarity      float64   `gorm:"not null" json:"similarity"`
	SessionID       string    `gorm:"type:varchar(255);not null" json:"session_id,omitempty"`
	UserID          string    `gorm:"type:varchar(255);not null" json:"user_id,omitempty"`
	TeamID          string    `gorm:"type:varchar(255);not null" json:"team_id,omitempty"`
	VirtualKeyID    string    `gorm:"type:varchar(255);not null" json:"virtual_key_id,omitempty"`
	CustomerID      string    `gorm:"type:varchar(255);not null" json:"customer_id,omitempty"`
	BusinessUnitID  string    `gorm:"type:varchar(255);not null" json:"business_unit_id,omitempty"`
	TeamIDs         *string   `gorm:"type:text" json:"-"` // JSON array, as on logs
	CustomerIDs     *string   `gorm:"type:text" json:"-"` // JSON array, as on logs
	BusinessUnitIDs *string   `gorm:"type:text" json:"-"` // JSON array, as on logs
	Provider        string    `gorm:"type:varchar(255);not null" json:"provider,omitempty"`
	Model           string    `gorm:"type:varchar(255);not null" json:"model,omitempty"`
	App             string    `gorm:"type:varchar(128);not null" json:"app,omitempty"`
	Status          string    `gorm:"type:varchar(50);not null" json:"status,omitempty"`
	Cost            float64   `gorm:"not null" json:"cost"`
	Latency         float64   `gorm:"not null" json:"latency"` // ms; 0 = unmeasured
	TotalTokens     int       `gorm:"not null" json:"total_tokens"`
	LogCreatedAt    time.Time `gorm:"column:created_at;not null;index:idx_warp_topic_assignments_created_at" json:"-"`
	AssignedAt      time.Time `gorm:"not null" json:"assigned_at"`
}

WarpTopicAssignment is one request's place among the topics.

TopicID is empty for a request that matched nothing: it is still a row, so "how much traffic has no topic" is a count like any other. Everything below Similarity is copied from the log when the row is written. The five ownership columns keep the log's names and meanings exactly, because the access scope on a restricted caller's reads is a predicate over those names.

LogCreatedAt is the log's created_at, not the time this row was written. It is what retention keys on, so an assignment expires with the log it points at rather than some days after it.

func WarpTopicAssignmentFromLog added in v1.11.0 

func WarpTopicAssignmentFromLog(entry *Log) WarpTopicAssignment

WarpTopicAssignmentFromLog projects a log onto the assignment columns, for a caller that holds the log row already. It is the in-process twin of warpTopicLogColumns and copies exactly what that does, with TopicID, Similarity and AssignedAt left for the caller to fill.

func (WarpTopicAssignment) TableName added in v1.11.0 

func (WarpTopicAssignment) TableName() string

TableName sets the table name for the Warp topic assignment model.

type WarpTopicAssignmentFilter added in v1.11.0 

type WarpTopicAssignmentFilter struct {
	StartTime *time.Time
	EndTime   *time.Time
	// TopicIDs may include "" to select requests that matched no topic.
	TopicIDs        []string
	LogIDs          []string
	SessionIDs      []string
	UserIDs         []string
	TeamIDs         []string
	VirtualKeyIDs   []string
	CustomerIDs     []string
	BusinessUnitIDs []string
	Providers       []string
	Models          []string
	Apps            []string
	Statuses        []string
}

WarpTopicAssignmentFilter selects assignments. Each populated list narrows the selection; a zero filter selects every row the caller may see.

type WarpTopicBucket added in v1.11.0 

type WarpTopicBucket struct {
	TopicID  string  `gorm:"column:topic_id" json:"topic_id"`
	Bucket   int64   `gorm:"column:bucket_start" json:"bucket"` // unix seconds at which the bucket starts
	Requests int64   `gorm:"column:requests" json:"requests"`
	Errors   int64   `gorm:"column:errors" json:"errors"`
	Cost     float64 `gorm:"column:total_cost" json:"cost"`
	Tokens   int64   `gorm:"column:tokens" json:"tokens"`
}

WarpTopicBucket is what one topic's requests add up to in one time bucket.

type WarpTopicFilter added in v1.11.0 

type WarpTopicFilter struct {
	IDs                []string
	Kinds              []string
	Statuses           []string
	EmbeddingSignature string
	// OmitCentroids leaves Centroid unread, for callers that only list topics.
	OmitCentroids bool
}

WarpTopicFilter selects topics. A zero filter selects all of them.

type WarpTopicRetentionManager added in v1.11.0 

type WarpTopicRetentionManager interface {
	DeleteWarpTopicAssignmentsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
	DeleteWarpTopicUnmatchedBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
}

WarpTopicRetentionManager is implemented by stores that keep Warp's topic rows. Optional for the same reason MCPToolLogRetentionManager is. Both tables hold rows about individual logs, and expire on the log's own created time so neither outlives the log it describes.

type WarpTopicStore added in v1.11.0 

type WarpTopicStore interface {
	// UpsertWarpTopics writes topics whole, replacing any row with the same ID.
	// A caller changing one field reads the topic, changes it and writes it
	// back; there is no partial update, because ClickHouse has none.
	UpsertWarpTopics(ctx context.Context, topics []WarpTopic) error
	// ListWarpTopics returns the selected topics, oldest first.
	//
	// It is not narrowed by the caller's access scope: a topic has no owner.
	// Whether a restricted caller may see a topic's label is decided by the
	// caller of this method from the assignments that caller can see.
	ListWarpTopics(ctx context.Context, filter WarpTopicFilter) ([]WarpTopic, error)

	// UpsertWarpTopicAssignments writes one row per request, replacing any row
	// already written for the same request.
	UpsertWarpTopicAssignments(ctx context.Context, assignments []WarpTopicAssignment) error
	// SummarizeWarpTopicAssignments adds up the selected assignments per topic,
	// largest first, within the caller's access scope. Requests that matched
	// no topic are reported under the empty topic ID.
	SummarizeWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter) ([]WarpTopicUsage, error)
	// ListWarpTopicAssignments returns the selected assignments newest first,
	// within the caller's access scope.
	ListWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter, limit int) ([]WarpTopicAssignment, error)
	// DeleteWarpTopicAssignments removes the given requests' assignments, for
	// a run taking back the rows it wrote.
	DeleteWarpTopicAssignments(ctx context.Context, logIDs []string) error
	// DeleteWarpTopicAssignmentsUnmatchedSince removes the rows filed under no
	// topic at or after since, for a failed seed run taking back what it filed
	// there without keeping a list of every one.
	DeleteWarpTopicAssignmentsUnmatchedSince(ctx context.Context, since time.Time) error
	// BucketWarpTopicAssignments adds up the selected assignments per topic
	// and per bucket of bucketSizeSeconds, oldest bucket first, within the
	// caller's access scope. Buckets start at multiples of the size since the
	// Unix epoch, as the log histograms draw them, and a bucket with no
	// request has no row.
	BucketWarpTopicAssignments(ctx context.Context, filter WarpTopicAssignmentFilter, bucketSizeSeconds int64) ([]WarpTopicBucket, error)
	// DeleteWarpTopicAssignmentsBatch deletes up to batchSize assignments whose
	// log was created before cutoff, for the retention cleaner.
	DeleteWarpTopicAssignmentsBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)

	// AddWarpTopicUnmatched puts requests in the unmatched pool, replacing any
	// row already there for the same request.
	AddWarpTopicUnmatched(ctx context.Context, rows []WarpTopicUnmatched) error
	// ListWarpTopicUnmatched returns the pool for one embedding model, newest
	// first.
	ListWarpTopicUnmatched(ctx context.Context, embeddingSignature string, limit int) ([]WarpTopicUnmatched, error)
	// CountWarpTopicUnmatched reports the pool's size for one embedding model
	// without reading its vectors.
	CountWarpTopicUnmatched(ctx context.Context, embeddingSignature string) (int64, error)
	// DeleteWarpTopicUnmatched removes requests from the pool, once they have
	// a topic.
	DeleteWarpTopicUnmatched(ctx context.Context, logIDs []string) error
	// PruneWarpTopicUnmatched bounds the pool: it drops requests older than
	// olderThan, then the oldest beyond the newest keep. A zero olderThan or a
	// keep below one skips that bound.
	PruneWarpTopicUnmatched(ctx context.Context, olderThan time.Time, keep int) (deletedCount int64, err error)
	// DeleteWarpTopicUnmatchedBatch deletes up to batchSize pool rows whose log
	// was created before cutoff, for the retention cleaner.
	DeleteWarpTopicUnmatchedBatch(ctx context.Context, cutoff time.Time, batchSize int) (deletedCount int64, err error)
	// DeleteWarpTopicUnmatchedExcept drops every pool row embedded by a model
	// other than embeddingSignature: once the embedding model changes, those
	// vectors mean nothing and would never be clustered.
	DeleteWarpTopicUnmatchedExcept(ctx context.Context, embeddingSignature string) (deletedCount int64, err error)

	// DeleteWarpTopics removes topic and theme rows outright, for the upkeep
	// that prunes rows retired long enough ago that nothing reads them.
	DeleteWarpTopics(ctx context.Context, ids []string) error

	// AddWarpVectorDeletes records deleted logs whose vector delete failed,
	// replacing any row already there for the same log.
	AddWarpVectorDeletes(ctx context.Context, rows []WarpVectorDelete) error
	// ListWarpVectorDeletes returns up to limit of those, oldest first.
	ListWarpVectorDeletes(ctx context.Context, limit int) ([]WarpVectorDelete, error)
	// DeleteWarpVectorDeletes removes the rows of logs whose vector is gone.
	DeleteWarpVectorDeletes(ctx context.Context, logIDs []string) error

	// ListLogsForWarpTopics returns the assignment columns of the given logs:
	// everything an assignment copies from its log, with TopicID, Similarity
	// and AssignedAt left for the caller to fill. from and to bound the logs'
	// timestamps when non-zero, which lets a time-ordered store skip the rest.
	//
	// It is narrowed by the caller's access scope, as every log read is. The
	// jobs that file requests under topics carry none, so they read every log.
	ListLogsForWarpTopics(ctx context.Context, logIDs []string, from, to time.Time) ([]WarpTopicAssignment, error)
}

WarpTopicStore is the topic surface. It is embedded in LogStore for the reason WarpConversationStore is: a store that forgot a method should fail the build, not start and serve no topics.

type WarpTopicUnmatched added in v1.11.0 

type WarpTopicUnmatched struct {
	LogID              string    `gorm:"type:varchar(255);primaryKey" json:"log_id"`
	Timestamp          time.Time `gorm:"not null;index:idx_warp_topic_unmatched_ts" json:"timestamp"`
	Vector             []byte    `json:"-"`
	EmbeddingSignature string    `gorm:"type:varchar(255);not null" json:"embedding_signature"`
	LogCreatedAt       time.Time `gorm:"column:created_at;not null;index:idx_warp_topic_unmatched_created_at" json:"-"`
}

WarpTopicUnmatched is one request waiting for a topic that does not exist yet. Vector is its embedding, encoded by EncodeWarpVector.

func (WarpTopicUnmatched) TableName added in v1.11.0 

func (WarpTopicUnmatched) TableName() string

TableName sets the table name for the Warp unmatched-request model.

type WarpTopicUsage added in v1.11.0 

type WarpTopicUsage struct {
	TopicID    string  `gorm:"column:topic_id" json:"topic_id"`
	Requests   int64   `gorm:"column:requests" json:"requests"`
	Sessions   int64   `gorm:"column:sessions" json:"sessions"` // distinct sessions; requests without one are not counted
	Errors     int64   `gorm:"column:errors" json:"errors"`
	Cost       float64 `gorm:"column:total_cost" json:"cost"`
	Tokens     int64   `gorm:"column:tokens" json:"tokens"`
	AvgLatency float64 `gorm:"column:avg_latency" json:"avg_latency"` // ms, over requests that measured one
}

WarpTopicUsage is what one topic's requests add up to over a selection.

type WarpUsageTotals added in v1.9.0 

type WarpUsageTotals struct {
	TotalTokens int
	Cost        float64
}

WarpUsageTotals is what a thread has cost so far.

type WarpVectorDelete added in v1.11.0 

type WarpVectorDelete struct {
	LogID     string    `gorm:"type:varchar(255);primaryKey" json:"log_id"`
	Namespace string    `gorm:"type:varchar(255);not null" json:"namespace"` // empty: the configured one when retried
	CreatedAt time.Time `gorm:"not null;index:idx_warp_vector_deletes_created_at" json:"created_at"`
}

WarpVectorDelete is a deleted log whose Warp vector could not be removed when the log was. The log store deletes a log and its topic rows in one transaction, but the vector lives in the vector store, so its delete runs after and can fail on its own; this row is what lets upkeep retry it. It is written only when that delete fails, and removed once a retry succeeds.

func (WarpVectorDelete) TableName added in v1.11.0 

func (WarpVectorDelete) TableName() string

TableName sets the table name for the Warp pending vector delete model.

type WebhookDelivery added in v1.5.3 

type WebhookDelivery struct {
	ID         string `gorm:"primaryKey;type:varchar(36)" json:"id"`
	WebhookID  string `gorm:"type:varchar(36);index:idx_webhook_deliveries_webhook_id;not null" json:"webhook_id"`
	EndpointID string `` /* 149-byte string literal not displayed */
	AsyncJobID string `gorm:"type:varchar(255);not null" json:"async_job_id"`
	// RequestID is the async job's inference request id — the same id the
	// LLM logs record — copied here at attempt time. Empty when the job row
	// expired before the attempt.
	RequestID  string                 `gorm:"type:varchar(255);index:idx_webhook_deliveries_request_id" json:"request_id,omitempty"`
	Event      tables.WebhookEvent    `gorm:"type:varchar(255);index:idx_webhook_deliveries_event;not null" json:"event"`
	AttemptNo  int                    `gorm:"not null;default:0" json:"attempt_no"`
	Outcome    WebhookDeliveryOutcome `gorm:"type:varchar(50);index:idx_webhook_deliveries_outcome;not null" json:"outcome"`
	StatusCode int                    `gorm:"default:0" json:"status_code,omitempty"`
	Error      string                 `gorm:"type:text" json:"error,omitempty"`
	CreatedAt  time.Time              `` /* 140-byte string literal not displayed */
	ExpiresAt  *time.Time             `gorm:"index:idx_webhook_deliveries_expires_at" json:"expires_at,omitempty"`
}

WebhookDelivery records one webhook delivery attempt. Rows are insert-only — every attempt appends a new record and existing rows are never updated — and carry delivery metadata only, never event payloads or receiver response bodies. WebhookID is the delivery's `webhook-id` wire header, shared by every attempt of the same delivery.

func (WebhookDelivery) TableName added in v1.5.3 

func (WebhookDelivery) TableName() string

TableName sets the table name for GORM

type WebhookDeliveryOutcome added in v1.5.3 

type WebhookDeliveryOutcome string

WebhookDeliveryOutcome classifies the result of one webhook delivery attempt. 

const (
	// WebhookDeliveryOutcomeDelivered means the receiver acknowledged with a 2xx.
	WebhookDeliveryOutcomeDelivered WebhookDeliveryOutcome = "delivered"
	// WebhookDeliveryOutcomeRetryableFailure means the attempt failed but the
	// delivery has retries left.
	WebhookDeliveryOutcomeRetryableFailure WebhookDeliveryOutcome = "retryable_failure"
	// WebhookDeliveryOutcomePermanentFailure means the receiver rejected the
	// delivery with a non-retryable status; no further attempts are made.
	WebhookDeliveryOutcomePermanentFailure WebhookDeliveryOutcome = "permanent_failure"
	// WebhookDeliveryOutcomeExhausted means the final allowed attempt failed.
	WebhookDeliveryOutcomeExhausted WebhookDeliveryOutcome = "exhausted"
)

func (WebhookDeliveryOutcome) Value added in v1.5.5 

func (o WebhookDeliveryOutcome) Value() (driver.Value, error)

Value implements driver.Valuer so database drivers that append typed column values (e.g. clickhouse-go batch inserts) can serialize the type.

type WebhookDeliverySearchFilters added in v1.6.1 

type WebhookDeliverySearchFilters struct {
	EndpointIDs []string   `json:"endpoint_ids,omitempty"`
	Events      []string   `json:"events,omitempty"`
	Outcomes    []string   `json:"outcomes,omitempty"`
	StatusClass []string   `json:"status_class,omitempty"`
	RequestID   string     `json:"request_id,omitempty"`
	DeliveryID  string     `json:"delivery_id,omitempty"`
	StartTime   *time.Time `json:"start_time,omitempty"`
	EndTime     *time.Time `json:"end_time,omitempty"`
}

WebhookDeliverySearchFilters represents the available filters for webhook delivery history searches. Every field is optional; a zero-valued struct matches all history. Slice fields are OR-ed within themselves and AND-ed against each other.

Note the naming: DeliveryID is WebhookDelivery.WebhookID, the delivery-run id shared by every attempt of one delivery. EndpointIDs are the webhook endpoints those deliveries were addressed to.

type WebhookDeliverySearchResult added in v1.5.3 

type WebhookDeliverySearchResult struct {
	Deliveries []WebhookDelivery `json:"deliveries"`
	Pagination PaginationOptions `json:"pagination"`
}

WebhookDeliverySearchResult represents one page of webhook delivery history.

type WebhookDispatcher added in v1.5.3 

type WebhookDispatcher interface {
	EnqueueJobEvent(ctx context.Context, job *AsyncJob)
}

WebhookDispatcher queues a webhook notification for a job that reached a terminal state. Implementations must not block on receiver I/O.

type WebhookManager added in v1.5.3 

type WebhookManager interface {
	WebhookEndpointByName(endpointName string) (*configstoreTables.TableWebhookEndpoint, bool)
}

WebhookManager resolves registered webhook endpoints so submit-time references can be validated before a job is accepted.

type WriterConfig added in v1.3.20 

type WriterConfig struct {
	MaxBatchSize             int    `json:"max_batch_size,omitempty"`
	BatchInterval            string `json:"batch_interval,omitempty"`
	MaxBatchBytes            int    `json:"max_batch_bytes,omitempty"`
	WriteQueueCapacity       int    `json:"write_queue_capacity,omitempty"`
	DeferredUsageConcurrency int    `json:"deferred_usage_concurrency,omitempty"`
}

WriterConfig controls the async logging plugin writer queue and batch flush behavior.

func (*WriterConfig) WithDefaults added in v1.3.20 

func (c *WriterConfig) WithDefaults() WriterConfig

WithDefaults returns a copy of WriterConfig with zero-value fields filled.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.