Skip to content
Maple Docs
Open app
Browse the docs
On this page

Prometheus scraping

Point Maple at any Prometheus exposition endpoint. Maple scrapes it on a schedule, converts the samples to OpenTelemetry metrics, and records the health of every scrape.

Maple can scrape any endpoint that serves the Prometheus or OpenMetrics text format. You add the endpoint as a scrape target. Maple polls it at the interval you choose, converts the samples to OpenTelemetry metrics, and ingests them like your own OTLP traffic. Scraped metrics appear in the metrics explorer, dashboards, and alert rules, and each target keeps a history of its scrapes.

Prerequisites

  • An endpoint reachable from the public internet that serves /metrics in the Prometheus exposition format.

Add a scrape target

Open Integrations → Prometheus in Maple and click Add Target. The Add Scrape Target dialog has these fields:

FieldNotes
NameDisplay name. Used as the service name when Service Name is empty.
Service NameOptional. Sets service.name on the resource and the job attribute on every data point.
URLFull endpoint URL, for example https://myapp.com:9090/metrics. Loopback, private-range, and cloud-metadata addresses are rejected.
Scrape Interval (seconds)5 to 300. Default 15.
AuthenticationNone, Bearer Token (sent as Authorization: Bearer …), or Basic Auth (Username and Password).

Credentials are encrypted at rest. The scraper receives the decrypted auth header from Maple’s API for each run and sends it directly to your endpoint. Requests carry the user agent maple-prometheus-scraper.

Each request times out after the scrape interval minus one second, capped at 60 seconds.

You can also manage targets through the REST API under /v2/scrape_targets, with endpoints to create, update, delete, probe, and list checks. The API accepts one extra field, labels_json: a JSON object of labels added to every sample (for example {"cluster": "prod"}). The keys job and instance, and any key starting with maple_ or __, are reserved and rejected.

How the data looks

  • Metric names are kept as they appear in the exposition.
  • Counters become cumulative monotonic sums. Gauges and untyped metrics become gauges. Histograms become OTLP histograms with the original bucket bounds.
  • Summaries become three series: <name>_sum as a cumulative sum, <name>_count as a cumulative monotonic sum, and the quantiles as a gauge named <name> with a quantile attribute. Summary samples that are not finite numbers (such as a NaN quantile with no observations yet) are dropped.
  • Every data point carries job (the service name) and instance (the host of the target URL), plus the target’s labels and the sample’s own labels.

Verify

  1. On the target row, click Test. Maple runs an immediate scrape and reports success or the exact failure: HTTP status, timeout, TLS or connection error.
  2. Wait one scrape interval. The status badge changes from No checks to Up, and the row shows Last scrape with a relative time.
  3. Open the target to see its check history. Each run lists Time, State, Duration, and Samples.
  4. Search for one of your metric names in the metrics explorer.

Troubleshooting

  • Status is Down. Open the target. The error message and a How to fix hint explain the failure. A failed scrape never advances the last successful scrape time, so the data gap stays visible next to the error.
  • The URL is rejected. The endpoint resolves to a loopback, private, or metadata address. Expose it through an authenticated public endpoint, or use the collector option below.
  • 401 or 403. Check the authentication type and credentials. Basic Auth sends the username and password exactly as entered.
  • The endpoint is only reachable inside your network. Run an OpenTelemetry Collector inside the network with a prometheus receiver and an OTLP exporter pointed at Maple’s ingest endpoint.

Next steps

  • WarpStream: scrape WarpStream Agents or the hosted Prometheus endpoint.
  • PlanetScale: branch metrics discovered automatically.
  • Alert rules: alert on a scraped metric.