Investigate

When an alert fires, a pattern is misbehaving, or you're auditing the env for drift, get the named cause in one tool call instead of stitching three dashboards. Returns the onset time, the cause with supporting evidence, the metrics and patterns that moved with it, and the kubectl / curl / PromQL commands to verify.

Example

You

spike on payments-svc — root cause?

Log10x

Onset: 14:30 today. Payment_Gateway_Timeout jumped 200/min → 45,000/min.

Cause: CPU spike on db-replica-2 matched the onset (r=0.94). What moved with it: db.replica.cpu, apm.payments.latency, kafka.consumer.lag.

Verify: kubectl describe pod db-replica-2

More to ask

• "why is Retry_Backoff_Exhausted firing?"
• "slow drift in checkout-svc, last 30 days"
• "full environment audit, last 30 days"

Prerequisites

This tool requires the Reporter deployed. Slow-drift investigations need continuous historical metrics, which CLI-only mode doesn't produce.

Schema and samples

Input example

Real call against the demo env (captured by scripts/capture-tool-envelopes.mjs).

{
  "starting_point": "otel-collector",
  "window": "1h",
  "depth": "shallow",
  "view": "summary"
}

Input schema

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

{
  "type": "object",
  "properties": {
    "starting_point": {
      "type": "string",
      "description": "The user's target, verbatim. Can be a raw log line, a pattern identity (symbolMessage or tenx_hash), a service name, or the literal string \"environment\"/\"all\"/\"audit\". The tool detects the mode automatically."
    },
    "window": {
      "type": "string",
      "default": "1h",
      "description": "Analysis window. `1h` default for acute-spike cases; `30d` recommended for drift cases. Accepts any PromQL-style duration string (`15m`, `1h`, `6h`, `24h`, `7d`). Alias: `timeRange`."
    },
    "timeRange": {
      "type": "string",
      "description": "Alias for `window` for consistency with other Log10x tools. If both are set, `window` wins."
    },
    "baseline_offset": {
      "type": "string",
      "description": "Offset for the baseline comparison. Defaults to `24h` for short windows (acute-spike cases) and to the same value as `window` for long windows (≥7d, drift cases). Override only if you need a non-standard comparison."
    },
    "depth": {
      "type": "string",
      "enum": [
        "shallow",
        "normal",
        "deep"
      ],
      "default": "normal",
      "description": "`shallow`: anchor service only. `normal` (default): anchor service + immediate dependencies. `deep`: full environment-wide."
    },
    "environment": {
      "type": "string",
      "description": "Environment nickname — required in multi-env setups."
    },
    "use_bytes": {
      "type": "boolean",
      "default": false,
      "description": "Use byte-based rate instead of event-count. Event-count is strongly preferred; use only if the Reporter does not emit the count metric."
    }
  },
  "required": [
    "starting_point"
  ],
  "additionalProperties": false
}

Source: src/tools/investigate.ts.

Output example

Real envelope from the demo env. view: "summary" returns the full StructuredOutput with typed data. Long arrays + base64 PNG bodies trimmed for readability; the real call returns them in full.

Headline (the 1-line agent-facing answer):

Investigation of "otel-collector" (window=1h): shape=unknown.

{
  "schema_version": "1.0",
  "schema_epoch": "2026-05-25",
  "tool": "log10x_investigate",
  "generated_at": "2026-05-26T15:37:46.392Z",
  "view": "summary",
  "summary": {
    "headline": "Investigation of \"otel-collector\" (window=1h): shape=unknown."
  },
  "data": {
    "ok": true,
    "starting_point": "otel-collector",
    "window": "1h",
    "depth": "shallow",
    "use_bytes": false,
    "report_markdown": "## Investigation: otel-collector, last 1h\n\n**Investigation id**: f4c0294d-e96a-423a-b75e-643b297e830f\n**Result**: Could not resolve \"otel-collector\" to a known pattern or service.\n\n**Supported inputs**:\n- A raw log line (will be templatized and matched by structural identity)\n- A pattern identity (symbolMessage / templateHash)\n- A service name\n- The literal string `\"environment\"`, `\"all\"`, or `\"audit\"` for an env-wide sweep\n\n**Try next**:\n- `log10x_event_lookup({ pattern: 'otel-collector' })` to search by substring\n- `log10x_list_by_label({ label: 'tenx_user_service' })` to list known services"
  },
  "actions": [],
  "truncated": false,
  "warnings": []
}

Output schema

The data block inside the StructuredOutput envelope:

interface ToolData {
  ok: boolean;
  starting_point: string;
  window: string;
  depth: string;
  use_bytes: boolean;
  report_markdown: 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).

Next: Query metrics