KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

qnapexporter

★ 74 Open GitHub ↗

Prometheus metrics exporter, Grafana dashboards, and QNAP notification sink for QNAP NAS devices.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Build](https://github.com/pedropombeiro/qnapexporter/actions/workflows/main.yml/badge.svg)](https://github.com/pedropombeiro/qnapexporter/actions/workflows/main.yml)

# qnapexporter

`qnapexporter` is a simple Go program meant to be run in the background on a QNAP NAS in order to export
relevant metrics to Prometheus. It exposes an HTTP `/metrics` endpoint which generates a standard Prometheus metrics file, and a `/notifications` endpoint which can simulate an SMSC endpoint for QNAP notifications.

The data produced by this exporter can be used to create Grafana dashboards such as the following:

![Grafana dashboard sample](https://raw.githubusercontent.com/pedropombeiro/qnapexporter/master/assets/grafana.png "Grafana dashboard sample")

![UPS Grafana dashboard sample](https://raw.githubusercontent.com/pedropombeiro/qnapexporter/master/assets/ups.png "UPS Grafana dashboard sample")

The Grafana dashboard sources are in the `/dashboards` directory.

## Installation (from binaries)

1. Download the latest qnapexporter executable from the [Releases page](https://github.com/pedropombeiro/qnapexporter/releases)
1. Run `qnapexporter`

```shell
   ./qnapexporter
   ```

Normally it should be run as a background task. Unfortunately this is not easy on a QNAP NAS.
   See for example [this forum post](https://forum.qnap.com/viewtopic.php?t=44743#p198192) for ideas on how to achieve it.

## Installation (via QNAP App Center repository)

The easiest way to install and keep `qnapexporter` up to date is via the built-in App Center repository support:

1. In the QNAP web UI, open **App Center**.
1. Click the settings/gear icon and select **App Repository**.
1. Click **Add** and enter the following URL:

```
   https://pedropombeiro.github.io/qnapexporter/repo.xml
   ```

1. Click **OK**. `QNAP Exporter` will now appear in App Center and can be installed and updated from there.

> **Note:** If you previously installed `qnapexporter` manually (from a downloaded `.qpkg`), you must uninstall that copy first. App Center treats the manually-installed package and the repository package as separate entries and will not upgrade one into the other.

## Installation (alternative, from qpkg)

1. Download the latest qnapexporter qpkg package from the [Releases page](https://github.com/pedropombeiro/qnapexporter/releases)
1. Via web ui in QNAP, use manual installation in App Center. Please note that the installation will issue a warning because the QPKG package is not signed. When the binary is installed via QPKG, it will automatically start as background task and can be also stopped/started via App Center.

## Building from source

### Prerequisites

- [Go](https://golang.org/) 1.25+
- [mise](https://mise.jdx.dev/) (version management & task automation)
- [hk](https://hk.jdx.dev/) (git hook manager, provided via mise)
- [golangci-lint](https://golangci-lint.run/) (linting, provided via mise)

### Setup

Install dependencies:

```bash
mise run install
```

This will run `mise install` to set up Go and project dependencies.

### Development Commands

- `mise run build` - Build the binary (output: `./bin/qnapexporter`)
- `mise run test` - Run all tests
- `mise run test -- -v -cover` - Run tests with verbose output and coverage
- `mise run lint` - Run golangci-lint checks
- `mise run fix` - Run formatters and auto-fixable linters
- `mise run mocks` - Generate test mocks
- `mise run vendor` - Update vendored dependencies
- `mise run clean` - Remove build artifacts
- `mise run info` - Display build metadata
- `mise tasks` - List all available commands

### Git Hooks

This repo uses [hk](https://hk.jdx.dev/) as its git hook manager. Enable the
hooks with:

```bash
mise run install
```

This sets `core.hooksPath` to the tracked `.hk-hooks/` directory. Hooks then
run automatically on `git commit`, or manually with `mise run fix`.

## Prometheus configuration

Add target to `scrape_configs` section of `prometheus.ini`

```yaml
- job_name: "qnap"
  scrape_interval: 10s
  honor_labels: true
  static_configs:
    - targets: ["localhost:9094"]
```

## Customization

qnapexporter supports the following command line flags:

| Flag                   | Default value | Description                                                                                                |
| ---------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| `--port`               | `:9094`       | Address/port where to serve the metrics                                                                    |
| `--ping-target`        | `1.1.1.1`     | Host to periodically ping                                                                                  |
| `--healthcheck`        | N/A           | Healthcheck service to ping every 5 minutes (currently supported: `healthchecks.io:<check-id>`)            |
| `--grafana-url`        | N/A           | Grafana host (e.g.: https://grafana.example.com), also settable through `GRAFANA_URL` environment variable |
| `--grafana-auth-token` | N/A           | Grafana API token for annotations, also settable through `GRAFANA_AUTH_TOKEN` environment variable         |
| `--grafana-tags`       | `nas`         | List of Grafana tags for annotations, also settable through `GRAFANA_TAGS` environment variable            |
| `--log`                | N/A           | Path to log file (defaults to standard output), also settable through `LOG_FILE` environment variable      |

### Configuring support for QNAP events as Grafana annotations

qnapexporter can expose QNAP events as Grafana annotations, to make it easy to understand what is happening on the NAS. To configure the support:

1. Log in to the NAS web interface
2. Open `Notification Center`, then `Service Account and Device Pairing`
3. In the `SMS` tab, click the `Add SMSC Service` button
   1. In `SMS service provider`, select `custom`
   2. Set `Alias` to `qnapexporter`
   3. Set `URL template text` to `http://localhost:9094/notification?phone_number=@@PhoneNumber@@&text=@@Text@@`. Customize the port to match whatever is passed to `--port`.
   4. Confirm the settings.
4. In the Grafana web UI, go to `Configuration`, `API Keys`
   1. Press `Add API key`
   2. Set `Key name` to `qnapexporter`
   3. Set `Role` to `Editor`
   4. Press `Add`
   5. Take note of the created token (this will be passed to qnapexporter with `--grafana-auth-token`)

## Tips

The root endpoint exposes information about the current status of the program (useful for debugging):

![Status page](https://raw.githubusercontent.com/pedropombeiro/qnapexporter/master/assets/status.jpeg "Status page")

qnapexporter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README