Log10x MCP

Identify patterns where one slot value dominates the field (>= 60% of events by default). Surfaces sampling opportunities: "slot `verb` is `get` 78% of events, sample the get case at 1/10 to cut its volume." Sampling is lossy: the other 9 in 10 of those events are discarded. Differentiated against analyzer field histograms because the engine groups by per-pattern field-set, so dominance is measured within the structural pattern, not globally. **Stage 1**: accepts events as a paste array (same shape as log10x_resolve_batch). **Calibration**: the 60% concentration floor and 1/10 sampling rate are hand-picked defaults tagged `unvalidated_default` in the output. The envelope surfaces the empirical `observed_dominant_pct_distribution` across all candidate slots so the agent can judge whether 0.6 is well above or below the noise floor for this dataset. See `docs/cross-pillar-primitives.md` for the agent behavior contract.

Single-call root-cause investigation for any log line, pattern, service, or environment. Returns a complete causal chain (for acute spikes) or co-drifter cohort (for gradual drift) with confidence scores derived mechanically from data signal quality, plus ready-to-run verification commands. Per-pattern blocks include `offload_status` (pass / sample / compact / drop) so the narrative reflects whether the receiver is admitting or dropping the implicated patterns, matching `top_patterns` and `pattern_trend`. Call whenever the user asks 'what is going on with X', 'why is X spiking', 'investigate X', or pastes a log line / alert and asks for diagnosis. Input is the user's natural-language target: pass their words verbatim. The tool detects whether the input is a raw log line, pattern identity, service name, or 'environment' and runs the appropriate flow. It also detects whether the trajectory is acute or gradual drift and renders a different report shape for each. Confidence percentages decompose into named sub-scores (stat × lag × chain for acute; slope_sig × cohort for drift): walk the user through the decomposition when asked. Show the entire markdown report to the user without modification.

List the user's Log10x ACCOUNT environments and report credential / login state. **Call this, and ONLY this, for any of these phrasings**: 'which Log10x environments do I have', 'which environments are available to me', 'list my envs', 'what tenants/accounts can I query', 'am I logged in', 'switch envs'. **For 'log me in' / 'sign me up' / 'create a Log10x account' / 'use my real account'**: call `log10x_signin_start` (browser Auth0 device flow; the model chains to `log10x_signin_complete` automatically), or call `log10x_signin_complete` directly with `{ api_key: "<key>" }` if the user already has a key. **Do NOT call `log10x_discover_env` for these questions**: that tool scans the user's Kubernetes/AWS infrastructure, unrelated to Log10x account environments. In demo mode (no key set, or key failed validation), the response is a step-by-step config guide. In signed-in mode, lists the user's identity, every env they can reach with permissions (OWNER/WRITE/READ), the default env, and the most-recently used env this session. Read-only, takes no args.

Measure per-pattern compact ratios (bytes before and after encoding) on a sample pulled from the customer's SIEM and run through a local engine; a ratio on that sample, not a SIEM meter reading. Pulls `sample_size` events for a service over `timeRange`, runs them through the local tenx engine, and returns per-pattern `compaction_ratio_x` (original bytes / encoded bytes) derived from that sample. Use this to replace the destination's default compact ratio in `log10x_estimate_savings` (one measured capture per destination, named in `compact_ratio_basis`) with ratios measured on this customer's sample. Requires: tenx CLI installed locally (LOG10X_TENX_PATH or `tenx` on PATH) AND SIEM credentials (same as `log10x_poc_from_siem_submit`). Confidence tiers: high (>=50 events), medium (10-49), low (<10). Results flow into `log10x_estimate_savings` to improve savings projections. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker.

Third step of cross-pillar investigation: return aligned anchor + candidate timeseries plus deterministic facts (`peak_at`, `peak_offset_seconds`, `n_buckets_aligned`). No Pearson, no tier: pure raw data for the agent to interpret. Use this once `log10x_rank_by_shape_similarity` has narrowed to a single suspect, or to manually verify any anchor/candidate pair side-by-side. Bucket size auto-selected from window length; both series are right-aligned to the same trailing bucket grid so a sparse anchor and dense candidate compare on the same chaos window.

