# Metrics

The MCP server supports querying Prometheus-compatible metrics using PromQL. Use these tools to discover metrics, explore metric labels, and query time-series data to monitor service behavior in real time.

### Search metrics

Use the `search_relevant_metrics` tool to find metrics before writing PromQL queries. Search semantically by natural-language description, or match metric names directly with a wildcard name pattern.

| Name    | Required | Type   | Description                                                                                                       |
| ------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `query` | Yes      | string | Search text. Its meaning depends on `mode`.                                                                       |
| `mode`  | No       | enum   | `by_description` (semantic search, default) or `by_name` (wildcard name pattern match, e.g. `http_*`, `*_total`). |
| `top_k` | No       | number | Maximum number of semantic matches to return (1–100, default: 5). Ignored when `mode` is `by_name`.               |

### Explore metric labels

Use the `get_metric_labels` tool to list the label names available for a metric, then use `get_metric_label_values` to list the values for a specific label. Use these to understand a metric's structure before constructing queries.

**`get_metric_labels` parameters:**

| Name          | Required | Type   | Description                         |
| ------------- | -------- | ------ | ----------------------------------- |
| `metric_name` | Yes      | string | The metric to list label names for. |

**`get_metric_label_values` parameters:**

| Name          | Required | Type   | Description                          |
| ------------- | -------- | ------ | ------------------------------------ |
| `metric_name` | Yes      | string | The metric to list label values for. |
| `label`       | Yes      | string | The label to list values for.        |

### Instant metric query

Run a PromQL expression at a single point in time using the `query_promql_instant` tool.

**Example:**

```js
{
  "query": "sum by (service) (rate(http_requests_total[5m]))",
  "time": "2024-01-15T11:00:00Z"
}
```

**Parameters**:

| Name    | Required | Type   | Description                                                                   |
| ------- | -------- | ------ | ----------------------------------------------------------------------------- |
| `query` | Yes      | string | A valid PromQL expression evaluated at a single point in time.                |
| `time`  | No       | string | RFC-3339 UTC timestamp for the evaluation time. Defaults to the current time. |

### Range metric query

Run a PromQL expression across a time window using the `query_promql_range` tool.

**Example:**

```js
{
  "query": "cpu_usage_percent",
  "start": "2024-01-15T10:00:00Z",
  "end": "2024-01-15T11:00:00Z",
  "step": "1m",
  "limit": 20
}
```

**Parameters**:

| Name    | Description                                                                                                                                   |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | A valid PromQL expression to evaluate over a range of time. Aggregate and segment with `by(label)`, and avoid high-cardinality results.       |
| `start` | Start time of the query window (RFC-3339 UTC format).                                                                                         |
| `end`   | End time of the query window (RFC-3339 UTC format).                                                                                           |
| `step`  | Interval between data points, specified as a duration (e.g., `1m`, `30s`, `6h`, `1d`). Size it so each series returns roughly 20 data points. |
| `limit` | Maximum number of samples to keep per time-series (1–200). Series that exceed the limit are marked as truncated.                              |