---
type: concept
x-llmwiki:
  schemaVersion: "0.1"
  contentHash: 53445ba93d236c8ee34ee5fa3603b1a3f587b85eb927a8a5cbf5b65497cd7523
  pageDirectory: concepts
  sources:
    - tracing-langgraph-databricks-on-aws.md
  confidence: 0.97
  provenanceState: extracted
  freshnessStatus: unverified
  aliases:
    - manual-span-instrumentation-in-langgraph-nodes
    - MSIILN
  citations:
    - file: tracing-langgraph-databricks-on-aws.md
title: Manual Span Instrumentation in LangGraph Nodes
description: Adding child spans inside LangGraph nodes or tools using mlflow.start_span() to gain detailed per-step insights
tags:
  - mlflow
  - tracing
  - instrumentation
  - langgraph
timestamp: "2026-06-19T23:12:20.296Z"
---

<!-- Wiki page: Manual Span Instrumentation in LangGraph Nodes -->
---

## Manual Span Instrumentation in LangGraph Nodes

**Manual Span Instrumentation** allows you to insert custom child spans inside a LangGraph node or tool to capture finer-grained execution details. While [MLflow Tracing](/concepts/mlflow-tracing.md) provides [Automatic Tracing](/concepts/automatic-tracing.md) via `mlflow.langchain.autolog()`, you can enrich those auto-generated [Traces](/concepts/traces.md) by manually creating spans within your node logic. This is useful when a single node performs multiple distinct operations (e.g., validation checks, API calls, or sub‑tasks) and you want to monitor each step independently. ^[tracing-langgraph-databricks-on-aws.md]

## Prerequisites

Manual span instrumentation builds on top of the automatic LangGraph tracing integration. You need:

- [MLflow](/concepts/mlflow.md) ≥ 3.1 (with the `databricks` extras) installed, along with `langgraph`, `langchain_core`, `langchain_openai`, and any other LangChain packages your graph requires.
- A call to `mlflow.langchain.autolog()` to enable the base auto‑tracing layer. ^[tracing-langgraph-databricks-on-aws.md]

## How to Add Manual Spans

Inside a node or tool function, use the `mlflow.start_span()` context manager to create a child span. Each span should be given a descriptive name, a SpanType (such as `SpanType.TOOL` or `SpanType.FUNCTION`), and you should set its inputs and outputs using `span.set_inputs()` and `span.set_outputs()`. The span automatically attaches as a child of the parent trace that was created by auto‑tracing. ^[tracing-langgraph-databricks-on-aws.md]

The example below, adapted from the LangGraph Code Assistant tutorial, adds manual spans for the `import_check` and `execution_check` validations inside the `code_check` node:

```python
def code_check(state: GraphState):
    # State
    messages = state["messages"]
    code_solution = state["generation"]
    iterations = state["iterations"]

    # Get solution components
    imports = code_solution.imports
    code = code_solution.code

    # Check imports
    try:
        with [[mlflow|MLflow]].start_span(name="import_check", span_type=SpanType.TOOL) as span:
            span.set_inputs(imports)
            exec(imports)
            span.set_outputs("ok")
    except Exception as e:
        error_message = [("user", f"Your solution failed the import test: {e}")]
        messages += error_message
        return {
            "generation": code_solution,
            "messages": messages,
            "iterations": iterations,
            "error": "yes",
        }

    # Check execution
    try:
        code = imports + "\n" + code
        with [[mlflow|MLflow]].start_span(name="execution_check", span_type=SpanType.TOOL) as span:
            span.set_inputs(code)
            exec(code)
            span.set_outputs("ok")
    except Exception as e:
        error_message = [("user", f"Your solution failed the code execution test: {e}")]
        messages += error_message
        return {
            "generation": code_solution,
            "messages": messages,
            "iterations": iterations,
            "error": "yes",
        }

    # No errors
    return {
        "generation": code_solution,
        "messages": messages,
        "iterations": iterations,
        "error": "no",
    }
```

After this instrumentation, the trace for the `check_code` node will contain two child spans, recording whether each validation passed or failed, along with exception details if an error occurred. ^[tracing-langgraph-databricks-on-aws.md]

## Benefits

- **Granular observability**: See which specific step inside a node succeeded or failed.
- **Richer debugging**: Exception details are captured at the sub‑step level, making it easier to diagnose failures without re‑running the entire graph.
- **Composability**: Manual spans work seamlessly with the automatic [Traces](/concepts/traces.md) generated by `mlflow.langchain.autolog()`. ^[tracing-langgraph-databricks-on-aws.md]

## Related Concepts

- [MLflow Tracing](/concepts/mlflow-tracing.md) – The underlying tracing system that captures and visualizes execution spans.
- LangGraph – The framework for building stateful, multi‑actor LLM applications.
- [Autologging](/concepts/mlflow-autologging.md) – Enables automatic trace capture for LangChain/LangGraph graphs.
- SpanType – Enum defining the type of a manual span (e.g., `TOOL`, `FUNCTION`).
- [Manual Tracing APIs](/concepts/manual-tracing-apis.md) – General APIs for creating custom [Traces](/concepts/traces.md) outside of auto‑tracing.
- LangGraph Code Assistant – Example graph that uses manual spans for validation steps.

## Sources

- tracing-langgraph-databricks-on-aws.md

# Citations

1. [tracing-langgraph-databricks-on-aws.md](/references/tracing-langgraph-databricks-on-aws-6240217a.md)