First step of cross-pillar investigation: deterministic filter on which customer metrics moved while an anchor was active. Anchor is either a Log10x pattern (`anchor_type: "log10x_pattern"`) OR a customer metric expression (`anchor_type: "customer_metric"`); candidates are all sibling series from the OTHER pillar. Partitions the anchor's window into high-phase / low-phase buckets by median rate and keeps only candidates whose mean value differs ≥15% between the two phases. Returns `moved[]`, `not_moved[]`, `evaluation_failed[]`: no Pearson, no tier, no causal framing. This is the cheap deterministic cut that pares the candidate set before the more expensive shape-similarity pass. Compose with `log10x_rank_by_shape_similarity` and `log10x_metric_overlay`.

The contents view of the customer-owned offload S3 bucket: per-pattern bytes, event count, time-first-seen, time-last-seen, and growth rate. Filtered to action=offload via the cap-CSV the MCP wrote (`drop` patterns are NOT in S3; `compact` and `tier_down` route elsewhere). Call this as the maintenance-loop review: "what's accumulating in my overflow queue?" Routes the agent to log10x_retriever_query to fetch the offloaded events when an incident or audit needs them.

CALL THIS AFTER log10x_preview_filter when the user drills into a specific pattern by number. Returns a full single-pattern view: 24h line chart (up to 12 rows, 72 chars wide), ASCII horizontal bar chart for cross-service byte distribution (top 8 services), severity breakdown, and up to 5 sample events truncated to 120 chars each. Requires pattern_hash (tenx_hash from preview_filter.data.patterns[].tenx_hash). must_ask_user: Back to preview list, or Apply with this in the picture. actions[]: log10x_preview_filter (back) and log10x_configure_engine (apply).

Compare which log patterns are new, gone, persistent or back again between two adjacent time windows. Compares pattern presence in two windows (the most recent `timeRange` window as "after" vs the immediately preceding `timeRange` window as "before") and returns four sets: `new` (present after, absent before), `retired` (present before, absent after), `persistent` (present in both), and `re_emerged` (flagged as new but existed prior to the before-window, the "the bug we thought we fixed is back" case, derived by checking first_seen against the before-window boundary). Plus `co_emergence_clusters`: groups of 3+ patterns whose first_seen timestamps cluster within ±co_emergence_window_seconds (default 60s). That cluster is a deploy fingerprint: no CI/CD integration required; the agent can then query the customer's deploy system externally with the cluster timestamp. The two windows compare because a pattern's hash comes from the line, the symbol library and the engine configuration, not from what a query saw: under the same engine, library and configuration the same line carries the same hash in both windows. Use for "what changed since last deploy", "which patterns disappeared this week", "did the rollback bring back the old errors", or paired with log10x_pattern_examples on a flagged hash to see slot distribution. Scoping: `service` and `severity` narrow the universe; `limit` caps rows per category. Returns structured envelope under `data.diff` with the four sets plus an `incidents` block when co_emergence clusters are detected. An engine upgrade that changes the naming rules renames the patterns it affects once: across that boundary they show as `new` and their old names as `retired`, and the frequent ones form a co-emergence cluster at the upgrade time.

Pull recent live events for a pattern from the customer's log analyzer (Splunk, Datadog, Elasticsearch, CloudWatch) and return them grouped by templateHash with template-extracted slot values per match. **Bounded to a 24-hour window** (live log analyzer retention); for older history use `log10x_retriever_query`. Input is either a Symbol Message (pattern name like `Payment_Gateway_Timeout`) or a pasted raw log line; pasted lines resolve via the same templater path as `log10x_resolve_batch`. The tool runs a SIEM phrase-search probe, runs returned events through the local templater, groups by templateHash (one bucket per template variant of the pattern; each bucket carries the pattern hash, `tenx_hash`), applies a content-token Jaccard similarity threshold (≥0.85) to discriminate the matching pattern's events from look-alikes, and returns the top buckets by event count. Output marks partial extractions: per-bucket templateHash labels, recall counts, and explicit `parseFailed` markers when slot extraction fails. Multi-line group templates report head-line-only with an explicit warning. **Designed as an orchestration primitive** called by `log10x_investigate` when the chain needs concrete event evidence after a metric-tier identification. Direct user-facing use is fine but rare; prefer `log10x_event_lookup` + `log10x_pattern_trend` for single-line inspection.

