MLflow tracing as a backend for provevi

Trace, TraceInfo and TraceData

A Trace holds a TraceInfo and a TraceData, and TraceData holds the list of spans. The schema version in 3.17.2 is 3 (mlflow.trace_schema.version: "3"). Below is the TraceInfo of a real trace from t.py, made shorter:

{"trace_id": "tr-fee99023d73b75f24da6a4258976baf9",
 "trace_location": {"type": "MLFLOW_EXPERIMENT", "mlflow_experiment": {"experiment_id": "1"}},
 "request_time": "2026-10-31T16:13:01.175Z", "state": "OK", "execution_duration_ms": 33,
 "request_preview": "{\"q\": \"hi\"}", "response_preview": "{\"a\": \"yo\"}",
 "trace_metadata": {"mlflow.sourceRun": "c660a66d...", "mlflow.trace.tokenUsage": "{\"input_tokens\": 3, ...}",
                    "mlflow.traceInputs": "...", "mlflow.traceOutputs": "...", "mlflow.user": "<user>",
                    "mlflow.source.name": "<script>", "mlflow.trace.sizeBytes": "2002"},
 "tags": {"mlflow.traceName": "agent", "mlflow.trace.spansLocation": "TRACKING_STORE"},
 "assessments": [ ... ]}

• Trace ID. The MLflow trace ID is tr- followed by the 32 hex digits of the OTel trace ID.
• Metadata and tags. Metadata is immutable string pairs that MLflow and the user write when the trace starts. Tags are mutable string pairs.
• Trace location. A trace belongs to one experiment through trace_location. In Databricks, the location can also be a Unity Catalog table, set with MLFLOW_TRACE_LOCATION (changelog 3.14.0).

Spans

An MLflow Span wraps an OTel span. Span.to_dict() gives the OTLP JSON shape:

{"trace_id": "/umQI9c7dfJNpqQliXa6+Q==", "span_id": "skRdJJD77cc=", "parent_span_id": "0cnaHvdxwZg=",
 "name": "llm", "start_time_unix_nano": 1793463181208994000, "end_time_unix_nano": 1793463181209235000,
 "events": [], "status": {"code": "STATUS_CODE_OK", "message": ""}, "links": [],
 "attributes": {"mlflow.traceRequestId": "\"tr-fee99023...\"", "mlflow.spanType": "\"CHAT_MODEL\"",
                "mlflow.spanInputs": "{\"messages\": [...]}", "mlflow.spanOutputs": "\"yo\"",
                "mlflow.chat.tokenUsage": "{\"input_tokens\": 3, \"output_tokens\": 1, \"total_tokens\": 4}",
                "mlflow.spanLogLevel": "20"}}

• Attribute values are JSON strings. MLflow encodes each attribute value as JSON, so a string value carries its own quotes.
• Reserved attributes. MLflow reserves mlflow.spanType, mlflow.spanInputs, mlflow.spanOutputs, mlflow.chat.tokenUsage, mlflow.llm.model, mlflow.llm.provider, mlflow.llm.cost and mlflow.spanLogLevel. Log levels came in 3.13.0.
• Span events and links. Spans keep OTel events, for example exceptions. Span links came in 3.13.0 (LiveSpan.add_link()).

The SpanType constants in mlflow/entities/span.py (3.17.2) are LLM, CHAIN, AGENT, TOOL, CHAT_MODEL, RETRIEVER, PARSER, EMBEDDING, RERANKER, MEMORY, UNKNOWN, WORKFLOW, TASK, GUARDRAIL and EVALUATOR. The type is a free string, so a custom type such as EVIDENCE is stored as given.

Assessments

An assessment is a judgement attached to a trace, or to one span of a trace. MLflow has two kinds:

• Feedback. mlflow.log_feedback(trace_id=..., name=..., value=..., rationale=..., source=...) records a judgement, for example a judge score or a thumbs up.
• Expectation. mlflow.log_expectation(...) records a ground truth value.

Each assessment has a source with a type (HUMAN, LLM_JUDGE or CODE) and an ID. It also has run_id, span_id, rationale, metadata, overrides and valid. A new assessment can override an old one, and the old one then has valid=false. See the assessments docs.

Links to runs and experiments

• Experiment. Each trace has exactly one experiment, which is trace_info.experiment_id in SQL.
• Run. A trace made inside mlflow.start_run() gets the metadata key mlflow.sourceRun. MlflowClient.link_traces_to_run links traces to a run after the fact. These links go in the entity_associations table. OTLP ingest takes an optional x-mlflow-run-id header since 3.14.0.
• Session. trace_info.session_id groups the traces of one conversation. The UI has a session view since 3.6.0.

Mapping to OpenTelemetry

