sapcc-metrics

name	sapcc-metrics
description	Maia metrics querying for SAP Converged Cloud (Prometheus-as-a-Service). Triggers: metrics, monitoring, prometheus, promql, CPU usage, memory usage, maia, dashboard, alert, performance
version	1.0.0
metadata	{"service":["maia"],"task":["query","monitor","debug"],"persona":["developer","devops"]}

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