Lightweight observability for local development

[BruceWayne4]

DeerFlow currently integrates with tools like Langfuse for observability. While working locally, I found that for simple development and debugging workflows, this setup can feel a bit heavy.

I was wondering if there’s interest in supporting a more lightweight, built-in way to inspect execution flows—especially for:

• understanding how tasks are broken down across agents
• debugging intermediate steps and failures
• improving the local development experience

Curious if this is something already considered in the roadmap, or if there are preferred approaches for lightweight tracing/debugging within DeerFlow.

Happy to explore this further or contribute in this area if it aligns.

[DaoyuanLi2816]

This use case now has a possible extension-based path: the current host exposes caller-scoped RunEvidenceReader APIs and full-stack plugin surfaces. I'd like to help implement a small, optional read-only diagnostic plugin, rather than add an observability service to the default deployment.

One concrete workflow would be: after a run fails or is interrupted, a user selects that run and inspects its authoritative status plus a paginated timeline of persisted events, including an explicit indication when evidence is missing. The existing evidence-reader tests pass on main 63e399f2 (23 tests); that validates the foundation, not a completed plugin.

The initial scope would exclude evaluation suites, LLM judging, automatic retries, global/admin visibility, external telemetry export, and another subagent step UI. Subtask cards already provide their own step timelines. It would reuse request-scoped readers for the authenticated user's runs, avoid exposing raw payloads under an assumption of complete redaction, and not equate collected events with successful task completion.

This should remain distinct from #4070/#4083's evaluation effort: no new eval orchestration or runtime subsystem. A small integration spike would first verify the route/browser-page contract before proposing any host changes.

Are you still pursuing the original proposal, or would this be a useful slice to collaborate on? @AnnaSuSu @Vanzeren Would an optional plugin example fit the intended extension boundary, or would you prefer adjacent CLI tooling? I'm willing to take a focused implementation once the scope and existing ownership are agreed.

[AnnaSuSu]

An optional read-only diagnostic plugin looks like a reasonable starting point to me. LLM Space, DeerFlow's sister project, would be a useful reference for the Trace / Debug interaction: selecting a historical run, inspecting model messages and tool arguments/results, and stepping through the recorded execution to locate a failure.

Its core concepts documentation already lists DeerFlow run-event JSONL as a supported import format. For the initial spike, I'd suggest importing a real failed or interrupted DeerFlow run to see how much the existing workflow covers and identify what the in-app plugin should add. Import support alone does not establish complete event coverage or a live connection.

For the first version, I'd keep the plugin focused on the authenticated user's authoritative run status, a paginated timeline of persisted events, and clear indications of evidence availability or known gaps. That fits the small diagnostic scope you outlined. Your proposed route/browser-page integration spike would be a useful next step before considering any host changes.

[BruceWayne4]

Hey @DaoyuanLi2816, this approach seems like a good starting point. I'm up for collaboration with @AnnaSuSu and @Vanzeren.
Though this will be my first open source contribution, I may need initial help in collaboration process.

Thanks

[BruceWayne4]

Hey @AnnaSuSu and @Vanzeren , Have you started on this?

Thanks

[AnnaSuSu]

@BruceWayne4 Please go ahead and take the lead on this as an optional DeerFlow plugin. My earlier reply was guidance on the direction and scope; I'm happy to review your PR when it's ready.

DeepSeek Harness and LLM Space are useful references to explore. Please build against DeerFlow's existing plugin interfaces and start with the small read-only diagnostic scope discussed above: run status, a paginated event timeline, and clear indications of missing evidence.

@DaoyuanLi2816 also offered to help implement this, so please coordinate here on the split of work to avoid overlap. Feel free to post any concrete questions as you get started.

[BruceWayne4]

[BruceWayne4]

itr-1.md

[BruceWayne4]

I’m attaching the design plan for the plugin and the UI mockup for reference. The design is not finalized yet.

@DaoyuanLi2816, we can discuss it here and proceed with the next steps of design, which include:

1. Event catalog: Defining every event type and what the UI should display for each.
2. Timeline row structure: Deciding which columns and fields should be included in each timeline row.
3. Status panel and notes: Reviewing how the status panel (at the top, below the thread ID) and notes should be structured, and deciding whether we need the status panel at all.

Feedback and suggestions are welcome.

[DaoyuanLi2816]

I read itr-1.md against the host contracts on 2768b86f. A few suggestions for those three design questions:

• Keep the status panel: RunStatusView is the authoritative lifecycle projection. Treat run.end and missing terminal events as timeline evidence, not substitutes for that status. A null status should remain unavailable/not-visible, without distinguishing another user's run.
• For timeline rows, start with sequence, timestamp, type/category and a short summary, with details collapsed. Keep an unknown-event fallback rather than requiring an exhaustive renderer for every catalog entry. seq is thread-scoped, so gaps between a selected run's events alone do not prove missing evidence.
• Keep pagination and truncation visible in the notes. A page with has_more is incomplete; use next_after_seq, not timestamps or an assumed contiguous sequence. A finished status with an empty timeline should say evidence unavailable, not imply no work occurred.
• One privacy boundary to retain: the reader deep-copies content and redacts metadata secrets, but does not promise general content redaction. Bounding text/metadata is not sanitization. Render payloads as escaped text; avoid presenting raw content as already safe or adding export in this first slice.

The reported real-run campaign sounds useful. For review, an interrupted/failed example, a pagination boundary, and an unknown event would help pin the behavior above. I haven't run your plugin, so this is a contract/design review, not validation of the implementation. Please keep the implementation lead; I'm not starting a parallel plugin.

[BruceWayne4]

itr2.md

[BruceWayne4]

Attaching the in depth details of Status Panel, Timeline Row structure and Event Catalog.

[BruceWayne4]

Hello @DaoyuanLi2816, Can you please go through the MD file?

[DaoyuanLi2816]

I read itr2.md against host main 4b1e06bb. Keeping the status panel and treating loaded token/model evidence as partial makes sense. Three points need updating against the current host:

• Events are not saved only at run end. The Journal can flush at its buffer threshold, and the worker's subagent buffer flushes at its threshold or a subagent.end. A running run can therefore already have persisted events. Also, has_more=false means caught up with the current read, not permanently complete while the run is active; preserve the cursor when refreshing.
• The catalog now includes run.terminal: the owner's confirmed business outcome, distinct from root graph run.end. Add a row for it without replacing RunStatusView. Older histories need not contain it, and its presence alone does not establish complete/sealed evidence. A run can have several root run.end events before a later business failure.
• For llm.tool.result and subagent.end, color explicitly recognized failure statuses red, rather than every value other than success/completed. Missing or future status fields should stay unknown/neutral, consistent with your generic fallback, not become invented failures.

Useful acceptance examples would be an active parent with a completed subagent, a later business failure after a root run.end, and legacy history without run.terminal, alongside the existing paging/unknown-event cases. This is a source/contract review, not a run of your plugin. Please retain the implementation lead; I'm not starting a parallel implementation.