Skip to content
Maple Docs
Open app

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/v2/metrics/prometheus
URL (EU)https://api.eu.maple.dev/v2/metrics/prometheus
AuthAuthorization: Bearer maple_ak_…, or Basic auth with the key as the password
Required scopemetrics:read
Rate limit600 requests per minute per API key

Connect Grafana

  1. Create an API key with the metrics:read scope.
  2. In Grafana, go to Connections > Data sources > Add data source and pick Prometheus.
  3. Set Prometheus server URL to https://api.maple.dev/v2/metrics/prometheus (or the EU URL).
  4. Add the key in one of two ways:
    • Under HTTP headers, add a header named Authorization with the value Bearer <your API key>.
    • Or turn on Basic authentication, enter any user name, and paste the API key as the Password.
  5. Leave HTTP method on POST, or pick GET. Both work.
  6. Under Performance, set Prometheus type to Prometheus and Prometheus version to 3.x.
  7. 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_server_duration_seconds_bucket, _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/x-www-form-urlencoded body, as Grafana sends it.

EndpointMethodsNotes
queryGET, POSTInstant query.
query_rangeGET, POSTRange query.
seriesGET, POSTNeeds at least one match[].
labelsGET, POST
label/<name>/valuesGET__name__ lists metric names.
metadataGETType, help and unit from the metric catalog.
format_queryGET, POSTPretty-prints a PromQL expression.
query_exemplarsGET, POSTAlways an empty list.
rulesGETAlways an empty list: Maple evaluates no Prometheus rules.
alertsGETAlways an empty list. Use Maple alerts instead.
status/buildinfoGETReports Prometheus 3.5.0, so Grafana enables the matching features.
status/configGETAn empty configuration.
status/flagsGETNo 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

LimitValue
Metric retention90 days. A query_range over a longer range is evaluated as asked; steps before the retention have no samples.
Points per series in query_range11,000, as in Prometheus. Use a larger step for long ranges.
Series per query10,000
Samples a query may load5,000,000
Samples in one response500,000
How far back a query may read400 days, counting range selectors, offset, @ and subqueries
Query length10,000 characters
Selectors per query, match[] per call20
Metrics one selector may match100
Discovery windowThe last 32 days of the requested range. Without start and end, the last hour (24 hours for metadata).
Discovery results10,000 names, values or series per call
Query time30 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","errorType":"…","error":"…"}:

StatuserrorTypeWhen
400bad_dataThe query does not parse, or a parameter is invalid.
422executionThe query is valid but too large: too many series or samples, or more memory than allowed.
503timeoutThe query ran past the timeout parameter or the 30 second limit.
503unavailableThe 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: rules and alerts are always empty.
  • Exemplars: query_exemplars is always empty.
  • parse_query, targets, status/tsdb, status/runtimeinfo and the other status endpoints, and label/<name>/values over POST (Prometheus serves it as GET only too).