imbhgo

package module
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

imbh-go

A Go binding for IMBH — an embeddable, Rust observability database (logs, traces, metrics on Apache DataFusion) — with zero-copy Apache Arrow query results, fused onto Go's scheduler via sable.

You open an IMBH database from Go, feed it OpenTelemetry (OTLP) data, and query it with SQL or typed observability queries. Query results cross the language boundary as Arrow record batches without a copy: Go holds IMBH's Arc-refcounted Arrow buffers by pointer and releases them when done.

db, _ := imbhgo.OpenInMemory()
defer db.Close()
ctx := context.Background()

db.IngestOTLPLogs(otlpBytes)                 // what any OTLP/HTTP exporter sends

logs, _ := db.QueryLogsTyped(ctx, imbhgo.LogQuery{Service: "checkout", Match: "error"})
for _, e := range logs {
    fmt.Println(e.Time, e.Service, e.Body)
}

Status: early but working. The full path — open → ingest → SQL, typed queries, and the LGTM query languages (PromQL / LogQL / TraceQL), all zero-copy → errors → cancellation → backpressure — is implemented and tested (46 tests under -race, including on-disk durability, concurrency-under-load, and the admin / lifecycle / cursor-paging surface), and the memory-ownership protocol is leak-verified two independent ways (an in-process counter and a Valgrind gate). Dependencies are now external — imbh from crates.io and sable git-pinned — so it builds without local checkouts, and CI (.github/workflows/ci.yml) runs the whole gate on linux/amd64 and linux/arm64 for every push and pull request. See Feature coverage for what is and isn't exposed, and Limitations.

How it works

flowchart LR
    Go["Go program<br/>(imbhgo package)"]

    subgraph lib["libimbhgo.a — one static library"]
        direction LR
        Sable["sable<br/>Rust ⇄ Go runtime fusion"]
        Imbh["imbh::Db<br/>DataFusion + Tantivy"]
    end

    Go -->|"OTLP ingest (bytes)"| Sable
    Go -->|"SQL / typed queries"| Sable
    Sable --> Imbh
    Imbh -.->|"zero-copy Arrow batches<br/>(C Data Interface)"| Go
  • Everything links into one combined static library (libimbhgo.a) containing IMBH, sable's runtime, and the binding's handlers.
  • Queries stream one Arrow batch per await: the goroutine parks between batches while IMBH's engine runs, so no OS thread is blocked and the query executes lazily (bounded memory).
  • Each result batch crosses via the Arrow C Data Interface (FFI_ArrowArray), imported by arrow-go/cdata — no serialization, no GoBytes copy.

The full design is in ARCHITECTURE.md.

