Manual tracing

While MLflow's automatic tracing provides instant observability for supported frameworks, manual tracing gives you complete control over how your GenAI applications are instrumented. This flexibility is essential for building production-ready applications that require detailed monitoring and debugging capabilities.

When to use manual tracing

Manual tracing is the right choice when you need:

Fine-grained control over trace structure

• Define exactly which parts of your code to trace
• Create custom hierarchies of spans
• Control span boundaries and relationships

Custom framework instrumentation

• Instrument proprietary or internal frameworks
• Add tracing to custom LLM wrappers
• Support new libraries before official integration

Advanced workflow scenarios

• Multi-threaded or async operations
• Streaming responses with custom aggregation
• Complex nested operations
• Custom trace metadata and attributes

Prerequisites

MLflow 3

This page requires the following packages:

• mlflow[databricks]>=3.1: Core MLflow functionality with GenAI features and Databricks connectivity.
• openai>=1.0.0: (Optional) Only if your custom code interacts with OpenAI; replace with other SDKs if needed.

Install the basic requirements:

Python

%pip install --upgrade "mlflow[databricks]>=3.1"
# %pip install --upgrade openai>=1.0.0 # Install if needed

MLflow 2.x

This guide requires the following packages:

• mlflow[databricks]>=2.15.0,<3.0.0: Core MLflow functionality with Databricks connectivity.
• openai>=1.0.0: (Optional) Only if your custom code interacts with OpenAI.

MLflow version

Databricks strongly recommends installing MLflow 3.1 or newer if using mlflow[databricks].

Install the basic requirements:

Python

%pip install --upgrade "mlflow[databricks]>=2.15.0,<3.0.0"
# pip install --upgrade openai>=1.0.0 # Install if needed

Which API should I use?

Choose the right manual tracing approach for your needs:

Feature	Function decorators	Span tracing	Low-Level APIs
Use case	Trace entire functions with one-line decorator. Minimal code changes required.	Trace arbitrary code blocks within functions for fine-grained control.	Direct control over trace lifecycle for complex scenarios.
Automatic Parent-Child	Yes	Yes	No - manual management
Exception Handling	Automatic	Automatic	Manual
Works with Auto-trace	Yes	Yes	No
Thread Safety	Automatic	Automatic	Manual
Custom Trace IDs	No	No	Yes