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
• 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 matched by the engine's 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