# Sapcc Metrics

> Maia metrics querying for SAP Converged Cloud (Prometheus-as-a-Service). Triggers: metrics, monitoring, prometheus, promql, CPU usage, memory usage, maia, dashboard, alert, performance

- Skill: `notque/sapcc-metrics` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add notque/sapcc-metrics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/notque/sapcc-metrics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: notque (https://skillmd.com/u/notque)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/notque/sapcc-metrics

---


# SAP CC Metrics (Maia)

Maia is SAP CC's multi-tenant Prometheus-as-a-Service. Same PromQL query language, but tenant-isolated — each project sees only its own metrics. Read-only via MCP.

## MCP Tools

### Read Tools
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `maia_query` | Execute instant PromQL query | `query`, `time` (optional) |
| `maia_query_range` | Execute range PromQL query over time window | `query`, `start`, `end`, `step` |
| `maia_label_values` | Get values for a specific label | `label` (e.g., `__name__`, `instance`, `job`) |
| `maia_metric_names` | List all available metric names for current project | — |

## Maia vs Regular Prometheus

- **Same PromQL** — all standard functions and operators work (rate, avg, sum, topk, etc.)
- **Tenant-isolated** — you only see metrics from your authenticated project
- **Available metrics vary** — depends on what's instrumented in your project (not all projects have the same metrics)
- **Read-only** — no recording rules, no alert configuration, no write path via MCP
- **Instant and range queries** — maia_query executes point-in-time queries; maia_query_range returns time series over a window

## Gotchas

### 1. Results are scoped to current project — you CANNOT query other projects' metrics

Maia enforces tenant isolation via the OpenStack token. There is no way to query cross-project metrics. If you need fleet-wide data, check Limes for capacity or use cluster-level monitoring.

### 2. maia_query is INSTANT — use maia_query_range for time series

`maia_query` returns a single point in time. Use the `time` parameter to query a historical point. For time series data ("show me the last hour"), use `maia_query_range` with `start`, `end`, and `step` parameters instead.

### 3. Always start with maia_metric_names

Before writing PromQL, discover what's available. Different projects have different metrics. Never assume a metric exists — verify first.

### 4. maia_label_values with label="__name__" equals maia_metric_names

Both return the list of available metric names. Use `maia_label_values` when you need values for other labels (instance, job, device, etc.).

### 5. time parameter defaults to NOW

Optional. Accepts RFC3339 (`2024-03-15T10:00:00Z`) or Unix timestamp (`1710500400`). Omitting it gives current values. For "what was CPU at 3am?" — pass the specific timestamp.

### 6. PromQL syntax errors return generic errors

The API does not give helpful parse errors. If you get an error, validate your query syntax independently before blaming connectivity or permissions. Common mistakes: missing brackets, unbalanced quotes, typos in metric names.

### 7. Metric names vary by project

Not all projects have the same instrumentation. A compute-heavy project might have `node_cpu_seconds_total` while a Kubernetes project has `container_cpu_usage_seconds_total`. Always discover first.

### 8. Large result sets may be truncated

Queries that match many series (e.g., `{__name__=~".+"}`) can hit response size limits. Use specific label selectors to narrow: `{instance="specific-host"}`, `{job="specific-job"}`.

### 9. No aggregation across projects

If the user asks "how much CPU is our whole team using?" — that requires cluster-level access or Limes. Maia only shows the current project's metrics. Redirect to quota tools for cross-project views.

## Common Workflows

### Discover available metrics

```
1. maia_metric_names → see what's instrumented
2. Pick relevant metric name
3. maia_label_values(label="instance") → find dimensions
4. maia_label_values(label="job") → understand metric sources
```

### "Is my server healthy?"

```
1. maia_metric_names → find CPU/memory/disk metrics
2. maia_label_values(label="instance") → identify the server
3. maia_query(query='node_cpu_seconds_total{instance="<host>", mode="idle"}')
4. maia_query(query='node_memory_MemAvailable_bytes{instance="<host>"}')
5. maia_query(query='node_filesystem_avail_bytes{instance="<host>", mountpoint="/"}')
```

### "What's the current load?"

```
1. maia_query(query='rate(node_cpu_seconds_total{mode!="idle"}[5m])')
2. maia_query(query='avg by (instance) (rate(node_cpu_seconds_total{mode!="idle"}[5m]))')
```

Note: rate() requires a range vector but returns an instant vector — works with maia_query.

### Troubleshooting a specific issue

```
1. maia_metric_names → find relevant metrics (grep mentally)
2. maia_label_values(label="<relevant_label>") → explore dimensions
3. Write targeted PromQL with specific label selectors
4. Interpret the value in context (e.g., bytes → GiB, ratio → percentage)
```

## PromQL Quick Reference

Common patterns for SAP CC infrastructure metrics:

| Pattern | PromQL | Use Case |
|---------|--------|----------|
| Rate of change | `rate(metric[5m])` | Counter metrics (CPU, network bytes) |
| Average by instance | `avg by (instance) (metric)` | Reduce cardinality |
| Top N | `topk(5, metric)` | Find highest consumers |
| Threshold check | `metric > 0.9` | Alert-style filtering |
| CPU usage % | `1 - rate(node_cpu_seconds_total{mode="idle"}[5m])` | Per-core idle inverse |
| Memory usage % | `1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)` | Available/total ratio |
| Disk usage % | `1 - (node_filesystem_avail_bytes / node_filesystem_size_bytes)` | Free/total ratio |
| Sum by label | `sum by (job) (metric)` | Aggregate across instances |
| Filter by regex | `metric{label=~"pattern.*"}` | Flexible label matching |

See `references/promql-patterns.md` for extended pattern library.

## Troubleshooting

### No metrics found (maia_metric_names returns empty)

- Project has no instrumentation configured
- Token might be scoped to wrong project — verify with `keystone_token_info`
- The project may be new with nothing deployed yet

### maia_query returns empty result

- Metric name typo — copy-paste from maia_metric_names output
- Label selector too restrictive — remove labels and broaden
- Metric exists but no data at queried time — try without `time` param (defaults to now)
- Counter metric with rate() on too-short window — try `[10m]` instead of `[1m]`

### Query syntax error

- Unbalanced brackets: `rate(metric[5m]` missing closing `)`
- Wrong bracket type: range vectors use `[5m]` not `(5m)`
- Unquoted label value: must be `{label="value"}` with quotes
- Invalid duration: use `s`, `m`, `h`, `d` — not `sec`, `min`
- Metric name with dots: wrap in `{__name__="metric.with.dots"}`

### Unexpected values

- Counters always increase — use `rate()` or `increase()` to get meaningful values
- Gauge vs counter confusion — check if values only go up (counter) or fluctuate (gauge)
- Unit mismatch — bytes vs bits, MiB vs MB, seconds vs milliseconds
- `NaN` or `+Inf` — division by zero in your query or absent denominator series

## Security

Metrics reveal operational state: CPU patterns, memory pressure, disk growth rates, network traffic volumes, and deployment schedules. This data exposes:

- Capacity planning (how close to limits)
- Traffic patterns (peak times, quiet periods)
- Infrastructure topology (which instances, what roles)
- Potential vulnerabilities (overloaded systems, resource exhaustion)

Treat metric data as internal/confidential. Only query what's needed for the task at hand.

## Cross-Service References

| Need | Service | Tool |
|------|---------|------|
| Map instance label to server name | Nova | `nova_get_server(<instance_id>)` |
| Correlate resource usage with quota | Limes | `limes_get_project_quota` |
| Investigate anomalies in audit trail | Hermes | `hermes_list_events` |
| Network metrics correlation | Neutron | `neutron_list_ports(device_id=<instance_id>)` |

## Routing

| User need | Action |
|-----------|--------|
| PromQL query patterns for SAP CC | Read [promql-patterns.md](references/promql-patterns.md) |