[FRESH-SESSION ROUTING: if this is the user first cost question of the session, call log10x_start first instead, it returns the orientation menu the user needs before any per-tool action.] Given one pattern (symbolMessage identity or tenx_hash), return the env-gated CAPABILITY MENU of which mitigation paths are reachable: drop_at_analyzer, drop_at_forwarder, mute_at_10x, compact_at_10x. Each option carries `enabled` (true/false), `label`, and `disabled_reason` when not reachable. This is a REACHABILITY-FIRST router: it answers "which of the four tiers can I use right now given my env wiring", NOT "how much would each save". Per-option estimated savings (% reduction, $/mo) and paste-ready config snippets are surfaced by the next-tool chain (log10x_cost_options for the action menu, then the specific action tool for the snippet): NOT this envelope. The agent surfaces the menu to the user; the user picks; chain to log10x_cost_options for the action-level breakdown. **Action-shaped tool: calibration honesty**: the envelope's `recommendation_basis` tells the agent WHERE the capability detection came from (envs.json, snapshot, env vars, or unknown). `recommendation_audit.capability_sources` carries the per-field source, and `snapshot_age_seconds` carries snapshot staleness. The agent SHOULD NOT auto-route to the chosen sub-tool until the user picks an option, and SHOULD verify the basis before treating capability detection as authoritative (e.g., a stale snapshot may mis-flag mute as enabled when the receiver was uninstalled). See `docs/cross-pillar-primitives.md` for the agent behavior contract. **Call this** when a previous tool surfaced a high-cost pattern and the user asks 'what should I do' / 'how do I drop this' / 'how do I reduce this'.

Return the volume history for a single pattern over a chosen window (e.g. 1h, 24h, 7d, 30d), with a sparkline and spike detection: ranked by byte volume (with cost overlay when $/GB is set). **Call this after log10x_event_lookup** when the user asks "is this getting worse", "has it been louder before", "when did it start", or wants temporal context on a pattern surfaced in an earlier step. Always state the observation window explicitly in the reply: "flat at 2/h for the last 6 months of observation, spiked at 13:58 today", and never claim history older than the window. Pass `include` to select the cohort: `kept` (default), `dropped` (offloaded-only trend, useful for "is the receiver dropping more of this lately"), or `both` (total ingest). The envelope reports which cohort the series represents so the agent never conflates kept-only with total volume.

Run a log-cost-optimization POC entirely from local log sources: pass `path` for one log file (wrapper-normalized) or `paths` for files, directories and globs; `kubectl` samples pod logs; `docker` and `journald` to follow. No log-analyzer credentials required. Use when the prospect has no SIEM connection or has not yet shared API keys. Returns a synchronous markdown report with: (a) **sample composition** table, top-N pods by byte volume; the prospect must confirm the sample looks like their production mix, (b) **industry-pricing matrix**, projected savings at Datadog / Splunk / CloudWatch / Sumo / Elastic / OpenSearch list prices, NOT a prediction of any specific bill, (c) **top patterns** in the kubectl-sourced sample. For native exclusion configs, paste-ready Receiver YAML, and the full 9-section report tied to a specific log analyzer's GB-billed volume, run `log10x_poc_from_siem_submit` once credentials are available. **No automatic fallthrough**: this tool is invoked explicitly. If `log10x_poc_from_siem_submit` failed on missing credentials, the calling LLM should ask the user before re-invoking with this tool: local-source framing differs from SIEM-attached framing and silent fallthrough would be a bait-and-switch. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker. No log-analyzer credentials and no deployment are needed, but without an engine this returns an error rather than a report. Pass target_percent_reduction as a whole-number percent (e.g. 40 for 40%) to get a feasibility verdict against that target. **Two modes, and the agent should name whichever the user's phrasing invites.** Run normally, this tool reads local files but the server around it still has network. Run inside the FENCED profile (`TENX_AIRGAPPED=true`, `--network none`, the `log10x/poc` image) it is the same analysis with no network at all, and its output carries its own `docker inspect` proof. `log10x_emit_sample_plan` produces the sample for that…

