Metrics

Introduction

The Metrics App provides a building block for reporting of ownCloud Server. For simple use cases, it ships with an integrated dashboard that summarizes information about users, storage as well as shares and allows exporting it to a CSV file. Additionally, it adds a Metrics HTTP API endpoint to ownCloud Server, which can be used to obtain the Metrics data in regular intervals. Thus, more sophisticated analysis and visualizations can be conducted.

The Metrics data are provided as snapshot values in the JSON format and are optimized to be consumed by professional data analyzers (like Splunk, ELK or Prometheus/Grafana) to collect statistics, derive visualizations and to set alerts for certain events of interest. They can be perfectly combined with the ownCloud Audit Logs (provided by the Auditing App) to gather time series data and to create a reporting engine for ownCloud.

Internet Explorer 11 is not compatible with Metrics, because new web technologies have been used that are not supported by IE 11.

If you want to use Splunk in addition, check out ownCloud App for Splunk.

Specifically, the Metrics extension adds:

  • an API endpoint which allows querying snapshot values of the system data as well as per-user metrics

  • API endpoints for downloading metrics as CSV files

  • a dashboard that displays the snapshot data in the ownCloud Web UI and offers a CSV download in the system view and the user view.

If you’re operating very large instances with regard to users, files or shares, better use a special setup so you won’t put the production database under huge load when gathering the values. For this, replicate your installation (application server and read-only database) and install and use the Metrics app on the replica.

The following screenshots give you an impression of the Metrics app.

Figure 1. Metrics System Overview

Metrics System Overview

Figure 2. Metrics User Overview

Metrics User Overview

Available Data

The following data is available for analysis:

System data

  • Date/Time stamp - Server time of the request

  • Storage

    • Used storage (this includes both, data that count against user Quotas usedQuota, and usedOther like avatars, thumbnails and file versions)

    • Free storage

    • Total storage (used + free)

    • Number of files

  • Number of users

    • registered (total number of known users)

    • active (number of users with lastLogin less than two weeks ago)

    • concurrent (number of users with at least one active session)

  • Shares

    • Number of user shares

    • Number of group shares

    • Number of guest shares

    • Number of link shares

    • Number of federated shares

Per-user data

  • User ID

  • Display name

  • User backend

  • Last login

  • Active sessions

  • Quota

    • Quota limit

    • Quota usage

  • Number of files

  • Shares

    • Number of user shares

    • Number of group shares

    • Number of guest shares

    • Number of link shares

    • Number of federated shares

Usage

Authorization

To get started, you have to set a secret for authenticating requests at the endpoint.

See the following occ command on how to set it. Make up a passphrase, referred to as <your-metrics-secret> in the example below. The Metrics secret is necessary to use the dashboard.

sudo -u www-data ./occ config:system:set "metrics_shared_secret" --value "<your-metrics-secret>"
This token gets stored in config.php as metrics_shared_secret, which could also be done manually instead of using the occ command.

Dashboard User Interface

The dashboard is enabled by default. You can disable it with the following command:

sudo -u www-data ./occ config:app:set metrics disable_dashboard --value=yes

Endpoints and Parameters

Metrics Endpoint

To query for the Metrics data, use the following endpoint:

https://<your owncloud>/ocs/v1.php/apps/metrics/api/v1/metrics

  • URL Parameters

    • users=true

    • shares=true

    • quota=true

    • userData=true

    • format=json

  • Header "OC-MetricsApiKey: <your-metrics-secret>"

Except for the header, all other parameters are optional. You can split the query into parts by setting the respective parameters to false.

See the curl example to request the complete output:

curl -H "OC-MetricsApiKey: <your-metrics-secret>" \
     "https://<your owncloud>/ocs/v1.php/apps/metrics/api/v1/metrics?users=true&files=true&shares=true&quota=true&userData=true&format=json"
Replace <your-metrics-secret> with your respective system config value and <your owncloud> with the URL of your ownCloud instance.

CSV Download Endpoints

Downloading the current user and system metrics as CSV files is possible via the Web UI. If you want to set up cron jobs for downloading the metrics regularly without admin permissions, there are also public endpoints that require the configured token instead of admin privileges.

In the following curl examples, replace <your-metrics-secret> with your respective system config value and <your owncloud> with the URL of your ownCloud instance.

To receive user metrics, use:

curl -H "Content-Type: application/csv" \
     -H "OC-MetricsApiKey: <your-metrics-secret>" \
     -X GET https://<your owncloud>/index.php/apps/metrics/download-api/users > \
     /path/to/download/storage/user-metrics.csv

For system metrics, use:

curl -H "Content-Type: application/csv" \
     -H "OC-MetricsApiKey: <your-metrics-secret>" \
     -X GET https://<your owncloud>/index.php/apps/metrics/download-api/system > \
     /path/to/download/storage/system-metrics.csv

Limitations

The Metrics app was designed for ownCloud deployments up to 250 users. On deployments with more than 250 users, it can take considerably longer to gather the requested data. To reduce the time needed, exclude userData and quota.