---
title: "Trend"
description: "Volume and cost history for a single pattern, with sparkline and spike detection."
icon: material/chart-line
---

After [Identify](event-lookup.md) named a pattern, ask "when did this start spiking?" or "is it getting worse?". Returns a volume and cost history over the chosen window with an inline sparkline and spike flags. History is bounded by `timeRange`; pass a bigger window to look further back.

## :material-code-braces: Example

!!! tenx-ask "You"

    when did `Payment_Gateway_Timeout` start spiking?

!!! tenx-answer "Log10x"

    $200/wk → $4.2K/wk over 14 days. Sharp spike on day 10 (8× baseline), holding steady since. Trace:

    ```
    Day 1–9:   ▁▁▁▁▁▂▁▁▂   $200/wk
    Day 10:    █          8× spike
    Day 11–14: ▆▇▇▇       $4.2K/wk steady
    ```

## :material-chat-question-outline: More to ask

- *"`Payment_Gateway_Timeout` last hour, minute by minute"*
- *"`Retry_Exhausted` over the last 30 days"*
- *"is `GetCartAsync` getting worse?"*

## :material-check-decagram-outline: Prerequisites

This tool requires the [Reporter](../../../reporter/) deployed.

## :material-code-json: Schema and samples

??? tenx-input-example "Input example"

    Real call against the demo env (captured by [`scripts/capture-tool-envelopes.mjs`](https://github.com/log-10x/log10x-mcp/blob/main/scripts/capture-tool-envelopes.mjs)).

    ```json
    {
      "pattern": "Payment_Gateway_Timeout",
      "timeRange": "24h",
      "view": "summary"
    }
    ```

??? tenx-input-schema "Input schema"

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

    ```json
    {
      "type": "object",
      "properties": {
        "pattern": {
          "type": "string",
          "description": "Pattern name (e.g., \"Payment_Gateway_Timeout\"). Provide either pattern or pattern_hash. pattern_hash is preferred when available (skips a metrics lookup)."
        },
        "monthly_volume_gb": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "What-if volume lens: model the environment at THIS monthly volume (decimal GB/month) instead of its measured volume. Real per-pattern shares and the pattern mix are held fixed; only absolute bytes and dollars scale, by one uniform factor. The envelope stamps volume_actual_gb vs volume_projected_gb and the scale factor; a [Projected to X/mo] prefix marks a lensed run. Omit it for the environment's real measured volume."
        },
        "pattern_hash": {
          "type": "string",
          "description": "The tenx_hash of the pattern (11-char stable identity from top_patterns / preview_filter). Preferred over pattern when available."
        },
        "timeRange": {
          "type": "string",
          "enum": [
            "15m",
            "1h",
            "6h",
            "24h",
            "1d",
            "7d",
            "30d"
          ],
          "default": "7d",
          "description": "Time range. '24h' and '1d' are equivalent (one-day window). Sub-day values show fine-grained trajectory around an incident."
        },
        "step": {
          "type": "string",
          "enum": [
            "1m",
            "5m",
            "15m",
            "1h",
            "6h",
            "1d"
          ],
          "default": "1h",
          "description": "Data point interval. Use `1m`/`5m` for sub-day windows (15m/1h/6h), `1h`/`6h` for day-level, `1d` for week+ windows."
        },
        "analyzerCost": {
          "type": "number",
          "description": "SIEM ingestion cost in $/GB"
        },
        "environment": {
          "type": "string",
          "description": "Environment nickname"
        },
        "view": {
          "type": "string",
          "const": "summary",
          "default": "summary",
          "description": "Output format. Always \"summary\", the structured envelope. Field retained for backward-compat."
        },
        "include": {
          "type": "string",
          "enum": [
            "kept",
            "dropped",
            "both"
          ],
          "default": "kept",
          "description": "Which engine-decision cohort to scope the trend to. `kept` (default) = events the engine forwarded as-is (routeState!=\"drop\"), the pre-PL-12 behavior. `dropped` = events tagged routeState=\"drop\" by the engine (the offload/down-tier cohort). `both` = the pre-decision union; envelope adds a parallel `dropped_time_series` and `dropped_share_pct` so one call shows offload share over time. Use `dropped` to verify post-deploy realised savings or to chart \"what we are offloading right now\". Use `both` to overlay kept vs dropped on the same window."
        },
        "include_chart": {
          "type": "boolean",
          "default": false,
          "description": "Set include_chart=true to embed the rendered chart inline (large; default false to avoid response truncation)."
        }
      },
      "additionalProperties": false
    }
    ```

    Source: [`src/tools/trend.ts`](https://github.com/log-10x/log10x-mcp/blob/main/src/tools/trend.ts).

??? tenx-output-example "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):

    > _`Payment\_Gateway\_Timeout` over last 24h: $42.18 measured spend, change +218% (last quarter vs first quarter run-rate), spike detected_

    ```json
    {
      "schema_version": "1.0",
      "schema_epoch": "2026-05-25",
      "tool": "log10x_pattern_trend",
      "generated_at": "2026-05-26T00:00:00.000Z",
      "view": "summary",
      "summary": {
        "headline": "`Payment_Gateway_Timeout` over last 24h: $42.18 measured spend, change +218% (last quarter vs first quarter run-rate), spike detected"
      },
      "data": {
        "pattern": "Payment_Gateway_Timeout",
        "window": "last 24h",
        "step": "1h",
        "total_cost_usd": 42.18,
        "first_quarter_avg_bytes_per_sec": 1240,
        "last_quarter_avg_bytes_per_sec": 3942,
        "change_pct": 218,
        "spike_detected": true,
        "spike_window_start": "2026-05-25T22:00:00Z",
        "time_series": [
          {
            "ts": 1748131200,
            "bytes": 1130
          },
          {
            "ts": 1748134800,
            "bytes": 1224
          },
          {
            "ts": 1748138400,
            "bytes": 1180
          },
          "... 1 more elided"
        ]
      },
      "actions": [
        {
          "tool": "log10x_pattern_examples",
          "args": {
            "pattern": "Payment_Gateway_Timeout",
            "limit": 5,
            "timeRange": "1h"
          },
          "reason": "sample 5 events from the spike window to see what changed"
        },
        {
          "tool": "log10x_pattern_mitigate",
          "args": {
            "pattern": "Payment_Gateway_Timeout"
          },
          "reason": "spike is sustained. Show the env-gated mitigation menu"
        }
      ],
      "render_hint": {
        "chart": "timeseries",
        "units": "bytes/sec"
      },
      "truncated": false,
      "warnings": [],
      "images": [
        {
          "data": "<base64 PNG omitted from doc capture; render at runtime>",
          "mimeType": "image/png",
          "alt": "Timeseries chart of Payment_Gateway_Timeout over last 24h"
        }
      ]
    }
    ```

??? tenx-output-schema "Output schema"

    The `data` block inside the [StructuredOutput envelope](../index.md#json-by-default-output):

    ```typescript
    interface ToolData {
      pattern: string;
      window: string;
      step: string;
      total_cost_usd: number;
      first_quarter_avg_bytes_per_sec: number;
      last_quarter_avg_bytes_per_sec: number;
      change_pct: number;
      spike_detected: boolean;
      spike_window_start: string;
      time_series: Array<{
        ts: number;
        bytes: number;
      }>;
    }
    ```

    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).