Retrieve progress or a view of the report from a log10x_poc_from_siem_submit run. Pass `snapshot_id`; optionally `view` to select the level of detail. **In-progress** responses report status (pulling / templatizing / rendering), progress_pct, step_detail, and elapsed_seconds: poll every ~30s until done. **Complete** responses render one of six views: `summary` (default, ~30 lines, exec banner + top-5 wins + views CTA), `full` (complete 9-section report, ~300 lines), `yaml` (paste-ready Receiver mute-file for the top N patterns), `configs` (native SIEM exclusion configs, Datadog exclusion filter / Splunk props.conf / etc.), `top` (expanded N-row drivers table), `pattern` (deep-dive on one identity, requires `pattern` arg). **Failures** include partial_report_markdown when any events were successfully pulled before the error. The full report is also written to ${LOG10X_REPORT_DIR:-/tmp/log10x-reports}/poc_from_siem-<timestamp>.md regardless of which view the caller requested. Snapshots live in-memory per MCP process; a restart clears them, so persist the final report path to keep it. **Unified envelope**: response carries `status`, `query_count`, `total_latency_ms`, `backend_pressure_hint`, `human_summary`, plus the existing snapshot-lifecycle fields. Errors (unknown snapshot_id, render failure) come back as `status: 'error'` with a structured `PrimitiveError` envelope. See `docs/cross-pillar-primitives.md` for the agent behavior contract. **Two modes, and the agent should name whichever the user's phrasing invites.** This tool is the NETWORKED one: it reads the analyzer directly over the network with the caller's credentials, and the MCP mints one licence. The FENCED mode runs the same POC with no network at all: `log10x_emit_sample_plan` renders a read-only export script the user runs themselves, and the analysis happens in a container started with `--network none`, so 'cannot exfiltrate' is a kernel fact the user checks with one `docker inspect` rather than a clai…

Kick off a full log-cost-optimization POC against the user's SIEM. Pulls a representative event sample, groups the events into log patterns, each with its pattern hash, and renders a 9-section markdown report covering top cost drivers, Receiver recommendations, ready-to-paste native SIEM exclusion configs, Compact mode potential, risk/dependency checks, and deployment paths. Supported SIEMs: cloudwatch (AWS CloudWatch Logs via IAM credential chain), datadog (DD_API_KEY + DD_APP_KEY), sumo (Sumo Logic), gcp-logging (GCP Cloud Logging), elasticsearch (Elastic Cloud / self-hosted), azure-monitor (Azure Monitor / Log Analytics), splunk (SPLUNK_HOST + SPLUNK_TOKEN), clickhouse (OpenObserve / SigNoz / custom schemas). Auto-detects the SIEM from env vars when `siem` omitted: explicitly pass `siem` if multiple credential sets exist. `scope` and `query` are SIEM-specific: CloudWatch (log group + filter pattern), Datadog (index + query), Sumo (_sourceCategory + query), GCP (project id + filter), Elasticsearch (index pattern + KQL), Azure (workspace id + KQL), Splunk (index + SPL), ClickHouse (database + SQL WHERE). For ClickHouse, also pass `clickhouse_table` (required) and column-mapping args for custom schemas (OpenObserve/SigNoz auto-detected). Returns a `snapshot_id`: poll via log10x_poc_from_siem_status to retrieve progress and the final report. Report is also written to `${LOG10X_REPORT_DIR:-/tmp/log10x-reports}/poc_from_siem-<timestamp>.md`. Default window is 7d, default target event count is 250k, default max pull time is 5 min: the pull stops at whichever of the two ceilings hits first. **Tier prerequisites**: none. No log10x API key required. **Templating defaults to privacy_mode=true**: events are templated by a local Log10x engine, either a native `tenx` CLI (install for macOS/Linux/Windows: https://doc.log10x.com/install/) or a local Docker container (set `LOG10X_TENX_MODE=docker`, auto-detected and preferred when the mode is unset), and never leave the machine.…