Requirements

  • Go 1.26.4 (pinned — sable reaches Go's internal ABI via //go:linkname). go.mod enforces this toolchain, so Go downloads it automatically.
  • cgo (a C toolchain) to link the static library into your binary.
  • The github.com/apache/arrow-go/v18 module (for reading result batches).
  • Rust (stable, 1.96+) is needed only if you build the library from source. Consumers using a prebuilt archive (below) do not need Rust.

Prebuilt libimbhgo.a archives are published per platform (see Using a prebuilt library).

Using a prebuilt library (no Rust build)

You can depend on the binding without ever building the Rust side. cmd/imbhgo-fetch downloads the prebuilt libimbhgo.a for your platform from the matching GitHub release, verifies its checksum, and prints the CGO_LDFLAGS to link against it:

go get github.com/moriyoshi/imbh-go@v0.5.1
eval "$(go run github.com/moriyoshi/imbh-go/cmd/imbhgo-fetch@v0.5.1 -print-env)"
go build -tags sable_extern_lib ./...

  • The sable_extern_lib build tag is required — it makes sable's Go package link the combined archive rather than its own libsable.a.

  • -print-env emits POSIX shell syntax on every platform, including Windows — the shell that consumes the line is the one you invoked the tool from, and on Windows CI that is normally git-bash / MSYS2. From a native Windows shell, ask for its dialect explicitly:

    for /f "delims=" %i in ('go run github.com/moriyoshi/imbh-go/cmd/imbhgo-fetch@v0.5.1 -print-env -shell cmd') do @%i

    go run github.com/moriyoshi/imbh-go/cmd/imbhgo-fetch@v0.5.1 -print-env -shell powershell | Invoke-Expression

  • The fetch tool caches the archive under your user cache dir (override with -dest) and re-detects glibc vs musl on Linux automatically (override with -libc).

  • Prebuilt cells: Linux amd64/arm64 (glibc and musl), macOS amd64/arm64, and Windows amd64 (best-effort). Each archive is pinned to the Go toolchain in go.mod.

Building from source

To build the static library yourself (co-development, or a platform with no prebuilt), build the Rust side first; the Go package links it.

make            # cargo build --release in rust/  → rust/target/release/libimbhgo.a
make test       # go test -tags sable_extern_lib -race ./...

Then compile your program with the sable_extern_lib build tag:

go build -tags sable_extern_lib ./...

(The per-platform cgo linker flags live in link_linux.go / link_darwin.go / link_windows.go; they default to rust/target/release for a local build, and defer to CGO_LDFLAGS for a prebuilt.)

Cutting a release (maintainers)
make release VERSION=v0.1.2   # rewrite the version everywhere, then build + vet + race-test

That rewrites internal/release.Version — which the release workflow requires the tag to match — along with the version references in this README and in cmd/imbhgo-fetch, then runs the local gate. It stops there and prints the remaining steps: commit, merge to main, then git push origin v0.1.2. Pushing the tag is what triggers .github/workflows/release.yml, which cross-builds every prebuilt cell, attaches the archives plus SHA256SUMS to the release, and smoke-tests the result as a consumer would.

Quick start

A complete runnable tour lives in examples/quickstart — it ingests OTLP logs and metrics and queries them three ways:

make            # build the static library
make example    # go run -tags sable_extern_lib ./examples/quickstart

The package initializes the runtime automatically on first use — just import and go.

package main

import (
	"context"
	"fmt"

	imbhgo "github.com/moriyoshi/imbh-go"
)

func main() {
	db, err := imbhgo.OpenInMemory() // or imbhgo.Open("/path/to/data")
	if err != nil {
		panic(err)
	}
	defer db.Close()
	ctx := context.Background()

	// Ingest OTLP/HTTP export-request protobuf bytes (from any OTel SDK exporter).
	if _, err := db.IngestOTLPLogs(otlpLogBytes); err != nil {
		panic(err)
	}

	// Query with SQL — results stream as zero-copy Arrow batches.
	rows, err := db.Query(ctx, "SELECT service, count(*) AS n FROM logs GROUP BY service")
	if err != nil {
		panic(err)
	}
	defer rows.Close()
	for {
		rec, ok, err := rows.Next()
		if err != nil {
			panic(err)
		}
		if !ok {
			break
		}
		fmt.Println(rec) // an arrow.RecordBatch
		rec.Release()    // return the buffers when done
	}
}

Querying

SQL (lazy, zero-copy)

Query streams the result batch-by-batch through IMBH's lazy scan. Tables: logs, spans, metrics_gauge, metrics_sum, metrics_histogram, and more. IMBH's UDFs are available in SQL — including histogram_quantile, matches (full-text), and json_get_str:

rows, _ := db.Query(ctx,
    "SELECT histogram_quantile(0.95, explicit_bounds, bucket_counts) AS p95 " +
        "FROM metrics_histogram WHERE metric = 'http.server.duration'")

Query returns *Rows; iterate with Next() (arrow.RecordBatch, ok bool, err error) until ok is false, then check Err(). Every query takes a context.Context as its first argument — cancel a running query by cancelling that ctx, and a parked Next is interrupted and reports context.Canceled from Err().

Typed queries

Endpoint-shaped queries as native Go structs. Each has a raw form (returns *Rows of Arrow batches) and a decoded form (returns Go structs).

// Logs → []LogEntry
entries, _ := db.QueryLogsTyped(ctx, imbhgo.LogQuery{
    Service: "checkout",
    Match:   "timeout",       // full-text on the body
    Limit:   100,
})

// Metric range → a Matrix (one series per group-by label set)
m, _ := db.QueryMetricsTyped(ctx, imbhgo.MetricQuery{
    Metric:  "cpu.utilization",
    Step:    int64(time.Second),
    Start:   start.UnixNano(),
    End:     end.UnixNano(),
    GroupBy: []string{"host"},
})
for _, s := range m.Series {
    fmt.Println(s.Labels, len(s.Points))
}

// Span RED metrics → []SpanMetricPoint (calls / errors / p50 / p95 / p99)
red, _ := db.QuerySpanMetricsTyped(ctx, imbhgo.SpanMetricsQuery{
    Service: "checkout",
    Step:    int64(time.Minute),
    Start:   start.UnixNano(),
    End:     end.UnixNano(),
})

Typed queries collect eagerly (they materialize the result), so prefer them for bounded results (a limited page, a fixed-step range) and use Query(ctx, sql) for large, unbounded scans.

Every GroupBy / attribute predicate (LogVolumeBy, MetricQuery.GroupBy, SpanMetricsQuery.GroupBy, LogQuery.AttrEq and friends) also accepts "service.name" — or its column spelling "service" — even though service is a resource attribute lifted into a built-in column rather than a record attribute. Requires imbh 0.3.0: earlier versions resolved the key against the record attributes, silently collapsing a per-service breakdown into one empty-labelled series with the counts merged.

LGTM query languages (PromQL / LogQL / TraceQL)

IMBH implements the Grafana-stack query languages as explicitly-versioned compatibility profiles, and the binding exposes them over the same zero-copy Arrow path. Constructs outside a profile are rejected with a clear diagnostic rather than silently approximated.

// PromQL → labeled series. Metric names resolve against the stored catalog
// (OTel dots map to Prometheus underscores: cpu.util → cpu_util).
series, _ := db.QueryPromQLSeries(ctx, "rate(http_requests_total[5m])", start, end, step)
for _, s := range series {
    fmt.Println(s.Labels, len(s.Points))
}

// LogQL has two result shapes, as in Loki:
lines,  _ := db.QueryLogQLLines(ctx, `{service="checkout"} |= "error"`, start, end, 100) // streams
counts, _ := db.QueryLogQLSeries(ctx, `count_over_time({service="checkout"}[5m])`, start, end, step) // matrix

// TraceQL → matching traces + the span ids its spanset selected.
// Note attribute scope: service.name is a *resource* attribute.
matches, _ := db.QueryTraceQLMatches(ctx, `{ resource.service.name = "checkout" }`, start, end)

// …and follow a match through to that trace's spans (zero-copy).
spans, _ := db.GetTraceSpans(ctx, matches[0].TraceID)

Each also has a raw *Rows form (QueryPromQL, QueryLogQL, QueryTraceQL, GetTrace). Like every query method, all take a context.Context first argument for cancellation.

Ingesting

IngestOTLPLogs/IngestOTLPTraces/IngestOTLPMetrics take the protobuf bytes an OTLP/HTTP exporter sends (an ExportLogsServiceRequest, etc.) and return a Receipt:

r, _ := db.IngestOTLPLogs(otlpBytes)
fmt.Println(r.Accepted, r.Rejected, r.Durable)

Data is queryable immediately, before any Flush(). Flush() seals the in-memory buffer into an on-disk segment (to bound memory).

Backpressure

By default ingest is unbounded and never refused. To cap concurrency, set a global in-flight limit and use the Try* variants, which return ErrBackpressure instead of piling on:

imbhgo.SetMaxInFlight(64)
if _, err := db.TryIngestOTLPLogs(otlpBytes); errors.Is(err, imbhgo.ErrBackpressure) {
    // shed load or retry with backoff
}
stats := imbhgo.RuntimeStats() // InFlight, Rejected, MaxInFlight, …

The cap is process-global and also bounds concurrent open result streams (an open Rows holds a slot until Close).

Zero-copy: lifetime rules (important)

Result batches wrap IMBH-owned Arrow buffers that are freed when you Release() the batch:

  • Always Close() a Rows and Release() each RecordBatch you take from Next.
  • Values read from a batch alias its buffers. In particular, arrow-go's String.Value(i) and binary accessors return data that points into the Arrow buffer without copying. Anything you keep past that batch's Release() must be copied out (e.g. strings.Clone for strings). The typed decoders (QueryLogsTyped, etc.) do this for you.

Feature coverage

What this binding exposes today, against IMBH's own surface. "Reachable via SQL" means the capability works but through db.Query(ctx, sql) rather than a dedicated method.

Ingest & lifecycle
IMBH capability Go binding Notes
OTLP ingest (logs / traces / metrics) ✅ IngestOTLPLogs / …Traces / …Metrics returns a Receipt
Backpressure-aware ingest ✅ TryIngestOTLP*, SetMaxInFlight, RuntimeStats ErrBackpressure at the cap
Open in-memory / on-disk ✅ OpenInMemory, Open(path)
flush (seal buffer → segment) ✅ Flush
Read-only open (open_read_only) ✅ OpenReadOnly many-reader / single-writer; writes on the handle are rejected
Builder options (memory budget, WAL mode, retention, compression, maintenance, promote) ✅ OpenWith(DbOptions) host-runtime-Handle variants (async ingest, runtime-driven maintenance) deferred
Flush policy (DbBuilder::flush, imbh 0.2.0) ✅ DbOptions.Flush imbh's spec string ("interval=5s,wal=64MiB", or "manual"); needs MaintenanceBackgroundNs set, since that is what runs the scheduler
Duplicate-timestamp policy (DbBuilder::duplicates, imbh 0.5.0) ✅ DbOptions.Duplicates imbh's spec string: "error_on_read" (default, fails the PromQL read), "last_wins" (collapse at read), "reject[,recent=N]" (drop at ingest → Receipt.Rejected, DbStats.IngestRejected)
Ops: stats, compact, maintain, snapshot, segments, segment_files, durable_through, export (Arrow IPC) ✅ Stats / Compact / Maintain / Snapshot / Segments / SegmentFiles / DurableThrough / Export (+ExportRecords) writer-only ops error on a read-only handle
Query surfaces
IMBH capability Go binding Notes
SQL over logs / spans / metrics_* ✅ Query(ctx, sql) lazy, zero-copy, cancellable
SQL UDFs (histogram_quantile, matches, json_get_str, hex) ✅ via SQL incl. computed quantiles
Typed log query ✅ QueryLogs, QueryLogsTyped → []LogEntry curated field subset (below)
Metric range (resampled) ✅ QueryMetrics, QueryMetricsTyped → Matrix GroupBy splits series
Raw metric samples ✅ QueryMetricPoints, …Typed → []MetricPoint unaggregated; histogram → raw Rows
Span RED metrics ✅ QuerySpanMetrics, …Typed → []SpanMetricPoint calls / errors / p50 / p95 / p99
One trace's spans ✅ GetTrace, GetTraceSpans → []Span composes with TraceQL matches
Assembled Trace tree ✅ GetTraceForest, AssembleTrace → []*TraceNode parent→child forest; orphans surface as roots
Log pagination (LogPage cursor) ✅ QueryLogPage → LogPage{Entries,Next,Stats} opaque resume Cursor + per-page QueryStats
logs().volume / volume_by ✅ LogVolume / LogVolumeBy → []VolumeBucket time-bucketed counts, optional group_by
logs().count ✅ CountLogs(ctx, LogQuery) → uint64 full count(*) over the filter; ignores Limit/Backward
traces().search (TraceSummary) ✅ SearchTraces → []TraceSummary full attr-predicate set on TraceQuery
metrics().instant (Vector) ✅ QueryMetricInstant → []InstantSample last sample per series
metrics().catalog / series / exemplars ✅ MetricCatalog / MetricSeries / MetricExemplars
attrs() discovery (names, values) ✅ AttrNames / AttrValues
LGTM query languages
Capability Go binding Notes
PromQL ✅ QueryPromQL, QueryPromQLSeries → []Series metric names auto-resolved from the catalog (dots→underscores)
LogQL — range aggregation (matrix) ✅ QueryLogQL, QueryLogQLSeries → []Series count_over_time, rate, …
LogQL — bare selector (streams) ✅ QueryLogQLLines → []LogEntry {service="x"} |= "err"
TraceQL ✅ QueryTraceQL, QueryTraceQLMatches → []TraceMatch returns trace + selected span ids
Out-of-profile constructs ❌ by design rejected with a stable diagnostic rather than approximated
Typed-query field coverage

LogQuery now covers IMBH's builder broadly: Service, Match, AttrEq, Start, End, Limit, Backward, plus TraceID/SpanID correlation, SeverityAtLeast, and the richer attribute predicates (AttrExists, AttrMatches, AttrIn/AttrNotIn, AttrGt/Ge/Lt/Le, AttrRegex); cursor paging is via QueryLogPage. TraceQuery (trace search) exposes service / name / status / kind / duration bounds / time range / limit and the same attribute-predicate set. SpanMetricsQuery and MetricQuery cover the common fields.

Transport & correctness
Property Status
Zero-copy Arrow results (C Data Interface) ✅ all query surfaces
Lazy streaming (bounded memory) ✅ SQL only — typed/LGTM queries collect eagerly upstream
Context cancellation ✅ ctx first arg on every query
Error surfacing ✅ Rows.Err(), Go errors on byte ops
Leak-verified ownership ✅ live-batch counter + Valgrind gate

Limitations & roadmap

Honest current state:

  • Packaging. Consumed as external deps — imbh from crates.io (0.1.1) and sable git-pinned to a main commit — so no local checkouts are required to build. CI runs the standard gate on every push and pull request; cold build is minutes; the static archive is large.
  • Durability. Covered by TestDurabilityReopen (ingest → flush → close → reopen the same path → query without re-ingest, exercising WAL replay / segment reload). Read-only opens are tested too.
  • Concurrency. Stress-tested by TestConcurrentQueries (48 goroutines × 60 iters, mixed SQL + typed queries against one shared Db, all under -race).
  • Portability. linux/{amd64,arm64} and windows/amd64 are gated in CI: full build + go test -race, with the Windows leg building for x86_64-pc-windows-gnu and linking through the cgo directives natively. Durable (on-disk) DBs need imbh 0.1.1 or newer on Windows — 0.1.0 failed every on-disk open there (imbh#3). The Apple cells are compile-checked in CI (cargo check on a macOS runner) and built on release tags, but the Go suite has never run there.
  • Query surface. SQL, typed queries, LGTM (PromQL / LogQL / TraceQL), cursor-paged logs (QueryLogPage
    • QueryStats), trace search, log volume, metric catalog / series / exemplars / instant, and attribute discovery are all exposed, alongside the read-only / builder-options / ops admin surface — see Feature coverage for the exact matrix. Remaining: typed and LGTM queries collect eagerly upstream (only SQL streams lazily), logs().count is reachable via SQL rather than a dedicated method, and the two host-runtime-Handle builder variants (async ingest, runtime-driven maintenance) are deferred.

Testing

make test            # go test -tags sable_extern_lib -race ./...
make leak-valgrind   # Valgrind buffer-leak gate (requires valgrind)

License

Licensed under the Apache License, Version 2.0. This binding also links IMBH (Apache-2.0) and sable (MIT).

Documentation

Overview

Package imbhgo is a Go binding for IMBH — an embeddable observability database — with zero-copy Arrow query results fused onto Go's scheduler via sable. (Binding plan M0: open → SQL → zero-copy rows. Ingest and typed queries land in M1/M2.)

Build with -tags sable_extern_lib so sable's Go package contributes no -lsable of its own; the combined staticlib below (which contains both imbhgo_* and sable_* symbols) is linked instead.

Index

Constants

View Source 
const Version = release.Version

Version is the module release this source corresponds to. It is bumped in lockstep with each tagged release, and the prebuilt libimbhgo.a assets on GitHub Releases are named after it. The canonical value lives in internal/release (which is cgo-free so cmd/imbhgo-fetch can share it without depending on the archive); this re-export lets consumers read imbhgo.Version at runtime.

Variables

View Source 
var ErrBackpressure = sable.ErrBackpressure

ErrBackpressure is returned by the Try* entry points and by Query when the fused runtime is at its in-flight cap (see SetMaxInFlight). No work was admitted; the caller should shed load or retry.

Functions

func SetMaxInFlight 

func SetMaxInFlight(max uint64)

SetMaxInFlight caps the number of concurrently in-flight *admitted* operations (0 = unbounded, the default). The cap is process-global (one fused runtime) and applies to every admission-controlled entry point: TryIngestOTLP* and Query — a live Rows holds a slot until Close, so the cap also bounds concurrent open result streams. The blocking IngestOTLP* path is never refused (it still counts toward the in-flight gauge). Observe rejections via RuntimeStats().Rejected.

Types

type CompactionReport 

type CompactionReport struct {
	SegmentsMerged  uint64 `json:"segments_merged"`
	SegmentsCreated uint64 `json:"segments_created"`
}

CompactionReport summarizes a compact() pass (imbh: Db::compact).

type Cursor 

type Cursor []byte

Cursor is an opaque page-resume token. Obtain it from LogPage.Next and pass it back to QueryLogPage to fetch the following page (reusing the same filters/limit/direction). Treat it as opaque — do not construct or interpret it. The zero (nil) value requests the first page.

func (Cursor) HasMore 

func (c Cursor) HasMore() bool

HasMore reports whether a following page exists (i.e. this cursor points somewhere).

type DB 

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

DB is a handle to an embedded IMBH database.

func Open 

func Open(path string) (*DB, error)

Open opens a durable, on-disk database at path (created if absent).

func OpenInMemory 

func OpenInMemory() (*DB, error)

OpenInMemory opens an ephemeral, process-local database (great for tests and dev loops).

func OpenReadOnly 

func OpenReadOnly(path string) (*DB, error)

OpenReadOnly opens an existing on-disk database at path read-only. It takes no writer lock, so it coexists with the single writer process and with other readers; queries see the writer's segments unioned with its live WAL tail (near-real-time). Every write returns an error.

Rejected if the writer had its WAL disabled (the reader could then get only seal-interval freshness, not near-real-time); use OpenWith with AllowStaleReads to accept that. (imbh: Db::open_read_only.)

func OpenWith 

func OpenWith(opts DbOptions) (*DB, error)

OpenWith opens a durable database configured by opts (imbh: Db::builder(path) + setters).

func (*DB) AttrNames 

func (db *DB) AttrNames(ctx context.Context) ([]string, error)

AttrNames returns every distinct attribute/label key present on any signal (logs, spans, metrics), plus "service.name" when any record carries a service. Sorted.

func (*DB) AttrValues 

func (db *DB) AttrValues(ctx context.Context, key string) ([]string, error)

AttrValues returns the distinct string values for one attribute key across every signal, sorted.

func (*DB) Close 

func (db *DB) Close()

Close drops the database handle.

func (*DB) Compact 

func (db *DB) Compact() (CompactionReport, error)

Compact merges segments to reduce fragmentation. Writer-only.

func (*DB) CountLogs 

func (db *DB) CountLogs(ctx context.Context, q LogQuery) (uint64, error)

CountLogs returns the number of log records matching q — imbh's logs().count(filter), a full count(*) over the filter that ignores q.Limit and q.Backward (they bound/order returned rows, not the total). It scans without materializing rows, so it is cheaper than draining QueryLogs when you only need the tally. Equivalent to SELECT count(*) via Query, but driven by the same typed LogQuery.

func (*DB) DurableThrough 

func (db *DB) DurableThrough() (uint64, bool, error)

DurableThrough returns the highest LSN durably persisted, or (0, false) if nothing is durable yet (imbh: Db::durable_through).

func (*DB) Export 

func (db *DB) Export(table Table, startNs, endNs int64) ([]byte, error)

Export returns the given table's rows over [startNs, endNs) as an Arrow-IPC stream (a self-describing schema + record batches), buffer unioned with segments ordered by time. Pass startNs == endNs == 0 for the whole range. Use ExportRecords to decode. (imbh: Db::export.)

func (*DB) ExportRecords 

func (db *DB) ExportRecords(table Table, startNs, endNs int64) ([]arrow.RecordBatch, error)

ExportRecords is Export decoded into Arrow record batches. Each returned batch is Retained and owned by the caller — Release() it when done.

func (*DB) Flush 

func (db *DB) Flush() error

Flush seals the in-memory buffer into an immutable segment. Not required for queryability (queries see the buffer union segments); use it to bound memory or to exercise the on-disk read path.

func (*DB) GetTrace 

func (db *DB) GetTrace(ctx context.Context, traceID string) (*Rows, error)

GetTrace fetches one trace's spans as zero-copy Arrow rows. traceID is the 32-char hex id — the same form QueryTraceQLMatches returns, so a TraceQL match can be passed straight in.

func (*DB) GetTraceForest 

func (db *DB) GetTraceForest(ctx context.Context, traceID string) ([]*TraceNode, error)

GetTraceForest fetches a trace's spans (via GetTraceSpans) and returns them assembled into a parent→child forest. It is named GetTraceForest rather than GetTrace because DB.GetTrace already exists in lgtm.go and returns zero-copy Arrow *Rows.

func (*DB) GetTraceSpans 

func (db *DB) GetTraceSpans(ctx context.Context, traceID string) ([]Span, error)

GetTraceSpans fetches a trace and decodes its spans into []Span (ordered by start time).

func (*DB) IngestOTLPLogs 

func (db *DB) IngestOTLPLogs(otlp []byte) (Receipt, error)

IngestOTLPLogs ingests OTLP/HTTP logs export-request protobuf bytes (what a stock OTel exporter sends). Data is queryable immediately, before any Flush.

func (*DB) IngestOTLPMetrics 

func (db *DB) IngestOTLPMetrics(otlp []byte) (Receipt, error)

IngestOTLPMetrics ingests an OTLP metrics export-request.

func (*DB) IngestOTLPTraces 

func (db *DB) IngestOTLPTraces(otlp []byte) (Receipt, error)

IngestOTLPTraces ingests an OTLP traces export-request.

func (*DB) LogVolume 

func (db *DB) LogVolume(ctx context.Context, q LogQuery, stepNs int64) ([]VolumeBucket, error)

LogVolume returns log record counts per stepNs-sized time bucket over the filter q. The bucket start is floor(time/stepNs)*stepNs in unix nanos; buckets carry no labels (Labels == "{}").

func (*DB) LogVolumeBy 

func (db *DB) LogVolumeBy(ctx context.Context, q LogQuery, stepNs int64, groupBy []string) ([]VolumeBucket, error)

LogVolumeBy is LogVolume broken down by the given attribute keys — counts per (step-bucket, label set), each bucket carrying its Labels as canonical JSON. Empty groupBy is equivalent to LogVolume.

A key may name a record attribute or the service: "service.name" (the OTel resource key) and "service" (the column it is lifted into at ingest) both split per service. Requires imbh 0.3.0 — before that, either spelling silently collapsed the breakdown into one empty-labelled bucket set.

func (*DB) Maintain 

func (db *DB) Maintain() (MaintenanceReport, error)

Maintain runs a maintenance pass (seal + retention enforcement). Writer-only; a read-only handle returns an error.

func (*DB) MetricCatalog 

func (db *DB) MetricCatalog(ctx context.Context) ([]MetricInfo, error)

MetricCatalog returns the metric catalog — one MetricInfo per stored metric.

func (*DB) MetricExemplars 

func (db *DB) MetricExemplars(ctx context.Context, metric string) ([]Exemplar, error)

MetricExemplars returns every exemplar recorded for a metric. Exemplars are carried by histogram/ exponential-histogram (and gauge/sum) points; a metric with none yields an empty slice.

func (*DB) MetricSeries 

func (db *DB) MetricSeries(ctx context.Context, metric string) ([]string, error)

MetricSeries returns the distinct label sets (series) carrying a metric, each rendered as its canonical JSON object string. Resource-level dimensions like service are separate axes and are not folded in.

func (*DB) Query 

func (db *DB) Query(ctx context.Context, sql string) (*Rows, error)

Query runs a SQL statement and returns a lazily-streamed, zero-copy result set. The query executes batch-by-batch on IMBH's engine (fused onto Go's scheduler via sable); each Rows.Next pulls one Arrow RecordBatch without copying its buffers. Cancelling ctx aborts a parked Next (interrupting a slow batch) and cancels the query on the IMBH side (releasing its pinned snapshot); after cancellation, Next returns ok=false with ctx.Err().

func (*DB) QueryLogPage 

func (db *DB) QueryLogPage(ctx context.Context, q LogQuery, after Cursor) (*LogPage, error)

QueryLogPage runs a single page of a log query. Pass a nil Cursor for the first page; pass the returned LogPage.Next (while HasMore) for each subsequent page, keeping the same LogQuery. Rows are materialized into []LogEntry (like QueryLogsTyped); the page's cursor and QueryStats come back alongside. (imbh: logs().query → LogPage, LogQuery::after.)

func (*DB) QueryLogQL 

func (db *DB) QueryLogQL(ctx context.Context, query string, start, end, step int64) (*Rows, error)

QueryLogQL evaluates a LogQL query over [start, end] at step, returning zero-copy Arrow rows. LogQL has two result shapes (as in Loki): a range aggregation (e.g. count_over_time, rate) yields labeled series (labels|timestamp|value), while a bare selector yields log lines (the logs projection). See QueryLogQLSeries and QueryLogQLLines for the decoded forms.

func (*DB) QueryLogQLLines 

func (db *DB) QueryLogQLLines(ctx context.Context, query string, start, end int64, limit int) ([]LogEntry, error)

QueryLogQLLines evaluates a bare LogQL selector (e.g. `{service="checkout"} |= "error"`) and decodes the matching log lines. This is LogQL's `streams` result shape, as opposed to the `matrix` shape a range aggregation produces (see QueryLogQLSeries). limit caps the lines returned (0 = engine default).

func (*DB) QueryLogQLSeries 

func (db *DB) QueryLogQLSeries(ctx context.Context, query string, start, end, step int64) ([]Series, error)

QueryLogQLSeries evaluates a LogQL range aggregation and decodes it into labeled series.

func (*DB) QueryLogs 

func (db *DB) QueryLogs(ctx context.Context, q LogQuery) (*Rows, error)

QueryLogs runs a typed log query, returning a zero-copy streamed result set (see Rows).

func (*DB) QueryLogsTyped 

func (db *DB) QueryLogsTyped(ctx context.Context, q LogQuery) ([]LogEntry, error)

QueryLogsTyped runs a typed log query and decodes the result rows into []LogEntry. Convenience over QueryLogs for callers that want Go structs rather than raw Arrow batches. Prefer QueryLogs (+ manual Arrow) for very large results, since this materializes all rows.

func (*DB) QueryMetricInstant 

func (db *DB) QueryMetricInstant(ctx context.Context, q MetricQuery) ([]InstantSample, error)

QueryMetricInstant runs an instant metric query (imbh's `metrics().instant`) over the same MetricQuery as QueryMetrics, returning one InstantSample per series (the last point in range).

func (*DB) QueryMetricPoints 

func (db *DB) QueryMetricPoints(ctx context.Context, q MetricPointsQuery) (*Rows, error)

QueryMetricPoints returns raw metric samples as zero-copy Arrow rows. Columns: point_time, metric, service, attributes, temporality, is_monotonic, then value (scalar kinds) or explicit_bounds + bucket_counts (histogram).

func (*DB) QueryMetricPointsTyped 

func (db *DB) QueryMetricPointsTyped(ctx context.Context, q MetricPointsQuery) ([]MetricPoint, error)

QueryMetricPointsTyped decodes raw scalar (gauge/sum) samples into []MetricPoint. For histogram metrics use QueryMetricPoints and read the bucket columns directly.

func (*DB) QueryMetrics 

func (db *DB) QueryMetrics(ctx context.Context, q MetricQuery) (*Rows, error)

QueryMetrics runs a typed metric range query, returning a zero-copy streamed result set.

func (*DB) QueryMetricsTyped 

func (db *DB) QueryMetricsTyped(ctx context.Context, q MetricQuery) (Matrix, error)

QueryMetricsTyped runs a metric range query and decodes it into a Matrix (rows grouped into series by the GroupBy label set). Convenience over QueryMetrics.

func (*DB) QueryPromQL 

func (db *DB) QueryPromQL(ctx context.Context, query string, start, end, step int64) (*Rows, error)

QueryPromQL evaluates a PromQL query over [start, end] at the given step (all unix nanoseconds), returning the result as zero-copy Arrow rows (columns labels | timestamp | value).

func (*DB) QueryPromQLSeries 

func (db *DB) QueryPromQLSeries(ctx context.Context, query string, start, end, step int64) ([]Series, error)

QueryPromQLSeries evaluates a PromQL query and decodes the result into labeled series.

func (*DB) QuerySpanMetrics 

func (db *DB) QuerySpanMetrics(ctx context.Context, q SpanMetricsQuery) (*Rows, error)

QuerySpanMetrics runs a span (RED) metrics query, returning a zero-copy streamed result set with columns bucket, [group labels], calls, errors, p50, p95, p99.

func (*DB) QuerySpanMetricsTyped 

func (db *DB) QuerySpanMetricsTyped(ctx context.Context, q SpanMetricsQuery) ([]SpanMetricPoint, error)

QuerySpanMetricsTyped runs a span (RED) metrics query and decodes the rows into []SpanMetricPoint.

func (*DB) QueryTraceQL 

func (db *DB) QueryTraceQL(ctx context.Context, query string, start, end int64) (*Rows, error)

QueryTraceQL evaluates a TraceQL query over the trace-start window [start, end] (unix nanoseconds), returning matches as zero-copy Arrow rows (columns trace_id | span_id).

func (*DB) QueryTraceQLMatches 

func (db *DB) QueryTraceQLMatches(ctx context.Context, query string, start, end int64) ([]TraceMatch, error)

QueryTraceQLMatches evaluates a TraceQL query and decodes the matches into []TraceMatch.

func (*DB) SearchTraces 

func (db *DB) SearchTraces(ctx context.Context, q TraceQuery) ([]TraceSummary, error)

SearchTraces returns the trace summaries matching q, most-recent-first per imbh's ordering.

func (*DB) SegmentFiles 

func (db *DB) SegmentFiles(table Table) ([]string, error)

SegmentFiles lists the on-disk file paths backing the given table (imbh: Db::segment_files).

func (*DB) Segments 

func (db *DB) Segments() ([]SegmentRef, error)

Segments lists the database's current on-disk segments.

func (*DB) Snapshot 

func (db *DB) Snapshot(dir string) (SnapshotInfo, error)

Snapshot writes a consistent copy of the database's segments into dir (created if absent). Writer-only.

func (*DB) Stats 

func (db *DB) Stats() (DbStats, error)

Stats returns a snapshot of storage and ingest counters. Works on readers and writers.

func (*DB) TryIngestOTLPLogs 

func (db *DB) TryIngestOTLPLogs(otlp []byte) (Receipt, error)

TryIngestOTLPLogs is IngestOTLPLogs with backpressure: at the in-flight cap it returns ErrBackpressure immediately without ingesting (nothing admitted), so a producer can shed load or retry with backoff instead of piling on unbounded work.

func (*DB) TryIngestOTLPMetrics 

func (db *DB) TryIngestOTLPMetrics(otlp []byte) (Receipt, error)

TryIngestOTLPMetrics is IngestOTLPMetrics with backpressure.

func (*DB) TryIngestOTLPTraces 

func (db *DB) TryIngestOTLPTraces(otlp []byte) (Receipt, error)

TryIngestOTLPTraces is IngestOTLPTraces with backpressure.

type DbOptions 

type DbOptions struct {
	// Path is the on-disk directory (required).
	Path string `json:"path"`
	// ReadOnly opens as a reader (no writer lock; many may coexist with one writer).
	ReadOnly bool `json:"read_only,omitempty"`
	// AllowStaleReads lets a read-only open accept seal-interval freshness when the writer's WAL is
	// off (otherwise such an open is rejected).
	AllowStaleReads bool `json:"allow_stale_reads,omitempty"`
	// MemoryBudgetBytes caps the in-memory buffer (0 = imbh default, 128 MiB).
	MemoryBudgetBytes uint64 `json:"memory_budget_bytes,omitempty"`
	// Compression selects the segment codec: "none", "lz4", or "zstd" (with ZstdLevel). "" = default.
	Compression string `json:"compression,omitempty"`
	// ZstdLevel is the zstd level used when Compression == "zstd".
	ZstdLevel int32 `json:"zstd_level,omitempty"`
	// WalMode selects the write-ahead-log mode: "off", "always", or "interval" (with WalIntervalNs).
	WalMode string `json:"wal_mode,omitempty"`
	// WalIntervalNs is the flush interval when WalMode == "interval".
	WalIntervalNs int64 `json:"wal_interval_ns,omitempty"`
	// RetentionDays drops data older than N days (0 = keep, unless MaxDiskBytes bounds it).
	RetentionDays uint64 `json:"retention_days,omitempty"`
	// MaxDiskBytes bounds on-disk segment bytes (0 = unbounded).
	MaxDiskBytes uint64 `json:"max_disk_bytes,omitempty"`
	// Refresh controls read-only snapshot refresh: "onquery", "manual", or "ttl" (with RefreshTtlNs).
	Refresh string `json:"refresh,omitempty"`
	// RefreshTtlNs is the refresh TTL when Refresh == "ttl".
	RefreshTtlNs int64 `json:"refresh_ttl_ns,omitempty"`
	// MaintenanceBackgroundNs runs background maintenance on an owned OS thread every N ns (0 = manual).
	// This picks *who* runs the scheduler; Flush picks *when* it seals. imbh's default is manual, so
	// with this at 0 nothing seals (and no WAL fsync timer runs) unless you call Flush/Maintain yourself.
	MaintenanceBackgroundNs int64 `json:"maintenance_background_ns,omitempty"`
	// Flush is imbh's flush-policy spec: comma-separated key=value pairs, or the single word "manual"
	// ("off"/"none"/"never" alias it). Keys are interval/every (duration), buffer/bytes (size, or
	// "budget"/"off"), rows (count), wal (size), idle (duration), and tick (duration); the triggers OR
	// together. E.g. "interval=5s,wal=64MiB". Unlike the other string tags, a malformed spec fails the
	// open rather than falling back to a default. "" leaves imbh's own default, which seals on the
	// MaintenanceBackgroundNs tick and at the memory-budget-derived byte threshold. (imbh 0.2.0:
	// DbBuilder::flush.)
	Flush string `json:"flush,omitempty"`
	// Duplicates picks what happens when two metric datapoints share a series *and* a timestamp — a
	// pair PromQL has no meaning for, since series identity is service + __name__ + the string
	// attributes. "" (or "error_on_read") keeps imbh's historical behavior: ingest takes both and any
	// PromQL query touching that series fails, naming the metric, labels and instant. "last_wins"
	// collapses the duplicated instant at read time, degrading one point instead of the whole metric —
	// the only remedy for points already written. "reject" drops the repeat at ingest and counts it in
	// Receipt.Rejected and DbStats.IngestRejected; it costs a fixed ~13 MiB guard and takes an optional
	// lookback, "reject,recent=N" (default 262144 points). The guard is process-local, best-effort, and
	// never rejects out-of-order or late points — only an exact (series, timestamp) repeat. Like Flush,
	// a malformed spec fails the open rather than falling back. (imbh 0.5.0: DbBuilder::duplicates.)
	Duplicates string `json:"duplicates,omitempty"`
	// PromoteKeys promotes the given attribute keys to dedicated columns. Reserved names (including
	// "service") are dropped by imbh, and "service.name" needs no promotion: since imbh 0.3.0 both
	// spellings resolve to the built-in service column in every group-by and attribute predicate.
	PromoteKeys []string `json:"promote_keys,omitempty"`
}

DbOptions configures a durable open, mirroring imbh's DbBuilder. The zero value opens with imbh's defaults (equivalent to Open). Only set fields take effect; unrecognized string tags are ignored (leaving the default). The host-runtime option variants (async ingest, runtime-driven maintenance), which need an explicit tokio runtime handle, are intentionally not exposed here.

type DbStats 

type DbStats struct {
	Tables           []TableStats `json:"tables"`
	BufferBytes      uint64       `json:"buffer_bytes"`
	WalBytes         uint64       `json:"wal_bytes"`
	DurableLSN       *uint64      `json:"durable_lsn"`
	IngestQueueDepth uint64       `json:"ingest_queue_depth"`
	IngestDropped    uint64       `json:"ingest_dropped"`
	IngestErrors     uint64       `json:"ingest_errors"`
	// IngestRejected counts metric points dropped at ingest because their (series, timestamp) was
	// already accepted. Non-zero only under DbOptions.Duplicates == "reject"; every other policy
	// takes duplicates and resolves them (or fails) at read time. (imbh 0.5.0.)
	IngestRejected uint64 `json:"ingest_rejected"`
}

DbStats is a snapshot of the database's storage and ingest counters (imbh: Db::stats).

type Exemplar 

type Exemplar struct {
	Time       int64
	Value      float64
	TraceID    string
	SpanID     string
	Attributes string
}

Exemplar is one OTLP exemplar surfaced from a metric point — the trace link for metric→trace drill-down. TraceID/SpanID are "" when the exemplar carries none. Attributes is the exemplar's filtered attributes as canonical JSON ("" when none).

type InstantSample 

type InstantSample struct {
	Labels string
	Time   int64
	Value  float64
}

InstantSample is one series' instant value: the last sample of that series over the query range (Vector semantics — exactly one sample per series). Labels is the canonical JSON label-set string; Time is unix nanoseconds.

type LogEntry 

type LogEntry struct {
	Time         int64  // event time, unix nanoseconds
	Service      string // service.name (may be "")
	Severity     uint8  // OTLP severity number
	SeverityText string
	Body         string
	Attributes   string // attributes as a JSON object string
	TraceID      []byte // 16 bytes, or nil
	SpanID       []byte // 8 bytes, or nil
}

LogEntry is a decoded log record (a curated subset of IMBH's logs columns).

type LogPage 

type LogPage struct {
	Entries []LogEntry
	Next    Cursor
	Stats   QueryStats
}

LogPage is one page of a paged log query: the decoded rows, a resume cursor (empty when the page was short, i.e. no more rows), and the scan statistics.

type LogQuery 

type LogQuery struct {
	Service  string            `json:"service,omitempty"`  // exact service.name match
	Match    string            `json:"match,omitempty"`    // full-text match on the log body
	AttrEq   map[string]string `json:"attr_eq,omitempty"`  // attribute equality filters (AND)
	Start    int64             `json:"start,omitempty"`    // time range start (unix nanos, inclusive)
	End      int64             `json:"end,omitempty"`      // time range end (unix nanos)
	Limit    int               `json:"limit,omitempty"`    // max rows (0 = engine default)
	Backward bool              `json:"backward,omitempty"` // newest-first (default is oldest-first)

	// Trace correlation: filter logs down to a single trace or span.
	TraceID string `json:"trace_id,omitempty"` // hex trace id (32 hex chars); correlate logs to a trace
	SpanID  string `json:"span_id,omitempty"`  // hex span id (16 hex chars); correlate to a single span

	// Severity + attribute predicates (all AND-combined with the above).
	SeverityAtLeast int                 `json:"severity_at_least,omitempty"` // minimum OTEL severity number (1-24); 0 = unset
	AttrExists      []string            `json:"attr_exists,omitempty"`       // keys that must be present
	AttrMatches     map[string]string   `json:"attr_matches,omitempty"`      // key → full-text term match on that attribute
	AttrIn          map[string][]string `json:"attr_in,omitempty"`           // key → allowed value set
	AttrNotIn       map[string][]string `json:"attr_not_in,omitempty"`       // key → excluded value set
	AttrGt          map[string]float64  `json:"attr_gt,omitempty"`           // key → value must be > n
	AttrGe          map[string]float64  `json:"attr_ge,omitempty"`           // key → value must be >= n
	AttrLt          map[string]float64  `json:"attr_lt,omitempty"`           // key → value must be < n
	AttrLe          map[string]float64  `json:"attr_le,omitempty"`           // key → value must be <= n
	AttrRegex       map[string]string   `json:"attr_regex,omitempty"`        // key → RE2 pattern the value must match
}

LogQuery is an endpoint-shaped log query (mirrors IMBH's LogQuery builder; a curated subset). The zero value matches all logs. Times are Unix nanoseconds; 0 means unset.

type MaintenanceReport 

type MaintenanceReport struct {
	Sealed          bool   `json:"sealed"`
	SegmentsDropped uint64 `json:"segments_dropped"`
	BytesFreed      uint64 `json:"bytes_freed"`
}

MaintenanceReport summarizes a maintain() pass (imbh: Db::maintain).

type Matrix 

type Matrix struct {
	Series []Series
}

Matrix is the result of a metric range query — one series per distinct group-by label set.

type MetricInfo 

type MetricInfo struct {
	Metric      string
	Unit        string
	Temporality string
	Kind        string
}

MetricInfo is one metric's catalog entry: its name, unit, temporality ("" when the kind carries none, e.g. summaries), and kind ("gauge" | "sum" | "histogram" | ...).

type MetricPoint 

type MetricPoint struct {
	Time       int64 // unix nanoseconds
	Metric     string
	Service    string
	Attributes string // JSON object string
	Value      float64
}

MetricPoint is one decoded raw metric sample (scalar kinds: gauge / sum).

type MetricPointsQuery 

type MetricPointsQuery struct {
	Metric  string            `json:"metric"`
	Kind    string            `json:"kind,omitempty"`
	Filters map[string]string `json:"filters,omitempty"` // attribute equality filters (AND)
	Start   int64             `json:"start,omitempty"`
	End     int64             `json:"end,omitempty"`
	Limit   int               `json:"limit,omitempty"`
}

MetricPointsQuery selects raw (unaggregated) metric samples — the counterpart to MetricQuery, which resamples into a range. Kind is "gauge" (default), "sum", or "histogram". Times are Unix nanoseconds.

type MetricQuery 

type MetricQuery struct {
	Metric  string   `json:"metric"`             // metric name
	Sum     bool     `json:"sum,omitempty"`      // false = gauge (default), true = sum
	Step    int64    `json:"step,omitempty"`     // resample step (nanos)
	Start   int64    `json:"start,omitempty"`    // range start (unix nanos)
	End     int64    `json:"end,omitempty"`      // range end (unix nanos)
	GroupBy []string `json:"group_by,omitempty"` // attribute keys to split series on
}

MetricQuery is a metric range query over a scalar metric (gauge or sum). Times are Unix nanoseconds; Step is the resampling interval in nanoseconds. GroupBy names attribute keys to split series on — a record attribute, or the service under either spelling ("service.name" / "service"), which imbh 0.3.0 resolves to the built-in service column (earlier versions merged every service into one empty-labelled series). The same holds for LogQuery's attribute predicates and SpanMetricsQuery.

type Point 

type Point struct {
	T int64
	V float64
}

Point is one (time, value) sample. T is unix nanoseconds.

type QueryStats 

type QueryStats struct {
	SegmentsScanned uint64 `json:"segments_scanned"`
	SegmentsPruned  uint64 `json:"segments_pruned"`
	RowsScanned     uint64 `json:"rows_scanned"`
	RowsReturned    uint64 `json:"rows_returned"`
	BytesScanned    uint64 `json:"bytes_scanned"`
	ElapsedNs       uint64 `json:"elapsed_ns"`
	UsedIndex       bool   `json:"used_index"`
}

QueryStats reports what a query scanned. Complete only for a fully drained query (which QueryLogPage always does). Mirrors imbh's QueryStats.

type Receipt 

type Receipt struct {
	Accepted uint64
	Rejected uint64
	LSN      uint64
	Durable  bool
	Queued   bool
}

Receipt is the outcome of an ingest call. When Queued is true (async ingest), LSN/Durable carry no information yet.

type Rows 

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

Rows is a streaming, zero-copy query result. Iterate with Next until it returns ok=false, then check Err (or Close). Not safe for concurrent use: iterate from one goroutine. Each returned RecordBatch is owned by the caller — call its Release() when done.

ZERO-COPY CAVEAT: a batch's Arrow buffers are IMBH-owned and freed by Release(). Scalar values read from a batch — especially strings/[]byte via arrow-go, which alias the buffer without copying — are only valid until that batch's Release(). Copy anything you need to outlive the batch (e.g. strings.Clone for strings; QueryLogsTyped does this for you).

func (*Rows) Close 

func (r *Rows) Close()

Close releases the cursor (and cancels the query if not fully drained). Idempotent.

Abandoning a stream before end-of-stream means finish never runs, and finish is what clears this query's Rust-side error slot — so Close does it instead. Without that, a query that had already recorded a terminal error (a plan error, say, which is stored the moment the handler starts) holds that entry until the process exits: a slow leak for any long-lived program that abandons streams. See TestAbandonedStreamClearsErrorSlot.

One window remains open by design: if the handler records an error *after* this fetch — it is still running, and only a send failure makes it stop without storing — that entry is never claimed. The Rust-side fix would be to skip storing once the consumer is gone (`tx.is_closed()`), at every store site; the pending-error count in TestNoLeak is the tripwire if it ever matters in practice.

func (*Rows) Err 

func (r *Rows) Err() error

Err returns the terminal error after Next has returned ok=false: nil (clean end), a query error, or context.Canceled/DeadlineExceeded. Meaningless before iteration ends.

func (*Rows) Next 

func (r *Rows) Next() (rec arrow.RecordBatch, ok bool, err error)

Next pulls the next result batch. ok=false marks the end of iteration; then Err reports whether it ended cleanly (nil), on a query error, or on context cancellation. On ok=true the RecordBatch wraps IMBH-allocated Arrow buffers zero-copy; the caller must Release() it.

type SegmentRef 

type SegmentRef struct {
	RelativePath    string `json:"relative_path"`
	MinTimeUnixNano int64  `json:"min_time_unix_nano"`
	MaxTimeUnixNano int64  `json:"max_time_unix_nano"`
	Rows            uint64 `json:"rows"`
}

SegmentRef identifies one on-disk segment and its covered time range (imbh: Db::segments).

type Series 

type Series struct {
	Labels map[string]string
	Points []Point
}

Series is one metric time series: its label set and its samples over time.

type SnapshotInfo 

type SnapshotInfo struct {
	Dir      string `json:"dir"`
	Segments uint64 `json:"segments"`
}

SnapshotInfo describes a snapshot written by Snapshot (imbh: Db::snapshot).

type Span 

type Span struct {
	TraceID       []byte
	SpanID        []byte
	ParentSpanID  []byte
	Name          string
	Kind          string
	StartTime     int64 // unix nanoseconds
	DurationNs    int64
	StatusCode    string
	StatusMessage string
	Service       string
	Attributes    string // JSON object string
}

Span is one decoded span of a trace.

type SpanMetricPoint 

type SpanMetricPoint struct {
	Bucket int64 // bucket start, unix nanoseconds
	Labels map[string]string
	Calls  uint64
	Errors uint64
	P50    float64 // latency percentiles, nanoseconds
	P95    float64
	P99    float64
}

SpanMetricPoint is one bucket of RED span metrics for a label set.

type SpanMetricsQuery 

type SpanMetricsQuery struct {
	Service string   `json:"service,omitempty"`
	Name    string   `json:"name,omitempty"`     // span name
	Kind    string   `json:"kind,omitempty"`     // span kind
	Status  string   `json:"status,omitempty"`   // status code filter
	GroupBy []string `json:"group_by,omitempty"` // attribute keys to split on
	Step    int64    `json:"step,omitempty"`     // bucket width (nanos)
	Start   int64    `json:"start,omitempty"`
	End     int64    `json:"end,omitempty"`
}

SpanMetricsQuery is a span (RED) metrics query: calls / errors / latency percentiles over spans, bucketed by Step (nanos) and optionally split by GroupBy attribute keys.

type Stats 

type Stats = sable.Stats

Stats is a snapshot of the fused runtime's counters.

func RuntimeStats 

func RuntimeStats() Stats

RuntimeStats returns a snapshot of runtime counters (InFlight, Rejected, MaxInFlight, …) for backpressure tuning and observability.

type Table 

type Table string

Table names one of imbh's storage tables (logs, spans, and the five metric families). The string values match imbh's Table::as_str form used on the wire. 

const (
	TableLogs                Table = "logs"
	TableSpans               Table = "spans"
	TableMetricsGauge        Table = "metrics_gauge"
	TableMetricsSum          Table = "metrics_sum"
	TableMetricsHistogram    Table = "metrics_histogram"
	TableMetricsExpHistogram Table = "metrics_exp_histogram"
	TableMetricsSummary      Table = "metrics_summary"
)

type TableStats 

type TableStats struct {
	Table           string `json:"table"`
	SegmentCount    uint64 `json:"segment_count"`
	SegmentRows     uint64 `json:"segment_rows"`
	BufferRows      uint64 `json:"buffer_rows"`
	MinTimeUnixNano *int64 `json:"min_time_unix_nano"`
	MaxTimeUnixNano *int64 `json:"max_time_unix_nano"`
}

TableStats is per-table storage accounting within DbStats.

type TraceMatch 

type TraceMatch struct {
	TraceID string
	SpanIDs []string
}

TraceMatch is a TraceQL match: a trace and the span ids its spanset selected.

type TraceNode 

type TraceNode struct {
	Span
	Children []*TraceNode
}

TraceNode is one span in an assembled trace tree. It embeds the decoded Span and holds the spans whose ParentSpanID names this span's SpanID.

func AssembleTrace 

func AssembleTrace(spans []Span) []*TraceNode

AssembleTrace rebuilds the parent→child forest from a flat span slice and returns the roots.

A span becomes a root when its ParentSpanID is empty OR when its parent's SpanID is not present in the input (an orphan is surfaced as a root so no span is ever dropped). Every other span is attached under the node whose SpanID equals its ParentSpanID. Spans are keyed by string(SpanID); on a duplicate SpanID the first occurrence wins and later ones are discarded.

The input slice is not mutated: nodes are built from copies of the Span values. Children of each node, and the returned roots, are sorted by StartTime then by string(SpanID) so the output is stable regardless of input order. An empty or nil input returns nil.

type TraceQuery 

type TraceQuery struct {
	Service       string            `json:"service,omitempty"`
	Name          string            `json:"name,omitempty"`
	Status        string            `json:"status,omitempty"`
	Kind          string            `json:"kind,omitempty"`
	MinDurationNs int64             `json:"min_duration_ns,omitempty"`
	MaxDurationNs int64             `json:"max_duration_ns,omitempty"`
	AttrEq        map[string]string `json:"attr_eq,omitempty"`

	// Attribute predicates (parity with LogQuery; all AND-combined with the above).
	AttrExists  []string            `json:"attr_exists,omitempty"`  // keys that must be present
	AttrMatches map[string]string   `json:"attr_matches,omitempty"` // key → full-text term match on that attribute
	AttrIn      map[string][]string `json:"attr_in,omitempty"`      // key → allowed value set
	AttrNotIn   map[string][]string `json:"attr_not_in,omitempty"`  // key → excluded value set
	AttrGt      map[string]float64  `json:"attr_gt,omitempty"`      // key → value must be > n
	AttrGe      map[string]float64  `json:"attr_ge,omitempty"`      // key → value must be >= n
	AttrLt      map[string]float64  `json:"attr_lt,omitempty"`      // key → value must be < n
	AttrLe      map[string]float64  `json:"attr_le,omitempty"`      // key → value must be <= n
	AttrRegex   map[string]string   `json:"attr_regex,omitempty"`   // key → RE2 pattern the value must match

	Start int64 `json:"start,omitempty"`
	End   int64 `json:"end,omitempty"`
	Limit int64 `json:"limit,omitempty"`
}

TraceQuery selects traces for SearchTraces. All fields are optional: a field is applied only when non-empty/non-zero, so a zero TraceQuery matches everything (up to the server's default limit). The JSON tags match the Rust `TraceQueryWire`.

type TraceSummary 

type TraceSummary struct {
	TraceID     string
	RootService string
	RootName    string
	StartTime   int64
	DurationNs  int64
	SpanCount   int64
	Error       bool
}

TraceSummary is one matched trace's summary row. RootService/RootName are "" when the root span carries none (SQL-NULL upstream). StartTime is unix nanoseconds; DurationNs is the trace's wall duration in nanoseconds.

type VolumeBucket 

type VolumeBucket struct {
	Time   int64
	Labels string
	Count  int64
}

VolumeBucket is one time bucket of a log-volume query: the bucket start (unix nanos), the label set identifying this bucket's series as canonical JSON ("{}" when un-grouped), and the record count.

Source Files

View all Source files

Directories

Path Synopsis
cmd
imbhgo-fetch command
Command imbhgo-fetch downloads the prebuilt combined static library (libimbhgo.a) for the current platform so a consumer can build github.com/moriyoshi/imbh-go WITHOUT building the Rust side.
 Command imbhgo-fetch downloads the prebuilt combined static library (libimbhgo.a) for the current platform so a consumer can build github.com/moriyoshi/imbh-go WITHOUT building the Rust side.
internal
release
Package release holds the release coordinates for the prebuilt libimbhgo.a archives: the version this source corresponds to and the naming/URL scheme for the assets published on GitHub Releases.
 Package release holds the release coordinates for the prebuilt libimbhgo.a archives: the version this source corresponds to and the naming/URL scheme for the assets published on GitHub Releases.

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.