Retriever plan
Install the Retriever once AWS infra (S3 bucket, four SQS queues, IRSA-annotated ServiceAccount) is provisioned via Terraform. Returns Helm install, verify, and teardown commands with bucket and queue URLs filled in from the snapshot. Preflight blocks before render if any AWS resource is missing and lists exactly what's not there. AWS infra is not created by this advisor; provision it via the terraform-aws-tenx-retriever module first.
Example
You
Retriever into retriever namespace
Log10x
helm upgrade --install my-retriever log10x/retriever-10x \
--namespace retriever \
--set log10x.apiKey=lx_live_... \
--set aws.inputBucket=acme-prod-logs-archive \
--set aws.irsaRoleArn=arn:aws:iam::123456:role/retriever
# Verify
kubectl -n retriever get pods -l app=my-retriever
# expect: indexer, query-handler, stream-worker all Running
aws sqs get-queue-attributes --queue-url $INDEX_QUEUE \
--attribute-names ApproximateNumberOfMessages
# expect: count drops over time as the indexer drains
aws s3 ls s3://acme-prod-logs-archive/indexing-results/ | head
# expect: index objects written within ~minutes of install
If S3, SQS, or IRSA is missing, preflight blocks before any of the above and lists exactly what's not there.
More to ask
- "override input bucket, auto-detect picked the wrong one"
- "verify probes for
my-retriever" - "teardown plan, leave AWS infra alone"
Prerequisites
A fresh snapshot_id from Discover env. AWS infra provisioned via terraform-aws-tenx-retriever (S3 bucket, four SQS queues, IRSA-annotated ServiceAccount). Preflight blocks if any is missing.
Schema and samples
Input example
Representative call (synthetic, not captured from the live demo env).
Input schema
Agent-facing JSON Schema (the canonical shape the MCP server publishes via tools/list):
{
"type": "object",
"properties": {
"snapshot_id": {
"type": "string",
"description": "ID returned by `log10x_discover_env`. The snapshot is cached for 30 min."
},
"infra_mode": {
"type": "string",
"enum": [
"terraform",
"cli",
"existing"
],
"description": "How the customer provisions AWS infra. **terraform** = emit .tf module block. **cli** = emit aws-cli commands. **existing** = infra already provisioned, wizard skips infra steps and jumps to helm values. Auto-detected as \"existing\" when the snapshot already has all four SQS URLs + IRSA."
},
"index_source_bucket": {
"type": "string",
"description": "S3 bucket for source logs (module output: index_source_bucket_name). Auto-filled from snapshot.recommendations.retrieverS3Bucket when present."
},
"index_bucket": {
"type": "string",
"description": "S3 path for indexed results (include prefix). Default: `<index_source_bucket>/indexing-results/`."
},
"iam_role_arn": {
"type": "string",
"description": "IAM role ARN for the Retriever ServiceAccount (IRSA) (module output: iam_role_arn). Auto-detected from snapshot."
},
"index_queue_url": {
"type": "string",
"description": "SQS URL for index operations (module output: index_queue_url). Auto-detected from snapshot."
},
"query_queue_url": {
"type": "string",
"description": "SQS URL for query operations (module output: query_queue_url). Auto-detected from snapshot."
},
"subquery_queue_url": {
"type": "string",
"description": "SQS URL for sub-query operations (module output: subquery_queue_url). Auto-detected from snapshot."
},
"stream_queue_url": {
"type": "string",
"description": "SQS URL for stream operations (module output: stream_queue_url). Auto-detected from snapshot."
},
"license_source": {
"type": "string",
"enum": [
"signin",
"demo",
"paste"
],
"default": "signin",
"description": "How the wizard acquires the engine license JWT. Defaults to `\"signin\"` — emits `signin_required` mode when no Auth0 session exists. Pass `\"demo\"` for a 14-day anonymous JWT. Pass `\"paste\"` with `license_jwt_paste` to supply an existing JWT."
},
"license_jwt_paste": {
"type": "string",
"description": "License JWT supplied by the user when `license_source: \"paste\"`."
},
"release_name": {
"type": "string",
"description": "Helm release name. Default: `my-retriever`."
},
"namespace": {
"type": "string",
"description": "Target namespace. Default: snapshot.recommendations.suggestedNamespace."
},
"action": {
"type": "string",
"enum": [
"install",
"verify",
"teardown",
"all"
],
"description": "Plan scope. Default: `all`."
},
"destination": {
"type": "string",
"description": "Destination SIEM for the kept slice (e.g. `datadog`, `cloudwatch`, `splunk`). Gates SIEM down-tier sub-sections in the offload markdown."
},
"step_verify": {
"type": "boolean",
"description": "Run the post-install e2e verify step. When true, the wizard skips plan emission and instead runs log10x_retriever_probe against the deployed retriever, surfacing a structured verdict (green / broken / unknown) with per-stage asserts and a remedy on the first failure. Runs independent of prior wizard state — only snapshot_id is required."
},
"install_completed": {
"type": "boolean",
"description": "Convenience trigger for step_verify. When set true on the first wizard call, equivalent to step_verify=true."
},
"target_hash": {
"type": "string",
"description": "Pre-picked tenx_hash to use for the verify step. When omitted, the probe queries the metric backend for the top-volume hash over the last 5 min."
}
},
"required": [
"snapshot_id"
],
"additionalProperties": false
}
Source: src/tools/advise-retriever.ts.
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 all plan: 4 install / 3 verify / 2 teardown, release "my-retriever" in namespace "retriever".
{
"schema_version": "1.0",
"schema_epoch": "engine-1.0.9",
"tool": "log10x_advise_retriever",
"view": "summary",
"summary": {
"headline": "retriever all plan: 4 install / 3 verify / 2 teardown, release \"my-retriever\" in namespace \"retriever\"."
},
"data": {
"mode": "plan",
"ok": true,
"app": "retriever",
"snapshot_id": "snap_01HZ9KQ7M3X8P4R2T6V0Y1B5N9",
"release_name": "my-retriever",
"namespace": "retriever",
"action": "all",
"preflight": [
{ "name": "s3-input-bucket", "status": "ok", "detail": "acme-prod-logs-archive" },
{ "name": "sqs-index-queue", "status": "ok", "detail": "tenx-retriever-index-abc123" },
{ "name": "sqs-query-queue", "status": "ok", "detail": "tenx-retriever-query-abc123" },
{ "name": "sqs-subquery-queue", "status": "ok", "detail": "tenx-retriever-subquery-abc123" },
{ "name": "sqs-stream-queue", "status": "ok", "detail": "tenx-retriever-stream-abc123" },
{ "name": "irsa-role", "status": "ok", "detail": "arn:aws:iam::123456789012:role/tenx-retriever-role" }
],
"preflight_summary": { "ok": 6, "warn": 0, "fail": 0, "unknown": 0 },
"install_step_count": 4,
"install_file_count": 1,
"install_requires_chmod": false,
"license_kind": "user-scoped",
"install_mode": "fresh-release",
"verify_probe_count": 3,
"verify_probes": [
{
"name": "pods-running",
"question": "Are the indexer, query-handler, and stream-worker pods Running?",
"commands": ["kubectl -n retriever get pods -l app=my-retriever"]
},
{
"name": "index-queue-draining",
"question": "Is the index SQS queue depth dropping?",
"commands": ["aws sqs get-queue-attributes --queue-url $INDEX_QUEUE --attribute-names ApproximateNumberOfMessages"]
},
{
"name": "index-objects-written",
"question": "Are index objects being written to S3?",
"commands": ["aws s3 ls s3://acme-prod-logs-archive/indexing-results/ | head"]
}
],
"teardown_step_count": 2,
"blockers": [],
"notes": [
"Teardown is `helm uninstall` only, AWS infra remains."
],
"has_gitops_section": false,
"human_summary": "Retriever wizard produced an all plan for release \"my-retriever\" in namespace \"retriever\". 4 install steps across 1 file, 3 verify probes. Preflight: 6 ok, 0 warn, 0 fail.",
"markdown": "# Retriever install plan\n\n..."
},
"actions": [
{ "tool": "log10x_doctor", "args": {}, "reason": "verify the install once the helm release rolls out", "role": "optional-followup" },
{ "tool": "log10x_top_patterns", "args": {}, "reason": "once events are flowing, see which patterns are offloaded to the Retriever bucket", "role": "optional-followup" }
],
"truncated": false,
"warnings": []
}
Output schema
The data block inside the StructuredOutput envelope:
interface ToolData {
// Discriminator: which wizard mode produced this envelope.
mode:
| 'plan'
| 'next_question'
| 'missing_snapshot'
| 'session_error'
| 'cancelled'
| 'license_error'
| 'signin_required'
| 'unknown_args';
// Common fields (present on most modes).
ok?: boolean;
snapshot_id?: string;
markdown?: string;
human_summary: string;
// next_question mode.
question_id?:
| 'oidc-check'
| 'infra-review'
| 'infra-mode'
| 'input-bucket'
| 'sqs-urls'
| 'irsa-role'
| 'license-paste';
shape?:
| { type: 'single-choice'; answer_field: string; choices: Array<{ value: string; label: string; recommended?: boolean; details?: string }> }
| { type: 'string'; answer_field: string; description: string; example?: string }
| { type: 'form'; description: string; fields: Array<{ name: string; type: 'string'; description: string; required: boolean; default?: string; example?: string }> }
| { type: 'info'; headline: string; resolutions: Array<{ args: Record<string, unknown>; description: string }> };
// unknown_args mode.
unknown_keys?: string[];
suggestions?: Array<{ unknown: string; did_you_mean: string | null }>;
valid_keys?: string[];
// license_error mode.
error_message?: string;
// plan mode (AdvisePlanSummary). Fields below are populated when mode === 'plan'.
app?: 'reporter' | 'receiver' | 'retriever';
release_name?: string;
namespace?: string;
forwarder?: string;
action?: 'install' | 'verify' | 'teardown' | 'all';
preflight?: Array<{ name: string; status: 'ok' | 'warn' | 'fail' | 'unknown'; detail: string }>;
preflight_summary?: { ok: number; warn: number; fail: number; unknown: number };
install_step_count?: number;
install_file_count?: number;
install_requires_chmod?: boolean;
license_kind?: 'user-scoped' | 'demo' | 'user-pasted' | 'placeholder';
install_mode?: 'upgrade-existing' | 'fresh-release';
existing_helm_release?: { name: string; namespace: string };
verify_probe_count?: number;
verify_probes?: Array<{
name: string;
question: string;
commands: string[];
expectOutput?: string;
timeoutSec?: number;
}>;
teardown_step_count?: number;
blockers?: string[];
notes?: string[];
has_gitops_section?: boolean;
}
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).