observe

Documentation

Overview

Package observe holds duckgres' OpenTelemetry tracing helpers, the connection-count gauge, and the per-query Prometheus metrics emitted from the trace path. The package has no dependency on github.com/duckdb/duckdb-go, so the control plane and other duckdb-free callers can use it without linking libduckdb.

Index

• Variables
• func DecrementOpenConnections()
• func EnrichSpanWithProfiling(ctx context.Context, span trace.Span, execStart time.Time, ...)
• func IncrementOpenConnections()
• func ParseProfilingOutput(jsonStr string) (profilingRoot, bool)
• func SpanIDFromContext(ctx context.Context) string
• func TraceIDFromContext(ctx context.Context) string
• func Tracer() trace.Tracer
• func TruncateForSpan(q string) string
• type ProfilingRoot

Variables

var S3BytesReadTotal = promauto.NewCounterVec(prometheus.CounterOpts{
	Name: "duckgres_s3_bytes_read_total",
	Help: "Total bytes read from S3 by DuckDB",
}, []string{"org"})

S3BytesReadTotal counts bytes read from S3 by DuckDB, labeled by org. Bumped from EnrichSpanWithProfiling when DuckDB reports total_bytes_read in its profiling output.

var ScanRowsPerSecondHistogram = promauto.NewHistogramVec(prometheus.HistogramOpts{
	Name:    "duckgres_scan_rows_per_second",
	Help:    "Scan throughput: estimated wall-clock rows scanned per second. High values (>1e10) indicate buffer pool/cache hits.",
	Buckets: []float64{1e5, 5e5, 1e6, 5e6, 1e7, 5e7, 1e8, 5e8, 1e9, 1e10, 1e11, 1e12},
}, []string{"org"})

ScanRowsPerSecondHistogram observes scan throughput (estimated wall-clock rows scanned per second). High values (>1e10) indicate buffer pool / cache hits; the bucket range spans S3 cold reads (1e5-1e8) through in-memory cache hits (1e9-1e12).

var ScanWallSecondsHistogram = promauto.NewHistogramVec(prometheus.HistogramOpts{
	Name:    "duckgres_scan_wall_seconds",
	Help:    "Estimated wall-clock scan time per query",
	Buckets: []float64{0.01, 0.05, 0.1, 0.5, 1, 2, 5, 10, 30, 60},
}, []string{"org"})

ScanWallSecondsHistogram observes estimated wall-clock scan time per query.

Functions

func DecrementOpenConnections

func DecrementOpenConnections()

DecrementOpenConnections decrements the open connections gauge.

func EnrichSpanWithProfiling

func EnrichSpanWithProfiling(ctx context.Context, span trace.Span, execStart time.Time, executor sqlcore.QueryExecutor, orgID string)

EnrichSpanWithProfiling creates child spans from DuckDB profiling output showing where execution time was spent: planning, scanning (I/O), and compute. Also emits Prometheus metrics for baseline measurement.

func IncrementOpenConnections

func IncrementOpenConnections()

IncrementOpenConnections increments the open connections gauge.

func ParseProfilingOutput

func ParseProfilingOutput(jsonStr string) (profilingRoot, bool)

ParseProfilingOutput extracts the full profiling tree from DuckDB's JSON output. Exposed for the integration test in package server, which captures real DuckDB profiling JSON and verifies our parser handles it.

func SpanIDFromContext

func SpanIDFromContext(ctx context.Context) string

SpanIDFromContext returns the hex span ID from the span context, or "".

func TraceIDFromContext

func TraceIDFromContext(ctx context.Context) string

TraceIDFromContext returns the hex trace ID from the span context, or "".

func Tracer

func Tracer() trace.Tracer

Tracer returns the package-level tracer.

func TruncateForSpan

func TruncateForSpan(q string) string

TruncateForSpan truncates a query string for use as a span attribute.

Types

type ProfilingRoot

type ProfilingRoot = profilingRoot

ProfilingRoot represents the top-level DuckDB JSON profiling output.