Engine PR
The unified per-pattern action-plan PR author. Derives a per-pattern policy from live Prometheus metrics using a greedy solver ordered by volume × severity weight, then renders the cap CSV and opens a gh pr create command against the customer GitOps repo. The engine hot-reloads the CSV on the next gitops poll, with no restart and no event drops.
Two modes:
- configure (default): derive a fresh policy and open a PR
- refresh: re-pull TSDB metrics for a deployed policy, compare observed volume to the cap-CSV preamble baseline, and open a delta PR only when volume has drifted beyond
tolerance_pct
Absorbs the former configure_compact and configure_regulator tools into a single unified interface with a 6-action vocabulary (pass / sample / compact / tier_down / offload / drop).
Example
You
cut payment-svc by 40%
Log10x
Plan for payment-svc (23 patterns, 1 container). The 40% target was the goal; the per-pattern plan delivers more.
Current: 45.3 GB/mo · Delivered: 32.1 GB/mo shed (70.9%) · Floor patterns: 2 (audit/dashboard kept)
PR command ready:
More to ask
- "configure payment-svc at 30% target, protect audit logs"
- "refresh the policy for checkout-svc"
- "budget-based: cap payment-svc at $150/month"
Prerequisites
Reporter deployed for metrics. GitOps repo configured (gitops_repo arg or gitops.repo in ~/.log10x/envs.json). Destination SIEM (auto-detected from active env or discover_env snapshot).
Schema and samples
Input schema
Agent-facing JSON Schema (the canonical shape the MCP server publishes via tools/list):
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"configure",
"refresh"
],
"default": "configure",
"description": "`configure` (default) = derive a fresh per-pattern policy and open a PR. `refresh` = re-pull TSDB metrics for an already-deployed policy, compare observed volume to the cap-CSV preamble baseline, and open a delta PR only when the volume has drifted beyond `tolerance_pct`. Use `refresh` from cron/agent loops after the engine is live and 10x metrics are flowing. Requires `current_csv` carrying the prior `# target_percent=N` preamble; if absent, falls back to `target_percent` arg or returns target_resolution."
},
"tolerance_pct": {
"type": "number",
"minimum": 0,
"maximum": 50,
"description": "Refresh-mode tolerance band. When observed monthly volume drifts less than this percent vs the cap-CSV baseline, no PR is emitted (phase=refresh_skipped). Default 2%. Ignored in `configure` mode."
},
"service": {
"type": "string",
"description": "Customer-vocabulary name of the service to configure (e.g., `payment-service`). The tool resolves this to a set of `k8s_container` values via Prometheus and asks the agent to confirm if multiple candidates match."
},
"containers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Explicit list of k8s_container values to apply the policy to. If omitted, the tool resolves `service` to candidates and presents them; the agent re-calls with this parameter to commit."
},
"target_percent": {
"type": "number",
"minimum": 1,
"maximum": 95,
"description": "Reduce monthly volume bytes by this percent. Exactly one of `target_percent` or `budget_usd` is required."
},
"budget_usd": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Cap monthly destination spend at this dollar amount. Tool back-computes the equivalent `target_percent` from current spend at the destination ingest rate. Exactly one of `target_percent` or `budget_usd` is required."
},
"destination": {
"type": "string",
"enum": [
"splunk",
"datadog",
"elasticsearch",
"clickhouse",
"cloudwatch",
"azure-monitor",
"gcp-logging",
"sumo"
],
"description": "Destination SIEM. Auto-detected from active env / snapshot recommendations when omitted; if auto-detect fails the tool returns a structured not-configured envelope."
},
"es_pruned": {
"type": "boolean",
"description": "Elasticsearch only: are compactable fields excluded from `_source` via index template? Default `false` (unpruned). Auto-detection requires reading the customer index template; this knob is the explicit override. See OPEN Q 2 in the 14d-24 spec."
},
"contract_type": {
"type": "string",
"enum": [
"committed",
"on_demand"
],
"default": "on_demand",
"description": "`committed` = customer is on a committed-volume tier (Splunk, Datadog DPM) where savings count toward renewal forecasting. `on_demand` = pay-as-you-go."
},
"signal_floor": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pattern_hash": {
"type": "string",
"description": "Stable pattern identity (tenx_hash) to protect from any reduction."
},
"reason": {
"type": "string",
"description": "Human-readable rationale (e.g. `dashboard:payments-overview`)."
},
"events_per_min_per_pod": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Optional minimum throughput floor; solver will not sample/drop this pattern below this rate."
}
},
"required": [
"pattern_hash"
],
"additionalProperties": false
},
"default": [],
"description": "Patterns the solver MUST keep above floor (action=pass). First match wins. Use for dashboards, alerts, audit logs."
},
"action_defaults": {
"type": "object",
"properties": {
"standard": {
"type": "string",
"enum": [
"pass",
"sample",
"compact",
"tier_down",
"offload",
"drop"
],
"default": "compact",
"description": "Default action for standard-tier patterns (the bulk of volume)."
},
"debug": {
"type": "string",
"enum": [
"pass",
"sample",
"compact",
"tier_down",
"offload",
"drop"
],
"default": "drop",
"description": "Default action for debug-tier patterns."
},
"synthetic": {
"type": "string",
"enum": [
"pass",
"sample",
"compact",
"tier_down",
"offload",
"drop"
],
"default": "drop",
"description": "Default action for synthetic / load-gen patterns."
}
},
"additionalProperties": false,
"default": {},
"description": "Tier-to-action defaults. Audit-tier is always `pass`; error-tier is always `sample(N=2)`."
},
"reduction": {
"type": "string",
"enum": [
"soft",
"hard"
],
"default": "hard",
"description": "`soft` = mark for SIEM-side tier-down (lossless, recoverable). `hard` = drop at the receiver (gone). Soft is only meaningful on destinations that support a marker-driven tier (Splunk via `_raw` marker, ES via index-time routing)."
},
"observationDays": {
"type": "integer",
"minimum": 1,
"maximum": 90,
"default": 7,
"description": "Days of Prometheus history used to compute per-pattern volume. Default 7 (captures a full weekday/weekend cycle)."
},
"snapshot_id": {
"type": "string",
"description": "ID returned by `log10x_discover_env`. Used to resolve `gitops_repo`, `lookup_path`, and `destination` defaults."
},
"gitops_repo": {
"type": "string",
"description": "Owner/name of the customer gitops repo (e.g. `acme/log10x-config`). Falls back to `gitops.repo` in `~/.log10x/envs.json` if omitted."
},
"gitops_branch": {
"type": "string",
"default": "main",
"description": "Base branch for the PR. Default `main`."
},
"lookup_path": {
"type": "string",
"default": "pipelines/run/receive/rate/caps.csv",
"description": "Repo-relative path to the cap CSV. Default `pipelines/run/receive/rate/caps.csv`."
},
"current_csv": {
"type": "string",
"description": "Existing CSV content (header + rows). If omitted, the tool computes the diff against an empty baseline and notes that."
},
"from_poc_id": {
"type": "string",
"description": "POC snapshot id returned by `log10x_poc_from_siem_submit` (or the from-local equivalent). When set and the snapshot carries a `cap_csv` (i.e., the POC was run with `target_percent_reduction`), the tool reads that CSV verbatim and renders it as the PR body, with no Prometheus pull and no greedy re-derivation. Falls back to the live-Prometheus derivation when the snapshot has no cap_csv (or no `target_percent_reduction` was supplied to the POC)."
},
"auto_apply": {
"type": "boolean",
"default": true,
"description": "When `true` (default), the tool shells out to `gh` to create the PR after rendering. When `false`, returns the gh script verbatim for the agent/user to run. Industry-standard MCPs (GitHub, Linear, Atlassian) auto-execute write tools by default; the safety boundary is the MCP client approval UX plus the gh CLI token. Forced `false` whenever `read_only=true`."
},
"read_only": {
"type": "boolean",
"default": false,
"description": "When `true`, behaves as if `auto_apply=false` regardless of other flags. Use for evaluation, audit, or in MCP contexts without an approval surface (cron, headless agents). Mirrors `github/github-mcp-server --read-only`."
},
"delivery": {
"type": "string",
"enum": [
"gitops",
"kubectl_configmap",
"stdout_only",
"auto"
],
"default": "auto",
"description": "Which writer delivers the rendered action-intent + cap CSV. `gitops` opens a PR via gh (slow review loop, safest). `kubectl_configmap` applies a ConfigMap directly to the receiver namespace (fast iteration, requires kubectl access). `stdout_only` returns the rendered files in the envelope without writing. `auto` (default) picks based on snapshot: gitops if `gitops.repo` is known; else kubectl_configmap if a cluster was probed; else stdout_only."
},
"delivery_namespace": {
"type": "string",
"description": "kubectl_configmap delivery only: target k8s namespace for the ConfigMap. Defaults to the receiver pod namespace discovered in the snapshot (typically `demo` or `otel-demo`). Falls back to `default` when no snapshot."
},
"delivery_configmap": {
"type": "string",
"default": "log10x-action-intent",
"description": "kubectl_configmap delivery only: name of the ConfigMap to write. The engine's ConfigMap pull source reads this name in the receiver namespace. Default matches the canonical name the engine expects."
},
"view": {
"type": "string",
"enum": [
"summary",
"detail",
"pr_command_only"
],
"default": "summary",
"description": "Response shape. `summary` (default) returns a slim payload (~under 8K tokens for a 119-pattern policy): phase, target_percent, action_mix counts, the `totals` block (bytes_in / bytes_saved / dollars_saved monthly), the top-5 cost contributors, and a short PR-command prose summary. `detail` returns the full envelope with `pr_command`, `per_pattern_rows`, and `csv_diff` inlined. `pr_command_only` returns just the `gh pr create` string for copy-paste callers."
}
},
"required": [
"service"
],
"additionalProperties": false
}
Source: src/tools/configure-engine.ts.
The data block inside the StructuredOutput envelope. The shape below is the default view='summary' payload; view='detail' inlines pr_command, the full per_pattern_rows, and csv_diff.
interface ToolData {
ok: boolean;
phase: 'target_resolution' | 'backend' | 'resolution_prompt' | 'solver_failed' | 'pr_rendered' | 'refresh_skipped';
service: string;
containers: string[];
destination?: string;
target_percent?: number;
action_mix?: Record<string, number>; // count of patterns per action
// Delivered savings: the solver's ACTUAL projected shed, summed from
// per_pattern_rows. Reconciles with the per-pattern breakdown by
// construction and never exceeds current spend. `pass` rows shed
// nothing, so they contribute zero. Dollars are priced at the
// resolved customer rate (LOG10X_ANALYZER_COST / envs.json
// analyzerCost / ingestPerGb), not destination list price.
totals?: {
bytes_in_monthly: number;
bytes_saved_monthly: number;
dollars_saved_monthly: number;
};
derivation?: {
current_monthly_bytes: number;
current_monthly_usd: number;
// The flat target (current - target%). This is the GOAL, distinct
// from what the plan delivers (totals.*_saved_monthly). The greedy
// solver may overshoot or fall short of this line.
target_monthly_bytes: number;
target_monthly_usd: number;
floor_count: number;
actions_used: Record<string, number>;
};
top_5_per_pattern?: Array<{
pattern_hash: string;
descriptor: string;
action: string;
bytes_share_pct: number;
}>;
// Full per-pattern table (view='detail' only).
per_pattern_rows?: Array<{
pattern_hash: string;
current_bytes_30d: number;
cap_bytes_per_window: number;
action: string;
// Actual shed for THIS pattern under its assigned action; 0 for
// `pass` by construction (and 0 bytes for `tier_down`, which sheds
// no on-wire bytes). These sum into totals.*_saved_monthly.
saved_bytes_monthly: number;
saved_dollars_monthly: number;
projected_monthly_usd_low: number;
projected_monthly_usd_expected: number;
projected_monthly_usd_high: number;
floor_reason?: string;
reason: string;
}>;
checks?: { coverage_pct: number; feasible: boolean; blocking: string[]; warnings: string[] };
pr_command_summary?: string; // prose; full gh script via view='detail'
csv_diff?: string; // view='detail' only
pr_command?: string | null; // view='detail' / view='pr_command_only'
applied?: { ok: boolean; pr_url?: string; branch?: string; error?: string };
human_summary: string;
}
Envelope-level fields the agent should also read: summary.headline, actions[], schema_epoch.
The headline reports delivered savings (the solver's actual shed from totals), not the flat target. It reconciles with the per-pattern breakdown and never exceeds current spend. The flat current - target% line stays in derivation.target_monthly_* as the GOAL, clearly distinct from what the plan delivers.