For the complete documentation index, see llms.txt. This page is also available as Markdown.

Flow Debugging User Guide

Overview

Flow Debugging is an AI-powered capability that helps support engineers, QA users, and flow developers quickly investigate and troubleshoot flow executions without manually searching through Grafana logs and traces.

Instead of running complex Grafana queries, users can ask natural language questions about a flow run and receive detailed debugging information directly within the Debug Panel.

The solution is powered by System Flows, an LLM Agent, and a custom Grafana MCP Server that retrieves logs, traces, errors, and execution data from Grafana.


Purpose

The Flow Debugging feature helps users:

  • Analyze previous flow executions.

  • Identify errors and warnings.

  • View customer inputs submitted during a run.

  • Retrieve session and trace information.

  • Review execution timelines and component performance.

  • Generate summaries of flow runs.

  • Troubleshoot issues using natural language queries.


Key Benefits

  • Simplified Troubleshooting

    • No need to navigate Grafana and execute complex log queries manually.

  • Natural Language Interaction

    • Ask questions in plain English and receive actionable debugging insights.

  • Faster Root Cause Analysis

    • Quickly identify failures, latency issues, warnings, and execution details.

  • Centralized Debugging Experience

    • Access logs, traces, summaries, and execution information from a single interface.

  • Improved Developer Productivity

    • Reduce investigation time and accelerate issue resolution.


How Flow Debugging Works

Step 1: Execute a Flow

Run a flow through the application as usual.

Step 2: Open the Debug Panel

Navigate to the Debug Panel from the flow interface.

Step 3: Ask Questions

Enter natural language requests related to a flow execution.

Examples:

  • What happened to my last run?

  • Response Includes

    • Session ID

    • Execution timestamp

    • Run status

    • Errors (if any)

    • Warnings (if any)

    Example Result:

    • Flow executed successfully.

    • Session ID returned.

    • No errors detected.

    • No warnings detected.

View Customer Inputs

  • Show the user inputs for the last run.

  • The system displays customer inputs collected during the run.

  • User Input:

    • If redaction policies are enabled, sensitive information will be displayed in its redacted format.

Debug response:

View Execution Traces

  • Give me the traces of the last execution.

  • The system retrieves execution traces, including:

    • Session creation

    • Gateway processing

    • Flow retrieval

    • Component execution

    • Processing duration

    • Response generation

    Example:

    • Channel Gateway initiated session.

    • Session processing took 387 ms.

    • Flow retrieval timings displayed.

    • Component execution timeline available.

Generate Flow Summary

  • Summarize the flow run.

  • The AI agent generates a concise summary describing:

    • User actions

    • Flow progression

    • Key inputs

    • Execution outcome

    • Any issues encountered

Step 4: Data Is Retrieved

Relevant information such as:

  • Logs

  • Traces

  • Error details

  • Service health

  • Session information

is collected.

Step 5: Results Are Returned

The debugging response is displayed in the Debug Panel.


Architecture Overview

Flow Debugging is built using System Flows and MCP-based integrations.

Components:

  • Debug Panel: The interface where support or QA users submit debugging requests.

  • System Flow: A predefined flow that handles debugging conversations and orchestrates data retrieval.

  • LLM Agent: Processes user questions and determines which debugging tools should be invoked.

  • Grafana MCP Server: Provides access to:

    • Logs

    • Traces

    • Error patterns

    • Service health metrics

    • Execution details

  • Grafana Data Source: Stores flow execution telemetry and diagnostic information used during debugging.


Technical Workflow

  • User Opens Debug Panel: A support user or QA user accesses the debugging interface.

  • System Flow Loads: The platform loads the debugging system flow during runtime.

  • User Submits a Query: The user asks a natural language debugging question.

  • LLM Agent Processes Request: The agent analyzes the request and determines which tools are required.

  • MCP Tools Retrieve Data: The Grafana MCP Server executes queries against available telemetry sources.


Current Scope

The current release provides the first version of Flow Debugging and supports:

  • Run investigation

  • User input inspection

  • Session analysis

  • Trace visualization

  • Execution summaries

  • Error identification

  • Historical run lookup

Additional enhancements are planned to provide deeper debugging capabilities and more advanced flow analysis.


Conclusion

Flow Debugging simplifies flow investigation by allowing users to interact with execution data using natural language. By combining System Flows, an AI-powered LLM agent, and a custom Grafana MCP Server, users can quickly access logs, traces, errors, and execution insights without manually navigating Grafana. This significantly reduces troubleshooting effort, accelerates root cause analysis, and improves the overall developer and support experience.

Last updated

Was this helpful?