CALL THIS AFTER log10x_explain_mode when the user picks Preview. Shows the list of patterns that would be affected by applying a given enforcement mode to a service, before any action is taken. Returns a fixed-width plain-text table (no markdown pipes) with columns: rank, descriptor, volume, %, service, severity, first seen, trend sparkline. Writes a CSV to /tmp/log10x-preview-<mode>-<service>.csv. must_ask_user offers: drill into pattern #N (calls log10x_pattern_detail), Apply, or go back to pick a different mode. forbidden_next_actions locks log10x_configure_engine, log10x_pattern_mitigate, and log10x_advise_retriever until the user commits.

Answer Log10x product questions from the docs that ship inside the MCP build (chunked + indexed at install time). Use whenever the user asks a factual product question: "what is the Receiver", "how is pattern_hash computed", "what data leaves my network", "does the Reporter modify data", instead of answering from training data. Inputs: `topic` for an exact docs-slug lookup (e.g. `faq/security/data-protection`), or `query` for natural-language TF-IDF search across those docs. `category` narrows search to one of faq / apps / engine / api / config / manage. `max_results` caps the result count (default 3). Output is a standard chassis envelope with `found`, ranked `results` (each carrying matched chunks + canonical_url), and `similar_topics` as a did-you-mean fallback. Link the `canonical_url` of each result used in the answer. The docs are shipped from `config/mksite/docs` at build time; in development the loader also honors `LOG10X_PRODUCT_KB_PATH`.

