From f126d43684b62a031b0c9345deffca5d3f9f57ac Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
 <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Fri, 2 Oct 2026 14:05:12 +0000
Subject: [PATCH] docs: explain consistent SQLite reads during telemetry
 eviction

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 src/frontend/src/content/docs/dashboard/data-persistence.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/frontend/src/content/docs/dashboard/data-persistence.mdx b/src/frontend/src/content/docs/dashboard/data-persistence.mdx
index e397a91af8..8413585199 100644
--- a/src/frontend/src/content/docs/dashboard/data-persistence.mdx
+++ b/src/frontend/src/content/docs/dashboard/data-persistence.mdx
@@ -121,6 +121,8 @@ The dashboard applies the following default data retention limits:
 
 When these limits are exceeded, the oldest corresponding data is removed. Attribute, span-event, resource, instrumentation-scope, instrument, and dimension limits also apply.
 
+Reading a trace, span, structured log, or metric detail view involves multiple dependent SQLite queries, for example selecting a trace and then its spans. The dashboard runs these dependent reads inside a single deferred SQLite transaction so eviction can't remove a selected row between queries. This keeps the Traces, Spans, Structured Logs, and Metrics views consistent during normal telemetry eviction, without blocking concurrent ingestion under SQLite's write-ahead log (WAL) mode. Cached resource and instrument metadata lookups aren't part of these transactions, so an explicit telemetry clear that runs concurrently with a cache metadata lookup isn't protected by this behavior.
+
 | Mode | Database retention |
 |------|--------------------|
 | `None` | The temporary database lasts for the dashboard process and is deleted after a clean shutdown. |