Rank by shape

Step 2 of the three-step cross-pillar flow. Computes Pearson correlation and lag offset between an anchor series and each candidate at multiple lag offsets (default ±1800s), returning raw numbers: pearson_signed, best_lag_seconds, lag_direction, and flags. No tier labels, no "confirmed" / "coincidence" framing, no causal claim.

The agent reads the numbers and decides. Use metric_overlay to verify the top candidates visually.

Example

You

rank these 4 metrics by similarity to Payment_Gateway_Timeout

Log10x

Rank	Metric	Pearson	Lag	Direction
1	apm_request_duration_p99	0.91	+0s	co-moves
2	http_client_requests_total{status="503"}	0.87	−60s	candidate leads anchor
3	db_connection_pool_active	0.74	+30s	anchor leads candidate
4	apm_request_duration_p50	0.61	+0s	co-moves

Prerequisites

LOG10X_CUSTOMER_METRICS_URL configured. Reporter deployed for log10x pattern anchors. Call metrics_that_moved first to filter candidates to a manageable size.

Schema and samples

Input schema

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

{
  "type": "object",
  "properties": {
    "anchor_type": {
      "type": "string",
      "enum": [
        "log10x_pattern",
        "customer_metric"
      ]
    },
    "anchor": {
      "type": "string",
      "description": "Anchor identity (pattern symbol_message OR customer PromQL)."
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Customer-side PromQL expressions to rank (max 100). An AI caller reasoning over results can't meaningfully digest more than a few dozen; the cap reflects that, not a backend constraint."
    },
    "window": {
      "type": "string",
      "default": "1h"
    },
    "timeRange": {
      "type": "string"
    },
    "step": {
      "type": "string",
      "default": "30s"
    },
    "lag_search_max_abs": {
      "type": "number",
      "minimum": 0,
      "default": 1800,
      "description": "Maximum absolute lag in seconds to scan. Default 1800s — uncalibrated. Output is tagged `unvalidated_default` when used as-is. Narrow it when the use case has a known tighter upper bound on cascade latency (e.g. 300 for sub-5-min cascades). See `docs/cross-pillar-primitives.md` for the calibration playbook."
    },
    "anchor_phase_aligned_floor": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.15,
      "description": "Relative phase-gap floor for the `anchor_phase_aligned` flag. Default 0.15 — uncalibrated, same provenance caveat as lag_search_max_abs."
    },
    "environment": {
      "type": "string"
    }
  },
  "required": [
    "anchor_type",
    "anchor",
    "candidates"
  ],
  "additionalProperties": false
}

Source: src/tools/rank-by-shape-similarity.ts.

Output schema

The data block inside the StructuredOutput envelope:

interface ToolData {
  ranked: Array<{
    candidate: string;
    pearson_signed: number;
    best_lag_seconds: number;
    lag_direction: 'leads_anchor' | 'lags_anchor' | 'co_moves';
    anchor_phase_aligned: boolean;
    flags: string[];
  }>;
  anchor_dispersion: number;
  calibration_tags: string[];
}

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

Next: Detect