kopia-go-exporter

Kopia-go-exporter is a Prometheus exporter for Kopia backup repositories. It connects to a Kopia API server, retrieves snapshot metrics (size, file/dir counts, errors, duration, timestamps), and exposes them via an HTTP /metrics endpoint for Prometheus scraping.

See the Motivations section below for background on why this project exists.

Getting Started

1. Download: Get the latest binary for your platform from the GitHub releases page.
2. Configure: Create a config.yaml file with the following contents. All options are documented with comments in the config.default.yaml file.

   exporter:
     port: 9090
     metrics:
       prefix: "kopia_go_exporter"
     interval: 300
   
   kopia:
     apiserver:
       repositoryURL: "https://some.url:port"
       fingerprint: "you can also set me in KGE_KOPIA_APISERVER_FINGERPRINT env var"
     clients:
       default:
         username: "mybackup"
         hostname: "myhostname"
         password: "you can also set me in KGE_KOPIA_CLIENTS_DEFAULT_PASSWORD env var"
     retentionstoextract:
       - "latest-1"
   
   logger:
     log_level: "info"

3. Run:

   ./kopia-go-exporter --config config.yaml

4. Verify: Check that metrics are available at http://localhost:9090/metrics in your browser or via curl. You should see Kopia backup metrics such as kopia_go_exporter_total_size and kopia_go_exporter_backup_duration.

Run with docker/podman

The container image is published on the GitHub Container Registry:

ghcr.io/ymettier/kopia_go_exporter:0.3.0

1. Configure: Create a config.yaml file as described in the Getting Started section.
2. Run:

   podman run -d \
     --name kopia-go-exporter \
     -p 9090:9090 \
     -e KGE_KOPIA_CLIENTS_DEFAULT_PASSWORD="your-kopia-password" \
     -e KGE_KOPIA_APISERVER_FINGERPRINT="your-server-fingerprint" \
     -v /path/to/config.yaml:/config.yaml:ro \
     ghcr.io/ymettier/kopia_go_exporter:0.3.0 \
     --config /config.yaml

   Sensitive values (password, fingerprint) are passed preferably as environment variables.
3. Verify: Open http://localhost:9090/metrics in your browser or use curl http://localhost:9090/metrics to confirm metrics are being exported.

Kubernetes

The chart is located in charts/kopia_go_exporter.

Configuration:

1. Create the Kopia credentials Secret. The server fingerprint is stored under the fingerprint key. Each client's password is stored under a password-<clientname> key, where <clientname> is the client name from step 2 below (e.g. the default client uses the password-default key):

   kubectl create secret generic kopia-config \
     --from-literal=password-default='your-kopia-password' \
     --from-literal=fingerprint='your-server-fingerprint'

2. Create a custom values file with your configuration. Each key under config.kopia.clients is a client name, here default:

   cat <<EOF > myvalues.yaml
   config:
     kopia:
       apiserver:
         repositoryURL: "https://host:port"
       clients:
         default:
           username: "mybackup"
           hostname: "myhost"
   EOF

   See charts/kopia_go_exporter/values.yaml and config.default.yaml for all available options.

Install:

helm upgrade --install --rollback-on-failure kopia-go-exporter oci://ghcr.io/ymettier/charts/kopia-go-exporter --version 0.3.0 -f myvalues.yaml

Note: Helm 3 users need --atomic instead of --rollback-on-failure.

Configuration

The file config.default.yaml contains all the configuration.

Kopia-go-exporter can use such a configuration file: run it with --config /path/to/config.yaml or -c /path/to/config.yaml where the config.yaml file is based on config.default.yaml and modified as you wish.

You can also override this configuration with environment variables. They are forged on the configuration items in config.default.yaml, with KGE_ prefix, the path of the item, flattened, uppercase, with underscores as a separator. Example:

kopia:
  apiserver:
    repositoryURL: "https://some.url:port"

can be overridden with

KGE_KOPIA_APISERVER_REPOSITORYURL=https://some.url:port

The client password follows the same rule, e.g. KGE_KOPIA_CLIENTS_DEFAULT_PASSWORD overrides kopia.clients.default.password.

Building

To build from source:

echo dev > version.txt && go build

To run the tests:

go test ./...

Motivations

Kopia lacks per-backup metrics. Kopia only exposes global metrics, not per-snapshot or per-source metrics. This is a known limitation (kopia#609, closed as not planned). Related discussions: kopia#4100, kopia#4685, kopia#5014.

Existing alternatives are unmaintained. kopia-exporter by alvistar works fine but it seems to be unmaintained.

I prefer an exporter written in Go. I wanted an exporter written in Go, with tests including one that launches a real Kopia server with sample backups.

I wrote this project and I maintain it on my free time for my personal use. Contributions are welcome and I will do my best to review them.

License

Kopia-go-exporter is licensed under the MIT License.