Tracing

OpenTelemetry spans for searches, documents and evaluations. See Trace searches and ingestion.

vectrixdb.tracing

Spans for searches, ingestion and evaluation runs, off until you turn them on.

pip install "vectrixdb[tracing]"
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # or VECTRIXDB_TRACING=1

or, in code, after setting up OpenTelemetry the way the rest of the app does::

import vectrixdb.tracing
vectrixdb.tracing.enable()

Every Vectrix.search, add_document, rechunk, write_golden and evaluate then becomes a span named vectrixdb.<operation>, with the collection, the mode, the counts, the top relevance and how long it took, in whatever tracing tool the app already sends to: Jaeger, Grafana Tempo, Honeycomb, Datadog, Azure Monitor, any OTLP collector.

What a span never carries. No query text, no document text, no file names, no metadata values and no keys. A span says that a search ran, how it ran and how well it scored, the way the audit records carry a query's fingerprint and never its words. An exception is recorded by its type.

What it costs when it is off. One boolean check per call. OpenTelemetry is not imported, and no span is made, until tracing is on. It turns on when enable() is called, or at import when VECTRIXDB_TRACING is 1 or OTEL_EXPORTER_OTLP_ENDPOINT is set. VECTRIXDB_TRACING=0 keeps it off even with an endpoint set. Spans go to the app's OpenTelemetry provider, whenever the app sets it up. Where nothing sets one up, an OTLP exporter is set up from the standard OTEL_* variables: at import with VECTRIXDB_TRACING=1, and by vectrixdb serve and vectrixdb mcp, whose process is VectrixDB's own. An app that has its own provider keeps it.

SAFE_ATTRIBUTES = frozenset({'vectrixdb.collection', 'vectrixdb.mode', 'vectrixdb.limit', 'vectrixdb.rerank', 'vectrixdb.filtered', 'vectrixdb.results', 'vectrixdb.top_relevance', 'vectrixdb.top_relevance_kind', 'vectrixdb.degraded', 'vectrixdb.truncated', 'vectrixdb.chunks', 'vectrixdb.chunking', 'vectrixdb.documents', 'vectrixdb.kind', 'vectrixdb.questions', 'vectrixdb.collections', 'vectrixdb.setups', 'vectrixdb.preview', 'vectrixdb.duration_ms', 'vectrixdb.tool', 'vectrixdb.refused'}) module-attribute

CallerTrace

ASGI middleware: a request's spans join the trace its traceparent header names.

What a request span would do for the spans under it, without the span, which would carry the request's path and query. Off, it is one boolean check per request. A span already current, from an app that serves this one inside its own, stays the parent.

enable(tracer_provider=None)

Turn spans on. Returns False, and stays off, when OpenTelemetry is not installed.

tracer_provider is the provider to use; left out, OpenTelemetry's global one, which is whatever the app set up.

disable()

Turn spans off. Calls cost one boolean check again.

enabled()

describe()

Whether spans are on, and the host they go to when VectrixDB set up the exporter.

What the dashboard's settings show. to is the endpoint's host alone, never its path, query or credentials, and None when the app set up OpenTelemetry itself and VectrixDB does not know where it sends.

export_to_otlp()

Send spans to the OTLP endpoint the standard OTEL_* variables name.

Only when the app has not set up OpenTelemetry itself: an app with its own provider keeps it, and this returns False, as it does when the SDK or the exporter is not installed (the [tracing] extra has both). vectrixdb serve and vectrixdb mcp call it when tracing is on, since there the process is VectrixDB's own.

span(name, **attributes)

A span named vectrixdb.<name> around the block, or nothing when tracing is off.

traced(name, before=None, after=None)

Wrap a function in a span. before(arguments) and after(result) give its attributes.

arguments maps every parameter name to the value the call gave it, or its default, however it was passed. Off, the wrapper is one boolean check and the call. A function that calls itself again inside the same operation makes one span, not two.

inject(headers)

Put the current trace in an outgoing request's headers, when tracing is on.

The traceparent header, and whatever else the app's propagators carry, so the service at the other end, VectrixDB's extraction service among them, puts its spans in the same trace.

fastapi_options()

What each FastAPI app VectrixDB builds is given, so FastAPI traces nothing itself.

FastAPI 0.142 and later trace every request once a tracer provider is set up, with the request's path and query on the span, and send metrics and logs, exception messages among them, wherever OTEL_EXPORTER_OTLP_ENDPOINT points, whatever VECTRIXDB_TRACING says. A path names a document and a query can carry metadata, which no span here carries. :class:CallerTrace keeps a request's spans in its caller's trace.