The mapping to OTel is direct. An MLflow span is an OTel span with MLflow attributes, and MLflow uses an OTel TracerProvider inside. Span.from_otel_proto() and Span.to_otel_proto() convert between the two forms. The attribute mapping page lists the mappings for each attribute schema.

Current backends (3.17.2)

A SQL store can also move old span data out to object storage, for example S3. The trace archival feature came in 3.13.0. The tag mlflow.trace.spansLocation says where the spans of a trace live (TRACKING_STORE or an archive).

How MLflow retired the file store

Direct SQLite with no server is not deprecated. A search of the 3.17.2 source and the changelog found no deprecation of it. Since 3.7.0 it is the default. Only the file store was retired, in these steps:

1. 3.6.0 (2025-11-07). “[Model Registry] Add deprecation warnings for filesystem backends (#18524, @harupy)”.
2. 3.7.0 (2025-12-05). Breaking change: “SQLite as Default Backend: MLflow now uses SQLite as the default backend instead of file-based storage, unless existing mlruns data is detected.” (#18497). The code is _get_default_tracking_uri() in mlflow/tracking/_tracking_service/utils.py. It returns ./mlruns only if ./mlruns/<digits>/meta.yaml exists, and returns sqlite:///mlflow.db in all other cases.
3. 3.10.0 (2026-02-20). “Add mlflow migrate-filestore command (#20615)”. The migration guide says “The filesystem backend is in maintenance mode and will not receive further updates.” The tool writes only to SQLite, with mlflow migrate-filestore --source /path/to/mlruns --target sqlite:///path/to/mlflow.db.
4. 3.13.0 (2026-05-29). Breaking change: “Pointing the tracking or model registry store at a local file-system path now raises an error by default; set MLFLOW_ALLOW_FILE_STORE=true to keep using a file-based store. (#22773, @harupy)”.

A run with a file:///... tracking URI showed the exact error in 3.17.2, below. It comes from FileStore.__init__ in mlflow/store/tracking/file_store.py.

The filesystem tracking backend (e.g., './mlruns') is in maintenance mode and will not receive further updates. Please migrate to a database backend (e.g., 'sqlite:///mlflow.db') to access the latest MLflow features. The `mlflow migrate-filestore` tool migrates your existing data losslessly. See https://mlflow.org/docs/latest/self-hosting/migrate-from-file-store for migration guidance. If the filesystem backend is required for your workflow, set `MLFLOW_ALLOW_FILE_STORE=true` to opt out of this exception.

No removal date is published. The backend store page calls the file store “still supported for backward compatibility”.

Why SQLite can seem to need a server. A client that is not the full mlflow Python package may be the cause. Section 6 shows that mlflow-tracing, the TypeScript SDK, the Claude Code plugin and the Codex plugin all reject or drop sqlite: URIs. For those clients, “SQLite” means “start mlflow server --backend-store-uri sqlite:///mlflow.db”.

Ingest of OTLP spans

• Endpoint. The tracking server takes POST /v1/traces (OTLP_TRACES_PATH in mlflow/tracing/utils/otlp.py, router in mlflow/server/otel_api.py). The header x-mlflow-experiment-id is required. The header x-mlflow-run-id is optional (3.14.0).
• Version. The first ingest code came before 3.6.0. The 3.6.0 release (2025-11-07) announced “Full OpenTelemetry Support in OSS Server: … ingest OpenTelemetry traces into MLflow” (#18540, #18532, #18357).
• Encodings. OTLP/HTTP protobuf works since 3.6.0, and 3.7.0 fixed it to return protobuf (#18929). Gzip and deflate came in 3.7.0 (#19024). JSON OTLP came in 3.12.0 (#22408). There is no gRPC endpoint.
• Backend. The server calls store.log_spans_async(). FileStore does not implement it, so ingest needs a SQL backend.
• Allow list. The server keeps service.name only for an allow list (claude-code, codex_cli_rs, codex_vscode, gemini-cli and qwen-code). It keeps resource attributes since 3.14.0.
• Docs. See the ingest docs and the OpenTelemetry overview.

Attribute translation on ingest

When MLflow stores a span, it maps these foreign attribute schemas to mlflow.spanType, inputs, outputs, token usage, model and provider. The translators are in mlflow/tracing/otel/translation/:

• Standards. OTel GenAI semantic conventions (genai_semconv.py, which reads gen_ai.operation.name and gen_ai.usage.*), OpenInference, Traceloop and OpenLLMetry.
• Agent CLIs. Claude Code, Gemini CLI, Google ADK and Spring AI.
• Other tools. Langfuse, Laminar, Vercel AI, VoltAgent and LiveKit.

A test checked the GenAI translation with no server. It builds an OTel protobuf span with gen_ai.operation.name=chat, gen_ai.request.model, gen_ai.provider.name and gen_ai.usage.input_tokens/output_tokens. It calls Span.from_otel_proto() and then SqlAlchemyStore.log_spans(experiment_id, [span]) on t.db. The results:

• Trace info. MLflow made the trace_info row, with input_tokens=10 and output_tokens=5.
• Span content. content gained mlflow.spanType="CHAT_MODEL", mlflow.chat.tokenUsage, mlflow.llm.model and mlflow.llm.provider.
• Columns. model_name and model_provider were filled.
• Quirk. The spans.type column stayed NULL for the translated span, although content says CHAT_MODEL. A search by span type can miss spans that came in with foreign schemas.

Export to an OTel collector

The settings below are in mlflow/environment_variables.py, and the export docs describe them.

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (with OTEL_EXPORTER_OTLP_TRACES_PROTOCOL and headers). If it is set, MLflow exports to the OTLP endpoint in place of the tracking store.
• MLFLOW_ENABLE_OTLP_EXPORTER (default True). Set to False, it turns off the OTLP export above, even when the OTel variable is set. It came in 3.5.0 (#17505).
• MLFLOW_TRACE_ENABLE_OTLP_DUAL_EXPORT (default False). It writes to both the tracking store and the collector.
• MLFLOW_ENABLE_OTEL_GENAI_SEMCONV (default False). It rewrites mlflow.* attributes to GenAI semantic conventions before OTLP export, since 3.11.0 (#21494). See the GenAI semconv docs.
• MLFLOW_USE_DEFAULT_TRACER_PROVIDER (default True, which gives an isolated provider). Set it to False to mix MLflow and plain OTel SDK spans in one trace. MLFLOW_TRACE_PROPAGATE_TO_OTEL_CONTEXT lets plain OTel libraries nest under MLflow spans.

Claude Code

Current path (3.13.0 and later). Claude Code tracing is a Claude Code plugin, mlflow-tracing@mlflow-plugins. The plugin is the npm package @mlflow/claude-code, and its source is in libs/typescript/integrations/claude-code. Install it with these commands:

claude plugin marketplace add mlflow/mlflow --sparse .claude-plugin
claude plugin install mlflow-tracing@mlflow-plugins
/mlflow-tracing:setup        # or: mlflow autolog claude

• Hook. The plugin registers one Stop hook, in hooks/hooks.json. The hook runs node ${CLAUDE_PLUGIN_ROOT}/bundle/stop.cjs with a 120-second timeout.
• Transcript. The hook reads the session transcript JSONL (transcript.ts, processTranscript). It makes an AGENT root span for each turn, with LLM and TOOL children and nested AGENT spans for subagents. Token and cache usage go on each LLM span.
• Write-ahead log. A write-ahead log, a local file of pending writes, keeps tracing from slowing the agent or losing traces (changelog 3.14.0).
• Tracking URI. isValidTrackingUri() in src/config.ts accepts only http:, https: and databricks URIs. The plugin cannot write to SQLite, so it needs mlflow server.
• History. Claude Code tracing came in 3.4 and 3.5 (#17521, #18022), as a Python hook that mlflow autolog claude wrote into .claude/settings.json. In 3.12.0, the tracing moved to TypeScript (#22338). The 3.13.0 notes say “mlflow autolog claude no longer installs the old Python autolog hook; Claude Code tracing is now provided by the official Claude plugin, which must be installed separately. (#23339)”. The Python mlflow/claude_code/tracing.py still has the transcript parser.
• OTel path. Claude Code also emits OTLP traces by itself, which is beta in Claude Code, to /v1/traces. MLflow maps claude_code.interaction, claude_code.llm_request and claude_code.tool to AGENT, LLM and TOOL (translation/claude_code.py). The content is <REDACTED> if the user does not set OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS or OTEL_LOG_TOOL_CONTENT.
• Agent SDK. For the TypeScript Claude Agent SDK, use createTracedQuery(query). For the Python Claude Agent SDK, use mlflow.anthropic.autolog().
• Docs. See the Claude Code docs.

Codex

Codex tracing came in 3.12.0, as “Add TypeScript Codex CLI tracing via notify hook (#22410)”. Its parts are these:

• Notify hook. The npm package @mlflow/codex adds notify = ["mlflow-codex", "notify-hook"] to config.toml. Codex calls the hook after each turn. The hook reads the rollout JSONL transcript and honors CODEX_HOME since 3.16.0. Each turn gives an AGENT root span with LLM and TOOL children.
• Native OTel. The [otel] table in ~/.codex/config.toml can point at http://host:5000/v1/traces with x-mlflow-experiment-id. The docs warn that these spans show “internal execution details” and are not a clean conversation flow.
• Server. The docs say “The MLflow server must be running to receive traces.”
• Docs. See the Codex docs.

The AI Gateway (3.13.0) can also trace Claude Code, Codex and Gemini CLI. It works as a proxy for model calls.