{"id":13621422,"url":"https://github.com/xperimental/nextcloud-exporter","last_synced_at":"2025-10-09T12:09:20.489Z","repository":{"id":25345382,"uuid":"82425580","full_name":"xperimental/nextcloud-exporter","owner":"xperimental","description":"Prometheus exporter for Nextcloud servers.","archived":false,"fork":false,"pushed_at":"2025-10-04T18:11:54.000Z","size":570,"stargazers_count":261,"open_issues_count":4,"forks_count":39,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-10-04T18:22:01.463Z","etag":null,"topics":["hacktoberfest","monitoring","nextcloud","prometheus","prometheus-exporter"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xperimental.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-19T00:44:07.000Z","updated_at":"2025-10-04T18:11:57.000Z","dependencies_parsed_at":"2024-06-18T21:27:54.079Z","dependency_job_id":"ac976ac3-4081-46e4-a16f-688b6a07aca2","html_url":"https://github.com/xperimental/nextcloud-exporter","commit_stats":{"total_commits":98,"total_committers":13,"mean_commits":7.538461538461538,"dds":"0.19387755102040816","last_synced_commit":"05fb8eada3f983188b3810247014118d6d732c1d"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/xperimental/nextcloud-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fnextcloud-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fnextcloud-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fnextcloud-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fnextcloud-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xperimental","download_url":"https://codeload.github.com/xperimental/nextcloud-exporter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xperimental%2Fnextcloud-exporter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278357501,"owners_count":25973941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","monitoring","nextcloud","prometheus","prometheus-exporter"],"created_at":"2024-08-01T21:01:05.960Z","updated_at":"2025-10-09T12:09:20.455Z","avatar_url":"https://github.com/xperimental.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# nextcloud-exporter\n\nA [prometheus](https://prometheus.io) exporter for getting some metrics of a [Nextcloud](https://nextcloud.com/) server instance.\n\n## Installation\n\n### Docker Image\n\nThe preferred way to use `nextcloud-exporter` is by running the provided Docker image. It is currently provided on Docker Hub and GitHub Container Registry:\n\n- [`ghcr.io/xperimental/nextcloud-exporter`](https://github.com/xperimental/nextcloud-exporter/pkgs/container/nextcloud-exporter)\n- [`xperimental/nextcloud-exporter`](https://hub.docker.com/r/xperimental/nextcloud-exporter/)\n\nThe following tags are available:\n\n- `x.y.z` pointing to the release with that version\n- `latest` pointing to the most recent released version\n- `master` pointing to the latest build from the default branch\n\n### Pre-built binaries\n\nThe [releases](https://github.com/xperimental/nextcloud-exporter/releases) page contains pre-built binaries for AMD64 and ARM64 linux.\n\n### Build from Source\n\nIf you have a recent Go installation (see `go.mod` for the minimum version), Git and GNU Make, the following commands will check out the repository and compile the binary from source:\n\n```bash\ngit clone https://github.com/xperimental/nextcloud-exporter.git\ncd nextcloud-exporter\nmake\n```\n\nAfter this there should be a `nextcloud-exporter` binary in your current directory.\n\n## Client credentials\n\nThe exporter supports two different approaches for authenticating with the Nextcloud server:\n\n- Token authentication (needs Nextcloud 22 or newer)\n- Username and password\n\nIf you have Nextcloud 22 then using the token authentication is recommended, because it does not need a normal user account with admin privileges.\n\nIf both a token and username/password are specified in the configuration, the token will take precedence.\n\n### Token authentication\n\nNextcloud 22 and newer versions support \"token authentication\" for the serverinfo. That way, accessing this information does not need a normal user account with admin privileges. You can set the token to anything you like, but the recommendation is to set it to a long random number:\n\n```bash\n# Generate random value (for example using openssl)\nTOKEN=$(openssl rand -hex 32)\n# Set token (using the occ console application)\nocc config:app:set serverinfo token --value \"$TOKEN\"\n```\n\nYou can then use this generated token in the exported configuration instead of username and password.\n\n### Username and password authentication\n\nTo access the serverinfo API you will need the credentials of an admin user. It is recommended to create a separate user for that purpose. It's also possible for the exporter to generate an \"app password\", so that the real user password is never saved to the configuration. This also makes the exporter show up in the security panel of the user as a connected application.\n\nTo let the nextcloud-exporter create an app password, start it with the `--login` parameter:\n\n```bash\nnextcloud-exporter --login --server https://nextcloud.example.com\n```\n\nThe exporter will generate a login URL that you need to open in your browser. Be sure to login with the correct user if you created a special user for the exporter as the app password will be bound to the logged-in user. Once the access has been granted using the browser the exporter will output the username and password that need to be entered into the configuration.\n\nWhen the login process is done, it is possible to disable filesystem access for the generated token in the user's settings:\n\n![Allow filesystem access checkbox](contrib/allow-filesystem.png)\n\n---\n\nThe interactive login can also be done using a Docker container:\n\n```bash\ndocker run --rm -it ghcr.io/xperimental/nextcloud-exporter --login --server https://nextcloud.example.com\n```\n\nThe login flow needs at least Nextcloud 16 to work.\n\n## Usage\n\n```plain\n$ nextcloud-exporter --help\nUsage of nextcloud-exporter:\n  -a, --addr string          Address to listen on for connections. (default \":9205\")\n      --auth-token string    Authentication token. Can replace username and password when using Nextcloud 22 or newer.\n  -c, --config-file string   Path to YAML configuration file.\n      --enable-info-apps     Enable gathering of apps-related metrics.\n      --enable-info-update   Enable gathering of system update-related metrics.\n      --login                Use interactive login to create app password.\n  -p, --password string      Password for connecting to Nextcloud.\n  -s, --server string        URL to Nextcloud server.\n  -t, --timeout duration     Timeout for getting server info document. (default 5s)\n      --tls-skip-verify      Skip certificate verification of Nextcloud server.\n  -u, --username string      Username for connecting to Nextcloud.\n  -V, --version              Show version information and exit.\n```\n\nAfter starting the server will offer the metrics on the `/metrics` endpoint, which can be used as a target for prometheus.\n\n### Example Dashboard\n\nThe repository contains an [example Grafana dashboard](contrib/grafana-dashboard.json) that can be imported into Grafana. The dashboard is also available as ID `20716` from the [Grafana Dashboard Exchange](https://grafana.com/grafana/dashboards/20716-nextcloud/).\n\n### Configuration methods\n\nThere are three methods of configuring the nextcloud-exporter (higher methods take precedence over lower ones):\n\n- Environment variables\n- Configuration file\n- Command-line parameters\n\n#### Environment variables\n\nAll settings can also be specified through environment variables:\n\n|        Environment variable | Flag equivalent      |\n|----------------------------:|:---------------------|\n|          `NEXTCLOUD_SERVER` | --server             |\n|        `NEXTCLOUD_USERNAME` | --username           |\n|        `NEXTCLOUD_PASSWORD` | --password           |\n|      `NEXTCLOUD_AUTH_TOKEN` | --auth-token         |\n|  `NEXTCLOUD_LISTEN_ADDRESS` | --addr               |\n|         `NEXTCLOUD_TIMEOUT` | --timeout            |\n| `NEXTCLOUD_TLS_SKIP_VERIFY` | --tls-skip-verify    |\n|       `NEXTCLOUD_INFO_APPS` | --enable-info-apps   |\n|     `NEXTCLOUD_INFO_UPDATE` | --enable-info-update |\n\n#### Configuration file\n\nThe `--config-file` option can be used to read the configuration options from a YAML file:\n\n```yaml\n# required\nserver: \"https://example.com\"\n# required for token authentication\nauthToken: \"example-token\"\n# required for username/password authentication\nusername: \"example\"\npassword: \"example\"\n# optional\nlistenAddress: \":9205\"\ntimeout: \"5s\"\ntlsSkipVerify: false\ninfo:\n  apps: false\n  update: false\n```\n\n### Loading Credentials from Files\n\nBoth the authentication token and the password can optionally be read from a separate file instead of directly from the input methods above.\n\nThis can be achieved by setting the value to the path of the file prefixed with an \"@\", for example:\n\n```bash\n# Authentication token\nnextcloud-exporter -c config-without-token.yml --auth-token @/path/to/tokenfile\n# Password\nnextcloud-exporter -c config-without-password.yml -p @/path/to/passwordfile\n```\n\nThis also works when the password or token is set using one of the other configuration modes (configuration file or environment variables).\n\n## Other information\n\n### Info URL\n\nThe exporter reads the metrics from the Nextcloud server using its \"serverinfo\" API. You can find the URL of this API in the administrator settings in the \"Monitoring\" section. It should look something like this:\n\n```plain\nhttps://example.com/ocs/v2.php/apps/serverinfo/api/v1/info\n```\n\nThe path will be automatically added to the server URL you provide, so in the above example setting `--server https://example.com` would be sufficient.\n\nIf you open this URL in a browser you should see an XML structure with the information that will be used by the exporter.\n\n### Scrape configuration\n\nThe exporter will query the nextcloud server every time it is scraped by prometheus. If you want to reduce load on the nextcloud server you need to change the scrape interval accordingly:\n\n```yml\nscrape_configs:\n  - job_name: 'nextcloud'\n    scrape_interval: 90s\n    static_configs:\n      - targets: ['localhost:9205']\n```\n\n### Exported metrics\n\nThese metrics are exported by `nextcloud-exporter`:\n\n| name                                   | description                                                                                                                                                                                                                                        |\n|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| nextcloud_active_users_daily_total     | Number of active users in the last 24 hours                                                                                                                                                                                                        |\n| nextcloud_active_users_hourly_total    | Number of active users in the last hour                                                                                                                                                                                                            |\n| nextcloud_active_users_total           | Number of active users for the last five minutes                                                                                                                                                                                                   |\n| nextcloud_apps_installed_total         | Number of currently installed apps                                                                                                                                                                                                                 |\n| nextcloud_apps_updates_available_total | Number of apps that have available updates                                                                                                                                                                                                         |\n| nextcloud_database_info                | Contains meta information about the database as labels. Value is always 1.                                                                                                                                                                         |\n| nextcloud_database_size_bytes          | Size of database in bytes as reported from engine                                                                                                                                                                                                  |\n| nextcloud_exporter_info                | Contains meta information of the exporter. Value is always 1.                                                                                                                                                                                      |\n| nextcloud_files_total                  | Number of files served by the instance                                                                                                                                                                                                             |\n| nextcloud_free_space_bytes             | Free disk space in data directory in bytes                                                                                                                                                                                                         |\n| nextcloud_php_info                     | Contains meta information about PHP as labels. Value is always 1.                                                                                                                                                                                  |\n| nextcloud_php_memory_limit_bytes       | Configured PHP memory limit in bytes                                                                                                                                                                                                               |\n| nextcloud_php_upload_max_size_bytes    | Configured maximum upload size in bytes                                                                                                                                                                                                            |\n| nextcloud_scrape_errors_total          | Counts the number of scrape errors by this collector                                                                                                                                                                                               |\n| nextcloud_shares_federated_total       | Number of federated shares by direction `sent` / `received`                                                                                                                                                                                        |\n| nextcloud_shares_total                 | Number of shares by type: \u003cbr\u003e `authlink`: shared password protected links \u003cbr\u003e `group`: shared groups \u003cbr\u003e`link`: all shared links \u003cbr\u003e `user`: shared users \u003cbr\u003e `mail`: shared by mail \u003cbr\u003e `room`: shared with room                            |\n| nextcloud_system_info                  | Contains meta information about Nextcloud as labels. Value is always 1.                                                                                                                                                                            |\n| nextcloud_system_update_available      | Contains information whether a system update is available: \u003cbr\u003e`0`: no update available\u003cbr\u003e`1`: nextcloud update available\u003cbr\u003eIn case of 1=yes, `available_version` label contains the new version. This metric is only available if  activated.   |\n| nextcloud_up                           | Indicates if the metrics could be scraped by the exporter: \u003cbr\u003e`1`: successful\u003cbr\u003e`0`: unsuccessful (server down, server/endpoint not reachable, invalid credentials, ...)                                                                         |\n| nextcloud_users_total                  | Number of users of the instance                                                                                                                                                                                                                    |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxperimental%2Fnextcloud-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxperimental%2Fnextcloud-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxperimental%2Fnextcloud-exporter/lists"}