Second step of cross-pillar investigation: Pearson correlation + signed lag on a pre-filtered candidate set (typically the `moved[]` output of `log10x_metrics_that_moved`). Returns per-candidate: `pearson_magnitude`, `pearson_signed` (direction preserved), `lag_seconds` (signed: negative = candidate leads anchor, positive = candidate lags), `lag_at_bound` (flag: peak landed at search-window boundary), `lag_tightness` (how sharply the Pearson surface peaks), `anchor_phase_gap`, `anchor_phase_aligned` (flag: candidate value differs ≥15% between anchor's high-phase and low-phase buckets), `n_buckets`. No tier, no causal label: the agent reads the flags and decides. Compose with `log10x_metric_overlay` for the final per-candidate aligned-timeseries view.

Templatize a batch of log events and return per-pattern triage. **This is one of two tools that run a local Log10x pipeline on the user's machine** (the other is `log10x_extract_templates`): call this whenever the user asks 'can you run log10x locally', 'do a local pipeline run', 'templatize these events', or supplies any batch to analyze (Datadog/Splunk/Elastic query results, Slack incident attachments, kubectl logs, raw text). Does NOT need Kubernetes, a deployed Reporter, or a Log10x account: the pipeline runs in-process on the host. Output structures the batch by a paste-local templateHash with per-pattern frequency + severity + full template structure + per-slot variable distribution. Each top pattern carries `actions[]` chaining to `log10x_investigate` (historical correlation) and `log10x_retriever_query` (offload retrieval). Do NOT call for single-line resolution: use `log10x_event_lookup` for that. REQUIRES a local engine: the tenx binary on PATH, or Docker with LOG10X_TENX_MODE=docker.

End-to-end probe of the deployed Retriever chain. Fires a synthetic query at the picked top-volume tenx_hash (or an explicit target_hash) and asserts every stage in order: offload bucket has recent data, indexer pipeline is running (kubectl logs grep for 'starting pipeline - Tenx: @/apps/retriever/index'), SQS subquery + stream queues drained (depth ≤ 10), retriever pod containers all ready, then submits the query and asserts CloudWatch scan complete events have matched>0, CloudWatch stream worker complete events exist, S3 qr/<queryId>/*.jsonl files were written, and the MCP returned events_matched>0 AND events_returned>0. Returns a structured verdict (green / broken / unknown) with per-assert observed + remedy. Call this as the post-install verify step (chained from log10x_advise_retriever step_verify) OR as a deep doctor diagnostic when log10x_retriever_query returns 0 events and the cause is unclear. Catches the silent-failure shapes that take hours to debug manually: indexer not booted, stream pipeline launch failures, IRSA s3:PutObject misconfigured, MCP input_bucket misaligned with engine write location.

Fetch offloaded log events from the customer's own S3 bucket by pattern hash or by a variable value, reading only the byte ranges whose Bloom filters can hold a match, without a full scan. The use case: events the Receiver offloaded to the customer's S3 bucket instead of the SIEM, over any window the bucket holds. The Bloom filters cover each event's template hash and variable values. Matched events land as a list of `*.jsonl` objects in the customer's S3; the tool returns an in-context preview (capped by `limit`) PLUS `data.results_location` (the S3 bucket + prefix holding the full object set). A capable agent reads those objects directly to answer, or hands the S3 object list to the customer's own S3-to-SIEM path. No re-ingestion pipeline, no proprietary format. The envelope additionally carries per-pattern `offload_status` so retrieval results agree with the live metric-surface disposition (pass / sample / compact / drop) without a second tool call. Call for: offloaded events of a pattern; events filtered by a variable value that is not a faceted SIEM dimension (e.g. 'all payment_retry events for customer acme-corp 90 days ago'); compliance / audit / forensic exact retrieval; confirming what the Receiver offloaded for a given pattern. Optional JavaScript `filters` refine over payloads after the Bloom-scoped fetch. For a time-bucketed series instead of raw events, use `log10x_retriever_series`. The envelope carries by_severity / by_service / by_day rollups with a rollup_basis provenance stamp (qrs_summaries = whole-match from engine summaries; events_capped = derived from the capped download).

Post-hoc diagnostic surface for a specific retriever query, addressed by `queryId` (returned from `log10x_retriever_query` or recovered from the S3 results prefix). Pulls the coordinator's `_DONE.json` stats (scanned / matched / streamRequests / streamBlobs / submittedTasks / expectedMarkers), counts per-worker byte-count markers under `q/<queryId>/`, lists result JSONL files under `qr/<queryId>/`, optionally filters CloudWatch events from the `queryLogGroup` for the queryId substring (when the chart's `queryLogGroup` is configured), and runs a diagnostics engine that classifies the run into states like `dispatcher_failure` (scanned=0 with submittedTasks>0), `results_not_uploaded`, or `observability_disabled`. When pod logs are reachable from the MCP host, fetches a tail and greps for the `cloud/streamer/subquery` include-resolution signature to confirm the dispatcher-failure category. Call this whenever `log10x_retriever_query` returns 0 events but the wall-clock implies scan work, or whenever an offline post-mortem needs the structured timeline for a specific queryId. Pass fetch_results: true to ALSO recover the completed results from S3 (10-event preview + counts + results_location) after a partial or timed-out query, without resubmitting.

Materialize a fidelity-aware time series from the customer's S3 offload bucket over an arbitrary window, with optional group-by on enrichment fields. Auto-selects between exact full aggregation (Strategy A) and per-window-sampled fan-out (Strategy B) based on Reporter pattern volume: small/moderate-volume queries get exact counts; high-volume / long-window queries get a sampled series with time-distribution + group-ranking fidelity preserved and tail caveats reported. Pathological volume is refused with structured narrowing guidance, never silently truncated. Call when: (a) the user wants a 'rate of pattern X over the last 30 days, broken down by tenant' answer that exceeds SIEM retention/budget, (b) a baseline needs building from cost-driver patterns where Prometheus has continuous metrics but the *grouped breakdown* lives only in the offload bucket. Use `log10x_retriever_query` instead for the event payloads (not aggregates).