provrun.destinations

Where a run’s spans go: its evidence, and the destinations the policy approves.

The policy is the operator’s telemetry policy.

A run’s spans are provrun’s own, one for the run and one for each step, and those of a library whose instrumentation the policy approves, such as PydanticAI’s. provrun’s own spans are in the evidence already: each step’s event holds its span’s IDs and data. A library’s span is written to the evidence as a span_recorded event, its bodies kept as a payload.

The user’s variables say where spans may go. Each run reads them as it starts:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT, with its protocol and headers, names an OpenTelemetry collector. provrun sends nothing there if OTEL_SDK_DISABLED is true, or OTEL_TRACES_EXPORTER is none;
LOGFIRE_TOKEN names a Logfire project, at the base URL that LOGFIRE_BASE_URL names, or else at the region in the token. provrun sends nothing there if the user set LOGFIRE_SEND_TO_LOGFIRE to false.

A place gets spans only when the policy has a destination of its kind at that endpoint (TelemetryPolicy.match_destination). It then gets provrun’s spans, and those of each library that the policy lets feed it, each cut down to the level the destination receives. A place with no match gets nothing, and the run writes a telemetry_blocked event with the path destination.

provrun’s exporters connect straight to the place the policy approved. They ignore the proxy variables, such as HTTPS_PROXY and grpc_proxy, so that no variable sends the spans elsewhere. A run records which of these variables were set, by name only, because a proxy URL can hold a password.

MLflow is a destination of another kind. MLFLOW_TRACKING_URI names it, or, when the variable is unset, a sqlite evidence store’s own file. MLflow gets no span as the run goes. Once the run is sealed, provevi’s copy_run copies it from the store, cut to the level the destination receives (Routes.copy). The copy runs in a process of its own, for COPY_SECONDS at most. A copy that fails gives a warning, and never fails the run, whose evidence is closed by then.

class Route

source

Route(kind: str, variable: str, url: str, destination: Any = None, processor: Any = None, sent: Any = None, handed: int = 0, copying: bool = False, note: str = '')

One place a run sends spans to.

It holds the policy’s destination, the variable that named the place, and the processor that sends to it.

Parameter	Type	Default	Description
`kind`	str	required	“otlp”, “logfire” or “mlflow”
`variable`	str	required	The variable that named the place, such as OTEL_EXPORTER_OTLP_ENDPOINT
`url`	str	required	Where the variable points, without what can hold a secret
`destination`	Any	`None`	The policy’s Destination, or None
`processor`	Any	`None`	A BatchSpanProcessor, or None when nothing is sent
`sent`	Any	`None`	The exporter behind it, which counts what it sent and lost
`handed`	int	`0`	The spans handed to the processor
`copying`	bool	`False`	MLflow’s place, which gets a copy of the sealed run
`note`	str	`''`	Why nothing is sent there, or how it is sent, in words

Route.record

source

Route.record() -> dict

Give what run_created records of this place.

Parameter	Type	Default	Description
returns	dict		The kind, variable, URL, destination, level received, whether it is sending, and the note

class Routes

source

Routes(telemetry: Any, routes: list[Route] = <factory>, redirects: list[str] = <factory>, trace_id: int | None = None, refused: set[str] = <factory>, lock: Any = <factory>, mlflow: Route | None = None, environ: Mapping[str, str] = <factory>)

The places one run sends spans to, and the run’s spans as they end.

The places are read from the variables as the run starts.

Parameter	Type	Default	Description
`telemetry`	Any	required	The run’s Telemetry
`routes`	list[Route]	`<factory>`	Each place the variables name, sending or not
`redirects`	list[str]	`<factory>`	The proxy variables that are set, by name, which the exporters ignore
`trace_id`	int \| None	`None`	The run’s trace ID, once start has run
`refused`	set[str]	`<factory>`	Libraries whose spans were refused, each once
`lock`	Any	`<factory>`	Spans end in many threads
`mlflow`	Route \| None	`None`	The MLflow place, copied to after the seal
`environ`	Mapping[str, str]	`<factory>`	The user’s variables, for the copy

Routes.read

source

Routes.read(telemetry: Any, environ: Mapping[str, str], store: Any = None) -> Routes

Read where a run’s spans may go, under its policy.

A place that matches no destination is a telemetry_blocked event.

Parameter	Type	Default	Description
`telemetry`	Any	required	The run’s Telemetry, whose policy approves each place
`environ`	Mapping[str, str]	required	The variables as the user set them
`store`	Any	`None`	The run’s evidence store; None is the file store
returns	Routes		The run’s routes

Routes.copy

source

Routes.copy(run_id: str, store: Any, folder: Any) -> dict | None

Copy the sealed run into the approved MLflow place, if any.

The copy runs in a process of its own, with the user’s variables, for COPY_SECONDS at most. A copy that fails gives a warning and a result with its error; it never raises.

Parameter	Type	Default	Description
`run_id`	str	required	The sealed run’s ID
`store`	Any	required	The run’s evidence store; None is the file store
`folder`	Any	required	The run’s evidence folder
returns	dict \| None		Where it went and whether it was copied, with the error if not; None with no MLflow place

Routes.record

source

Routes.record() -> dict

Give what run_created records: each place, and the redirecting variables set.

Parameter	Type	Default	Description
returns	dict		“destinations”, one record for each place, and “redirects”

Routes.start

source

Routes.start(trace_id: str | None) -> None

Take the spans of the run’s trace from now on.

Parameter	Type	Default	Description
`trace_id`	str \| None	required	The run’s trace ID in hex; None or empty takes nothing

Routes.on_end

source

Routes.on_end(span: Any, own: bool) -> None

Keep an approved library’s span as evidence, and hand the span to each place that may get it.

A span of a library that the policy does not approve goes nowhere, and the first one is written as telemetry_blocked.

Parameter	Type	Default	Description
`span`	Any	required	A span of the run’s trace that has ended
`own`	bool	required	Whether provrun made it; a library’s span goes on only if the policy approves the library

Routes.close

source

Routes.close() -> None

Stop taking the run’s spans, and send what is left to all places at once.

This takes FLUSH_MILLIS at most. A place that did not get every span gives a warning; the run’s evidence is closed by then.