---
title: "Retriever probe"
description: "End-to-end Retriever chain verifier: fires a synthetic query and asserts every stage from the customer-owned offload bucket to MCP read-back."
icon: material/stethoscope
---

Fires a synthetic query at the deployed Retriever and asserts every stage of the chain:

- freshness of the customer-owned offload bucket
- indexer pipeline running
- SQS queues drained
- pod ready
- query submission
- CloudWatch scan match
- CloudWatch stream fetch
- S3 `qr/*.jsonl` write
- MCP-side events returned

Each stage is a named assert with a one-line `observed` summary and a stored remedy keyed on the assert name. Use as a deep doctor diagnostic or as the post-install verify step.

The probe reads from the offload (overflow) bucket the Receiver writes to and the result bucket the Retriever writes back to. Both are customer-owned S3.

## :material-code-braces: Example

!!! tenx-ask "You"

    run the retriever probe

!!! tenx-answer "Log10x"

    Retriever end-to-end health check passed.

    Picked the highest-volume pattern, ran query qr-7c12, all 8 checks succeeded (4.2s).

## :material-chat-question-outline: More to ask

- *"post-install verify for the retriever"*
- *"is the retriever chain healthy end-to-end?"*
- *"probe the retriever against hash 3f8a..."*

## :material-check-decagram-outline: Prerequisites

[Retriever](../../../retriever/) installed in the cluster, with `kubectl` and `aws` CLI reachable from the MCP host. The probe needs:

- S3 read on the offload + result buckets
- SQS list/describe
- CloudWatch Logs filter
- the metric backend reachable for the top-hash pick (or pass `target_hash` explicitly)

## :material-code-json: Schema and samples

??? tenx-input-example "Input example"

    Representative call (synthetic, not captured from the live demo env).

    ```json
    {
      "namespace": "log10x",
      "window_minutes": 5
    }
    ```

??? tenx-input-schema "Input schema"

    Agent-facing JSON Schema (the canonical shape the MCP server publishes via `tools/list`):

    ```json
    {
      "type": "object",
      "properties": {
        "namespace": {
          "type": "string",
          "default": "log10x",
          "description": "Kubernetes namespace where the retriever pod runs. Default: \"log10x\"."
        },
        "offload_bucket": {
          "type": "string",
          "description": "S3 bucket the receiver offloads data to (the bucket the retriever indexer reads from). Default: read from LOG10X_STREAMER_BUCKET env."
        },
        "input_bucket": {
          "type": "string",
          "description": "S3 bucket where the retriever WRITES qr/<id>/*.jsonl result objects. Default: read from retriever state (helm probe)."
        },
        "query_log_group": {
          "type": "string",
          "default": "log10x-retriever-query-events",
          "description": "CloudWatch log group the retriever writes per-query execution events to."
        },
        "target_hash": {
          "type": "string",
          "description": "Pre-picked tenx_hash to query for. When omitted, the probe queries the metric backend for the top-volume hash over the last 5 min."
        },
        "window_minutes": {
          "type": "number",
          "default": 5,
          "description": "Query window size in minutes. Default: 5."
        }
      },
      "additionalProperties": false
    }
    ```

    Source: [`src/tools/retriever-probe.ts`](https://github.com/log-10x/log10x-mcp/blob/main/src/tools/retriever-probe.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 end-to-end health check passed. Picked the highest-volume pattern, ran query qr-7c12, all 8 checks succeeded (4214ms)._

    ```json
    {
      "schema_version": "1.0",
      "schema_epoch": "2026-05-25",
      "tool": "log10x_retriever_probe",
      "generated_at": "2026-06-05T12:00:00.000Z",
      "view": "summary",
      "summary": {
        "headline": "Retriever end-to-end health check passed. Picked the highest-volume pattern, ran query qr-7c12, all 8 checks succeeded (4214ms)."
      },
      "data": {
        "verdict": "green",
        "picked_hash": "3f8a1b2c4d5e6f70",
        "query_id": "qr-7c12",
        "asserts": [
          {
            "name": "offload_bucket_has_recent_data",
            "pass": true,
            "observed": "12 object(s) modified in last 5 min in s3://log10x-offload/"
          },
          {
            "name": "indexer_pipeline_running",
            "pass": true,
            "observed": "indexer-pipeline start line observed 3 time(s) in last 60s"
          },
          {
            "name": "sqs_queues_drained",
            "pass": true,
            "observed": "2 queue(s) checked, max depth 0"
          },
          {
            "name": "retriever_pod_ready",
            "pass": true,
            "observed": "pod retriever-10x-abc: 2/2 containers ready"
          },
          {
            "name": "cw_scan_match",
            "pass": true,
            "observed": "cw scan complete events for qr-7c12: 1 line(s), total matched=42"
          },
          {
            "name": "cw_stream_fetch",
            "pass": true,
            "observed": "cw stream worker completion lines for qr-7c12: 1"
          },
          {
            "name": "s3_qr_jsonl_written",
            "pass": true,
            "observed": "1 jsonl file(s) under s3://log10x-results/indexing-results/tenx/app/qr/qr-7c12/"
          },
          {
            "name": "mcp_events_returned",
            "pass": true,
            "observed": "mcp eventsMatched=42, eventsReturned=1"
          }
        ],
        "total_runtime_ms": 4214
      },
      "actions": [],
      "truncated": false,
      "warnings": []
    }
    ```

??? tenx-output-schema "Output schema"

    The `data` block inside the [StructuredOutput envelope](../index.md#json-by-default-output):

    ```typescript
    interface ToolData {
      verdict: 'green' | 'broken' | 'unknown';
      picked_hash?: string;
      query_id?: string;
      asserts: Array<{
        name: string;
        pass: boolean;
        observed: string;
        remedy?: string;
      }>;
      first_failed_assert?: string;
      surfaced_remedy?: string;
      total_runtime_ms: number;
      reason?: string;
    }
    ```

    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).