Documentation
¶
Overview ¶
Package sqlite is obsdb's default backend: the observability schema in a single SQLite file on the CGO-free modernc.org/sqlite driver (thread/sqlite's choice). Open returns an obsdb.DB that also implements interface{ Hub() obsdb.Hub } — every Write publishes its frames to that in-process hub before returning, which is what setup A's live lane runs on (weft/otel's local sink writes, Studio's SSE handler subscribes, no network).
The handle shape is one writer connection plus a read pool: the local sink's synchronous processors write on the run's goroutine, Studio reads concurrently; WAL lets a reader in another process see the same data through its own Open.
Index ¶
- Variables
- func Open(path string, opts ...Option) (obsdb.DB, error)
- type DB
- func (d *DB) Catalogs(ctx context.Context, runID string) (_ []obsdb.ToolsRecord, err error)
- func (d *DB) Close() error
- func (d *DB) Compactions(ctx context.Context, runID string) (_ []obsdb.Compaction, err error)
- func (d *DB) Events(ctx context.Context, runID string, after int64, limit int) (_ obsdb.EventPage, err error)
- func (d *DB) Experiment(ctx context.Context, id string) (_ obsdb.Experiment, err error)
- func (d *DB) Experiments(ctx context.Context) (_ []obsdb.Experiment, err error)
- func (d *DB) Hub() obsdb.Hub
- func (d *DB) OtherLogs(ctx context.Context, runID string, q obsdb.LogQuery) (_ obsdb.LogPage, err error)
- func (d *DB) Prompt(ctx context.Context, runID, hash string) (_ obsdb.PromptRecord, err error)
- func (d *DB) Requests(ctx context.Context, runID string, q obsdb.RequestQuery) (_ []obsdb.RequestRecord, err error)
- func (d *DB) ResolvePublicID(ctx context.Context, publicID string) (_ string, err error)
- func (d *DB) Run(ctx context.Context, id string) (_ obsdb.RunDetail, err error)
- func (d *DB) RunSpans(ctx context.Context, runID string) (_ []obsdb.Span, err error)
- func (d *DB) Runs(ctx context.Context, q obsdb.RunQuery) (_ obsdb.RunPage, err error)
- func (d *DB) SaveExperiment(ctx context.Context, e obsdb.Experiment) (err error)
- func (d *DB) Session(ctx context.Context, id string) (_ obsdb.SessionDetail, err error)
- func (d *DB) Sessions(ctx context.Context, q obsdb.SessionQuery) (_ obsdb.SessionPage, err error)
- func (d *DB) Tools(ctx context.Context, runID, hash string) (obsdb.ToolsRecord, error)
- func (d *DB) Trace(ctx context.Context, traceID string) (_ []obsdb.Span, err error)
- func (d *DB) Transcript(ctx context.Context, runID string) ([]json.RawMessage, error)
- func (d *DB) TranscriptBatches(ctx context.Context, runID string) (_ []obsdb.TranscriptBatch, err error)
- func (d *DB) Write(ctx context.Context, b obsdb.Batch) (err error)
- type Option
Constants ¶
This section is empty.
Variables ¶
var ErrNewerSchema = errors.New("sqlite: database schema is newer than this obsdb")
ErrNewerSchema is returned by Open when the file's obsdb_migrations is ahead of this binary's highest migration: a database written by a newer weft fails loudly instead of silently ignoring tables it does not know.
Functions ¶
func Open ¶
Open opens (creating if needed) the database at path and brings its schema up to date. ":memory:" works — one in-process database. File connections carry journal_mode=WAL (a persistent property of the file, switched once), synchronous=NORMAL, busy_timeout=30000, foreign_keys=ON and _txlock=immediate (preventing deferred-to-writer upgrade deadlocks); the writer handle allows a single connection so every write is serialized, the read pool serves queries.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is the SQLite backend. Create it with Open; the zero value is not usable.
func (*DB) Compactions ¶ added in v0.10.0
func (*DB) Experiment ¶
Experiment returns one experiment; ErrNotFound otherwise.
func (*DB) Experiments ¶
Experiments lists the saved experiments, newest update first.
func (*DB) Hub ¶
Hub returns the DB's in-process live hub: every Write publishes its frames to it before returning (D4 — this handle is what setup A's studio.DB(otel.LocalDB()) shares).
func (*DB) OtherLogs ¶ added in v0.10.0
func (d *DB) OtherLogs(ctx context.Context, runID string, q obsdb.LogQuery) (_ obsdb.LogPage, err error)
OtherLogs reads a run's app log records from other_logs, where Write puts every record with no weft.run.id (obsdb.ReadOtherLogs: the attribution through the run's spans, the order, the paging). The candidates are read by trace id (other_logs_trace) inside the run's time window, the first obsdb.MaxLogCandidates by time.
func (*DB) Requests ¶ added in v0.10.0
func (d *DB) Requests(ctx context.Context, runID string, q obsdb.RequestQuery) (_ []obsdb.RequestRecord, err error)
func (*DB) ResolvePublicID ¶
func (*DB) SaveExperiment ¶
SaveExperiment upserts one experiment by id. A new id stamps Created; an existing one keeps it and moves Updated.
func (*DB) Sessions ¶
func (d *DB) Sessions(ctx context.Context, q obsdb.SessionQuery) (_ obsdb.SessionPage, err error)
Sessions is a GROUP BY session_id over top-level, non-playground runs (S3.4): turns, first/last seen, summed usage, and the newest turn's derived status.
func (*DB) Transcript ¶
func (*DB) TranscriptBatches ¶ added in v0.10.0
func (*DB) Write ¶
Write stores one batch in a single transaction: spans and the event/messages records first (INSERT OR IGNORE on the transport idempotency keys), then one runs upsert per run the batch touched.
The rules (S3.4, D3): deltas are counted, never inserted unless KeepDeltas; heartbeats are never inserted, they only move last_seen; counts increment only for rows actually inserted, so retries don't inflate them; any record or span — heartbeats and deltas included — sets last_seen to its max, started_ns to its min (a span's start, the earliest winning: run_start's time, or the invoke_agent span's just before it) and fills empty identity columns; run_finish sets the terminal fields; the invoke_agent span sets trace, finish, usage, steps and, on error, failed and err. A run first seen through a later record (a reordered batch) gets a provisional started_ns, corrected when the earlier rows land.
After the commit, every frame the batch produced is published to the DB's hub before Write returns — an in-process subscriber sees a record within this call (setup A's live lane).
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures Open.
func KeepDeltas ¶
func KeepDeltas() Option
KeepDeltas turns delta storage on for debugging (Q4, closed): deltas are counted but never stored by default, on their own counter, so storing them can never open a hole in the durable event sequence.
Source Files