Paperless-ngx metrics for Prometheus

This repository hosts a Prometheus metrics exporter for Paperless-ngx, a document management system transforming physical documents into a searchable online archive. The exporter relies on Paperless' REST API.

An implementation using the API was chosen to provide the same perspective as web browsers.

Usage

prometheus-paperless-exporter listens on TCP port 8081 by default. To listen on another address use the -web.listen-address flag (e.g. -web.listen-address=127.0.0.1:3000).

TLS and HTTP basic authentication is supported through the Prometheus exporter toolkit. A configuration file can be passed to the -web.config flag (documentation).

See the --help output for more flags.

Collector selection

The exporter supports configuring which collectors are enabled via the --collectors flag. Provide a comma-separated list of collector ids. If the flag is omitted or empty, all standard collectors are enabled.

Available collector ids:

• tag
• correspondent
• document_type
• storage_path
• task
• log
• group
• user
• document
• status
• statistics
• remote_version (requires --enable-remote-network to actually be used)

Examples:

Enable only tags and documents:

./prometheus-paperless-exporter --collectors=tag,document

Enable all standard collectors and also the remote version collector (remote network checks must be explicitly allowed):

./prometheus-paperless-exporter --enable-remote-network

If you specify unknown collector ids the exporter will exit with an error listing the unknown and known ids.

Permissions

The metrics user requires view permissions on the following object types:

• Admin
  • Required for log analysis.
  • Starting with version 2.8 there is no distinction between different access modes (paperless-ngx#6380).
• Correspondent
• Document
• DocumentType
• Group
• PaperlessTask
• StoragePath
• Tag
• User

Installation

Pre-built binaries are provided for all releases:

• Binary archives (.tar.gz)
• Debian/Ubuntu (.deb)
• RHEL/Fedora (.rpm)
• Microsoft Windows (.zip)

Docker images via GitHub's container registry. The image supports Linux/AMD64 and Linux/ARM64.

docker pull ghcr.io/hansmi/prometheus-paperless-exporter

It's also possible to produce custom builds directly using Go or GoReleaser.

Docker Compose

An example configuration for Docker Compose is available in contrib/docker-compose:

env --chdir contrib/docker-compose docker-compose up