--- title: "Query status" description: "Post-hoc observability for a submitted retriever query: reads the S3 _DONE marker, lists result files, and runs a diagnostics engine over the combined data." icon: material/clipboard-pulse-outline --- Inspect a previously-submitted [Retriever](../../../retriever/) query by ID. It: - reads the `_DONE.json` marker from S3 - lists event files and byte-count markers - optionally fetches per-query CloudWatch events and pod logs - runs a diagnostics engine that surfaces known dispatcher-failure signatures with a stored remedy Call after `log10x_retriever_query` returns 0 events or `partial_results=true` to find out what actually happened inside the engine. ## :material-code-braces: Example !!! tenx-ask "You" why did my last retriever query return 0 events? !!! tenx-answer "Log10x" Query 7f3c... completed in 240ms. Submitted 48 scan tasks. Scanned 0 objects. DIAGNOSTIC [CONFIRMED]: `dispatcher_failure`. Matched pattern: `include_resolve_streamer_legacy`. Remedy: upgrade chart to 1.0.21+. ## :material-chat-question-outline: More to ask - *"status of query `7f3c1d2e-...`"* - *"diagnose the last retriever call, skip pod logs"* - *"what's in `_DONE.json` for query `abc-123` on target `app`"* ## :material-check-decagram-outline: Prerequisites This tool requires the [Retriever](../../../retriever/) deployed with `__SAVE_LOG10X_RETRIEVER_URL__` and `__SAVE_LOG10X_RETRIEVER_BUCKET__` set. Pod-log confirmation also requires `kubectl` access from the MCP process; per-query CloudWatch events require `queryLogGroup` configured in helm values. ## :material-code-json: Schema and samples ??? tenx-input-example "Input example" Representative call (synthetic, not captured from the live demo env). ```json { "query_id": "7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "target": "app", "include_pod_logs": true } ``` ??? tenx-input-schema "Input schema" Agent-facing JSON Schema (the canonical shape the MCP server publishes via `tools/list`): ```json { "type": "object", "properties": { "query_id": { "type": "string", "description": "UUID of a previously-submitted retriever query. Returned as data.query_id from log10x_retriever_query." }, "target": { "type": "string", "default": "app", "description": "Target app/service prefix used when the original query was submitted. Defaults to \"app\". Must match the target that was passed to the original query." }, "include_pod_logs": { "type": "boolean", "default": true, "description": "When true and a dispatcher_failure is suspected (scanned=0 + submittedTasks>0), attempt kubectl logs on the retriever pod to confirm the chart 1.0.20 include-resolution error. Requires kubectl access from the MCP process. Set false to skip the kubectl call." } }, "required": [ "query_id" ], "additionalProperties": false } ``` Source: [`src/tools/retriever-query-status.ts`](https://github.com/log-10x/log10x-mcp/blob/main/src/tools/retriever-query-status.ts). ??? tenx-output-example "Output example" Representative envelope (synthetic, not captured from the live demo env). `view: "summary"` returns the full `StructuredOutput` with typed `data`. Headline (the 1-line agent-facing answer): > _Retriever query status for 7f3c1d2e-...: Query 7f3c1d2e-... on target app completed (reason=dispatched, elapsed=240ms). Scanned 0 objects, matched 0, submitted 48 scan tasks, stream requests: 0._ ```json { "schema_version": "1.0", "schema_epoch": "2026-05-25", "tool": "log10x_retriever_query_status", "generated_at": "2026-06-05T12:00:00.000Z", "view": "summary", "summary": { "headline": "Retriever query status for 7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f: Query 7f3c1d2e-... on target app completed (reason=dispatched, elapsed=240ms). Scanned 0 objects, matched 0, submitted 48 scan tasks, stream requests: 0." }, "data": { "status": "done", "query_id": "7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "target": "app", "bucket": "log10x-retriever-archive", "s3_done_key": "indexing-results/tenx/app/qr/7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f/_DONE.json", "stats": { "queryId": "7f3c1d2e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "completedAt": "2026-06-05T11:59:58.120Z", "elapsedMs": 240, "reason": "dispatched", "scanned": 0, "matched": 0, "skippedSearch": 0, "skippedTemplate": 0, "streamRequests": 0, "streamBlobs": 0, "submittedTasks": 48, "expectedMarkers": 48 }, "done_read_error": null, "marker_count": 0, "event_files": { "count": 0, "total_bytes": 0, "keys": [] }, "cloudwatch_events": { "log_group": "/log10x/retriever/query", "event_count": 4, "events": [ { "timestamp": "2026-06-05T11:59:57.880Z", "level": "ERROR", "message": "could not resolve include: 'cloud/streamer/subquery'", "data": { "queryId": "7f3c1d2e-..." } } ], "error": null }, "diagnostics": { "category": "dispatcher_failure", "confidence": "confirmed", "evidence": [ "_DONE.json: reason=\"dispatched\", submittedTasks=48, streamRequests=0, scanned=0", "CONFIRMED: pod logs match dispatcher pattern 'include_resolve_streamer_legacy'.", "Remedy: Chart < 1.0.21 with legacy hardcoded streamer paths. Upgrade chart to 1.0.21+ which uses apps/retriever/* paths." ], "pattern_id": "include_resolve_streamer_legacy", "remedy": "Chart < 1.0.21 with legacy hardcoded streamer paths. Upgrade chart to 1.0.21+ which uses apps/retriever/* paths." }, "human_summary": "Query 7f3c1d2e-... on target app completed (reason=dispatched, elapsed=240ms). Scanned 0 objects, matched 0, submitted 48 scan tasks, stream requests: 0. No event JSONL files found in the qr/ prefix. 4 CloudWatch event(s) from log group /log10x/retriever/query. DIAGNOSTIC [CONFIRMED]: dispatcher_failure ...", "source_disclosure": { "retriever_state_source": "helm", "namespace": "log10x" } }, "actions": [ { "tool": "log10x_advise_retriever", "args": {}, "reason": "chart 1.0.21+ upgrade or the rename-residual fix in modules/feat/soft-drop resolves this dispatcher failure" } ], "truncated": false, "warnings": [] } ``` ??? tenx-output-schema "Output schema" The `data` block inside the [StructuredOutput envelope](../index.md#json-by-default-output): ```typescript interface ToolData { status: 'done' | 'not_found' | 'unknown'; query_id: string; target: string; bucket: string; s3_done_key: string; stats: { queryId?: string; completedAt?: string; elapsedMs?: number; reason?: string; scanned?: number; matched?: number; skippedSearch?: number; skippedTemplate?: number; streamRequests?: number; streamBlobs?: number; submittedTasks?: number; expectedMarkers?: number; } | null; done_read_error?: string; marker_count: number; event_files: { count: number; total_bytes: number; keys: string[]; }; cloudwatch_events: { log_group: string | null; event_count: number; events: Array<{ timestamp: string; level: string; message: string; data?: Record; }>; error?: string; advisory?: string; }; diagnostics: { category: 'dispatcher_failure' | 'results_not_uploaded' | 'dispatch_failure' | 'observability_disabled' | 'ok' | 'unknown'; confidence: 'confirmed' | 'suspected' | 'advisory' | 'none'; evidence: string[]; pattern_id?: 'include_resolve_streamer_legacy' | 'config_var_resolve' | 'launch_pipeline_run_fail'; remedy?: string; }; human_summary: string; source_disclosure: { retriever_state_source: string; namespace: string | null; }; } ``` Envelope-level fields the agent should also read: `summary.headline` (1-line answer), `actions[]` (next-call chain hints as `{tool, args, reason}`), `truncated: boolean`, `images[]` (PNG attachments where applicable), `schema_epoch` (engine-ID stability boundary).