Overflow contents

The maintenance-phase tool for the overflow bucket. Queries all_events_summaryBytes_total{isDropped="true"} grouped by (pattern, service, container), joins the result to the cap-CSV so only offload-action patterns surface (not drop or compact), and computes growth rate per pattern as the percent change between the first and second halves of the window.

This tool does NOT scan S3 and does NOT estimate dollar savings — the overflow queue has negligible storage cost. Use log10x_retriever_query to fetch events back from the bucket.

Example

You

what's in the overflow bucket this month?

Log10x

Overflow contents (30d): 3 patterns · 12.4 GB total · top grower +18%/week.

Pattern	Service	Bytes (30d)	Growth
cart_item_added_sku_$qty$	checkout-svc	5.2 GB	+18%/week
healthcheck_ok_pod_$	all	4.1 GB	+2%/week
debug_cache_miss_key_$	cache-svc	3.1 GB	−3%/week

More to ask

• "overflow contents, last 7 days"
• "overflow contents scoped to payment-svc"
• "fetch back the cart_item_added events from last week" → routes to log10x_retriever_query

Prerequisites

Retriever (S3 overflow bucket) and Receiver deployed. log10x_configure_engine run with at least one pattern assigned action=offload.

Schema and samples

Input schema

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

{
  "type": "object",
  "properties": {
    "timeRange": {
      "type": "string",
      "enum": [
        "15m",
        "1h",
        "6h",
        "24h",
        "1d",
        "7d",
        "30d"
      ],
      "default": "30d",
      "description": "Window over which to compute overflow contents. 30d matches the maintenance-loop cadence; sub-30d windows for incident-window probes. '24h' and '1d' are equivalent."
    },
    "service": {
      "type": "string",
      "description": "Filter to a single service. Omit for the full overflow queue across every service that routes to S3."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500,
      "default": 50,
      "description": "Cap on the number of per-pattern rows returned. Total bytes always reflect the full overflow, even when rows are truncated."
    },
    "environment": {
      "type": "string",
      "description": "Environment nickname"
    },
    "view": {
      "type": "string",
      "const": "summary",
      "default": "summary",
      "description": "Output format. Always \"summary\" — the typed envelope (data.patterns[], data.totals)."
    }
  },
  "additionalProperties": false
}

Source: src/tools/overflow-contents.ts.

Output schema

The data block inside the StructuredOutput envelope:

interface ToolData {
  patterns: Array<{
    pattern_hash: string;
    service: string;
    container: string;
    bytes_in_window: number;
    event_count_in_window: number;
    time_window_first: string | null;
    time_window_last: string | null;
    time_window_basis: 'computed' | 'single_sample' | 'insufficient_samples';
    growth_rate_pct: number | null;
    growth_rate_basis: 'computed' | 'new_pattern' | 'insufficient_baseline';
    action: 'pass' | 'sample' | 'compact' | 'drop' | 'offload' | 'tier_down' | null;
    action_source: 'action_intent' | 'legacy_cap_csv' | 'unverified';
  }>;
  total_bytes_in_window: number;
  total_event_count_in_window: number;
  pattern_count: number;
  truncated: boolean;
  cap_csv_status: {
    kind: 'not_configured' | 'configured_not_loaded' | 'loaded' | 'lookup_failed';
    reason: string;
    source: string | null;
  };
  time_range: string;
}

Envelope-level fields: summary.headline, actions[] (routes to log10x_retriever_query for rehydration), schema_epoch.

Next: Probe