Instrument Your App with MLflow Tracing
New to MLflow Tracing? Checkout the Quick Start Guide to get started.
This page provides a comprehensive guide for instrumenting your GenAI applications with MLflow Tracing.
1. Installation
- Python
- JS/TS
Add mlflow-tracing
to your Python environment to enable tracing features with minimum set of dependencies.
pip install mlflow-tracing
npm install mlflow-tracing
The mlflow-tracing
Python package does not include other MLflow features, such as the self-host tracking server, evaluation capabilities, prompt management, etc. If you want to use the full set of MLflow's features, please install the full MLflow package. We recommend using the mlflow-tracing
package for production applications to keep the dependencies and package footprint minimal.
pip install mlflow
2. Connect Your Application with MLflow
- Self-Host MLflow (Local)
- Remote MLflow
- Databricks
- OpenTelemetry
For local development or personal use, locally hosting MLflow is a good option. While this is not recommended for production use, it is the fastest way to get started. For logging traces, we recommend using a SQL Backend for better performance.
To start a local MLflow server, run the following command in your terminal. Alternatively, you can use the official Docker image to run the server.
# Replace sqlite:/// part with your preferred database URI.
mlflow server --host 127.0.0.1 --port 5000 --backend-store-uri sqlite:///mlruns.db
Then, in your application, configure the tracking URI and set an active experiment using the following code:
Python:
import mlflow
mlflow.set_tracking_uri("http://127.0.0.1:5000")
mlflow.set_experiment("<your-experiment-name>")
JS/TS:
import * as mlflow from "mlflow-tracing";
mlflow.init(
trackingUri: "http://127.0.0.1:5000",
experimentId: "<your-experiment-id>", // If no experiment is created yet, create it on UI first.
);
When you have a remote MLflow server already running (either self-hosted or a cloud-based managed MLflow), you can connect your application to it by configuring the tracking URI.
Python
import mlflow
mlflow.set_tracking_uri("https://<your-mlflow-server>:<port>")
mlflow.set_experiment("<your-experiment-name>")
JS/TS:
import * as mlflow from "mlflow-tracing";
mlflow.init(
trackingUri: "https://<your-mlflow-server.com>:<port>",
experimentId: "<your-experiment-id>", // If no experiment is created yet, create it within the MLflow UI first.
);
These steps describe using a Databricks Personal Access Token. MLflow also works with the other Databricks-supported authentication methods.
If you're working on tracing with Databricks, configure your authentication with the Databricks CLI or by using the following environment variables:
export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"
Then, set the tracking URI and the target experiment to store the traces in MLflow from your application.
Python:
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("<your-experiment-name>")
JS/TS:
import * as mlflow from "mlflow-tracing";
mlflow.init(
trackingUri: "databricks",
experimentId: "<your-experiment-id>",
);
MLflow traces are compatible with OpenTelemetry, allowing you to export traces to OpenTelemetry-compatible monitoring backends.
Install the OpenTelemetry Protocol (OTLP) exporter:
pip install opentelemetry-exporter-otlp
Then, configure the following environment variables:
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://your-otel-collector.com:4317/v1/traces"
Your monitoring backends may have additional setup to enable trace exporting. Please refer to OpenTelemetry Integration for additional configurations and links to the each vendor's setup documentation.
OpenTelemetry export is only supported for the Python SDK right now.
3. Instrumenting Your Application Logic
MLflow offers different ways to instrument your application logic. Follow the links below to learn more about each approach to instrument your application:

Automatic Tracing
Instrument your application with a single line of code.

Manual Tracing
Instrument any Python code with a few lines of code, with full control and flexibility.

Typescript SDK
Instrument your Node.js applications with MLflow Tracing Typescript SDK.
⚙️ Common Patterns
Production Considerations
MLflow Tracing is production ready, but in order to ensure the scalability and reliability of the tracing system, we recommend the following best practices:
- Enable Async Logging and set up appropriate queue size and timeout.
- Use the lightweight
mlflow-tracing
package for minimizing the package footprint and dependencies. - Use managed MLflow services for reducing the operational overhead and ensure the scalability of the tracing system.
- When using self-hosted MLflow, make sure to use the SQL Backend with a scalable database like PostgreSQL. The default file-based backend has scalability limitations and is not recommended for production use.
Async Applications
Async programming is an effective tool for improving the throughput of your application, particularly for LLM-based applications that are typically I/O bound. MLflow Tracing natively supports instrumenting async applications.
Multi-Threaded Applications
Multi-threading is a common strategy for parallelizing IO-bound operations in applications. MLflow Tracing supports multi-threaded applications using context propagation.
Managing User sessions
Many LLM-based applications are deployed as chat-based applications, where each user session is a separate thread. Grouping traces by user session is a common practice. MLflow Tracing supports managing user sessions.
Redacting PII Data
Traces can contain sensitive data such as raw user inputs, internal document contents, etc. MLflow Tracing supports redacting PII data using flexible masking rules, custom functions, and integration with external PII masking libraries.
Collecting User Feedbacks
User feedback is a valuable source of information for improving the user experience of your application. MLflow Tracing supports collecting user feedback on traces to track and analyze the feedbacks effectively.