Nextcloud monitoring with Prometheus

Prometheus collects metrics by pulling them. On a fixed interval, the Prometheus server sends an HTTP request to each target it knows about, reads the metrics that target returns, and stores the samples in its local time series database. Targets come from service discovery or from a static list in the Prometheus configuration. For a Nextcloud server, that means Prometheus needs a stable address for the OpenMetrics endpoint added in Nextcloud 33, plus a scrape job that names it. Queries are written in PromQL, either in Prometheus directly or in Grafana, which reads from Prometheus as a data source.

The Prometheus pushgateway exists, but it is meant for short-lived batch jobs that finish before a scrape can reach them, such as an illustrative nightly maintenance script. It is not the normal path for a long-running Nextcloud server. Routing Nextcloud metrics through a gateway adds another component to secure, back up and monitor. It also hides failures, because the gateway keeps serving the last values it received even after the server has stopped responding. Before adding a gateway, list which jobs are truly batch work. For a web application that stays up, the endpoint itself carries the signal, and a failed scrape is a useful alert in its own right.

Because Prometheus opens every connection, design work starts at the network boundary. The Prometheus host must reach the metrics endpoint on the port and path Nextcloud serves, across any firewall, reverse proxy or container network in between. Write those rules before go-live, not after the first failed scrape. Authentication follows the same logic: the scrape job must present whatever credentials the endpoint requires, and those credentials sit in the Prometheus configuration, so they need the same protection as other secrets. Certificate trust belongs in the first design too. If Nextcloud uses a private certificate authority, Prometheus must trust it, and certificate renewal must be scheduled into the same process. Confirm how your Nextcloud version restricts access to the endpoint before you write the scrape job.

The Prometheus project documentation says it values reliability over precision and is not a good choice where 100% accuracy is required, such as per-request billing. A missed scrape leaves a gap in a graph, and rate calculations smooth over small inconsistencies. That is acceptable for capacity trends and for alerts on sustained conditions, such as a background job backlog that keeps growing or a database approaching its planned size. It is not an audit record of who opened or shared which file. Keep access logs, audit trails and any per-user accounting in Nextcloud's own logging, and tell reviewers that the Prometheus data is an operational view of the server.

The first decision is whether the metrics endpoint needs to leave the Nextcloud host at all. The simplest option keeps the endpoint on localhost and runs the Prometheus server on the same machine, so nothing is exposed to the network. When Prometheus runs elsewhere, the team has two practical paths: a dedicated internal listener that serves only the metrics path to the monitoring network, or a reverse proxy rule on the existing web server that matches the metrics path and admits only the scraper's address. Either path should be combined with credentials. Before relying on network controls alone, confirm in the Nextcloud 33 documentation whether the endpoint supports its own authentication, which settings enable it, and whether it can be bound to a separate interface.

The most common failure is routing the metrics path through the public web front end. If the virtual host forwards every request to Nextcloud, the endpoint answers anyone who can reach the site, and a request for an internal path may look like any other request to the application. Any rule added for scrapes must deny the metrics path to external sources by default and allow it only from the monitoring network. Test the rule from outside the network after every change to the web server configuration, because a rule that works from inside can still leave the path open. Also confirm how Nextcloud determines the client address behind a reverse proxy, since IP-based allow lists depend on the trusted proxy settings being correct.

Scrapes across hosts need transport encryption, and the team should decide how Prometheus will trust the certificate before the first scrape. Use a certificate issued by the internal certificate authority the organization already operates, install the CA bundle on the Prometheus host, and make sure the certificate name matches the host name in the scrape target. Disabling certificate verification to get a scrape working should be treated as an open defect. Assign certificate renewal to a named owner and monitor expiry, because an expired certificate stops every scrape at once. For scrape credentials, store the secret in a file readable only by the Prometheus service account, keep it out of configuration files committed to version control, and rotate it on a schedule: issue the new credential, update the file, reload Prometheus, confirm the target is up, then revoke the old credential.

Plan for the operational side before the endpoint goes live. Nextcloud publishes a new major version every four months and requires upgrades one major version at a time, so the team should recheck the endpoint, its authentication settings and the proxy rule after each upgrade and add that check to the upgrade runbook. Record which network path, credential and certificate authority the scraper uses, and name an owner for each. Alert on the up metric for the Nextcloud target so that a broken certificate, expired credential or blocked path appears as a failed scrape and is not hidden by gaps in dashboards. Finally, document and test a way to disable the scrape path quickly if a security review finds exposure.

Choose alerts by user impact. An alert earns a place in the first set only if someone must act on it within a known time. Start with five conditions: users unable to sign in or sync, background jobs stalling, database and cache unavailability, storage approaching capacity, and certificates close to expiry. A sign-in failure that affects many users matters more than a dozen counters for a single internal task. Ask, for each candidate alert, who gets paged, what they do first, and what breaks if they wait until morning.

Set thresholds from your own baseline. No universal values apply to every Nextcloud installation, because user counts, cron schedules, file sizes and sync patterns differ widely. Before enabling alerts, record normal sign-in failure rates, typical background job durations, cache and database response behavior and disk growth over a period your team chooses. Set each threshold above that normal range, then review it after the first few incidents. For certificates, the lead time should match how long your renewal process takes, including approvals. For storage, base the threshold on observed growth so the alert fires with enough time to add capacity.

Alertmanager reduces noise through three features. Grouping combines related alerts into one notification, so a database outage produces one message instead of one per affected service. Inhibition suppresses dependent alerts while a root cause is firing, for example muting application errors while the database alert is active. Silences cover planned maintenance and should carry an owner and an expiry time. A noisy alert set gets ignored, and once people mute a channel, real incidents are missed. For high availability, Alertmanager can run as a cluster using its cluster flags, and Prometheus should list every Alertmanager instance directly.

Prometheus local storage keeps data in two-hour blocks, and its default retention is 15 days. That period suits troubleshooting and short trend checks, but it is too short for capacity planning or compliance evidence. Local storage is not clustered or replicated, so the Prometheus server should be planned, sized and backed up like any single-node database. If your team needs longer history, configure remote write to an external long-term storage system. Confirm which backend you will use, who operates it, how it is secured and what it costs to run, because that work is separate from the Nextcloud and Prometheus setup itself.