Prometheus API and Grafana
Query Maple metrics with PromQL through the Prometheus HTTP API, and add Maple to Grafana as a Prometheus data source.
Maple serves the Prometheus HTTP query API over your metrics. Grafana, and any other tool that speaks to Prometheus, can query Maple with PromQL.
| URL (US) | https://api.maple.dev/ |
| URL (EU) | https://api.eu.maple.dev/ |
| Auth | Authorization: Bearer maple_, or Basic auth with the key as the password |
| Required scope | metrics:read |
| Rate limit | 600 requests per minute per API key |
Connect Grafana
- Create an API key with the
metrics:readscope. - In Grafana, go to Connections > Data sources > Add data source and pick Prometheus.
- Set Prometheus server URL to
https://api.maple.dev/(or the EU URL).v2/ metrics/ prometheus - Add the key in one of two ways:
- Under HTTP headers, add a header named
Authorizationwith the valueBearer <your API key>. - Or turn on Basic authentication, enter any user name, and paste the API key as the Password.
- Under HTTP headers, add a header named
- Leave HTTP method on POST, or pick GET. Both work.
- Under Performance, set Prometheus type to Prometheus and Prometheus version to 3.x.
- Click Save & test.
Grafana’s metric browser, label filters and query builder read the same API, so metric and label names autocomplete.
One key for every viewer
Grafana sends the data source’s key with every query, whoever is looking at the dashboard. All viewers share that key’s 600 requests per minute, and every query is recorded in Maple’s audit log as that key. A dashboard with many panels and template variables makes one request per panel and variable on each refresh, so a busy dashboard with a short refresh interval can reach the limit. Past it, Maple answers 429 with a Retry-After header and Grafana shows the error on the panel. Use a dedicated key per Grafana instance, and a longer refresh interval on large dashboards.
Provisioning
To set the data source up from a file, put this in Grafana’s provisioning/datasources/ directory with the key in the MAPLE_API_KEY environment variable:
apiVersion: 1
datasources:
- name: Maple
type: prometheus
access: proxy
url: https://api.maple.dev/v2/metrics/prometheus
jsonData:
httpMethod: POST
prometheusType: Prometheus
prometheusVersion: 3.5.0
httpHeaderName1: Authorization
secureJsonData:
httpHeaderValue1: Bearer ${MAPLE_API_KEY}
With Basic authentication instead of the header:
apiVersion: 1
datasources:
- name: Maple
type: prometheus
access: proxy
url: https://api.maple.dev/v2/metrics/prometheus
basicAuth: true
basicAuthUser: maple
jsonData:
httpMethod: POST
prometheusType: Prometheus
prometheusVersion: 3.5.0
secureJsonData:
basicAuthPassword: ${MAPLE_API_KEY}
Basic auth is accepted only on the Prometheus API. The user name is ignored, and the password must be a Maple API key; a session token or a malformed header is refused with 401.
Metric and label names
OpenTelemetry metrics get the names the Prometheus OTLP translation gives them: dots become underscores, the unit is added as a suffix, and monotonic sums end in _total. A sum http.server.requests is http_server_requests_total, and a histogram http.server.duration in seconds is http_, _count and _sum. The stored OpenTelemetry name also works.
Attributes become labels the same way (http.route is http_route). job is the service name, prefixed with service.namespace/ when the service sets one, and instance is service.instance.id.
To find a metric’s name, open Grafana’s Metrics browser, or list them all with label/__name__/values. The metrics explorer shows the stored OpenTelemetry names and their types.
Endpoints
All paths are under /v2/metrics/prometheus/api/v1/ and follow Prometheus’ parameters and response format. POST takes an application/ body, as Grafana sends it.
| Endpoint | Methods | Notes |
|---|---|---|
query | GET, POST | Instant query. |
query_range | GET, POST | Range query. |
series | GET, POST | Needs at least one match[]. |
labels | GET, POST | |
label/<name>/values | GET | __name__ lists metric names. |
metadata | GET | Type, help and unit from the metric catalog. |
format_query | GET, POST | Pretty-prints a PromQL expression. |
query_exemplars | GET, POST | Always an empty list. |
rules | GET | Always an empty list: Maple evaluates no Prometheus rules. |
alerts | GET | Always an empty list. Use Maple alerts instead. |
status/buildinfo | GET | Reports Prometheus 3.5.0, so Grafana enables the matching features. |
status/config | GET | An empty configuration. |
status/flags | GET | No flags. |
curl -H "Authorization: Bearer $MAPLE_API_KEY" \
"https://api.maple.dev/v2/metrics/prometheus/api/v1/query" \
--data-urlencode 'query=sum by (job) (rate(http_server_requests_total[5m]))'
Limits
| Limit | Value |
|---|---|
| Metric retention | 90 days. A query_range over a longer range is evaluated as asked; steps before the retention have no samples. |
Points per series in query_range | 11,000, as in Prometheus. Use a larger step for long ranges. |
| Series per query | 10,000 |
| Samples a query may load | 5,000,000 |
| Samples in one response | 500,000 |
| How far back a query may read | 400 days, counting range selectors, offset, @ and subqueries |
| Query length | 10,000 characters |
Selectors per query, match[] per call | 20 |
| Metrics one selector may match | 100 |
| Discovery window | The last 32 days of the requested range. Without start and end, the last hour (24 hours for metadata). |
| Discovery results | 10,000 names, values or series per call |
| Query time | 30 seconds in the metric store, or less with the timeout parameter |
labels, label/<name>/values and series never fail on a long range: a dashboard set to the last 90 days fills its template variables from the most recent 32 days.
Errors
Errors use Prometheus’ envelope, {"status":"error",:
| Status | errorType | When |
|---|---|---|
| 400 | bad_data | The query does not parse, or a parameter is invalid. |
| 422 | execution | The query is valid but too large: too many series or samples, or more memory than allowed. |
| 503 | timeout | The query ran past the timeout parameter or the 30 second limit. |
| 503 | unavailable | The metric store could not be reached. Retry. |
For execution and timeout, narrow the selector with more label matchers, aggregate with sum by (...), or use a larger step. Authentication and rate-limit errors (401, 403, 429) use the v2 API error format instead.
Not supported
- Writing data: no remote write, and
/api/v1/admin/*is not served. Send metrics with OpenTelemetry or Prometheus scraping. - Recording and alerting rules:
rulesandalertsare always empty. - Exemplars:
query_exemplarsis always empty. parse_query,targets,status/tsdb,status/runtimeinfoand the other status endpoints, andlabel/<name>/valuesover POST (Prometheus serves it as GET only too).