The snapcraft metrics command is used to track installation and usage statistics for snaps published with your developer account.
A selection of metrics are also visible from the Snap Store web UI. See Snap Store metrics for details.
To ensure you have the correct and updated permissions to access metrics, we recommend using snapcraft logout and snapcraft login the first time this feature is used. See Credentials for more details.
Usage
The snapcraft metrics command takes the following arguments:
snapcraft metrics <snap-name> --name <metric-name> \
--start <start-date> --end <end-date> [--format=(json|table)]
| Parameter | Required/Optional | Type | Description |
|---|---|---|---|
<snap-name> |
required | string | Name of snap. |
name |
required | string | Name of supported metric (see below). |
start |
optional | string of format YYYY-MM-DD | Start of date range to request (must not be later than today’s date). Defaults to yesterday. |
end |
optional | string of format YYYY-MM-DD | End (inclusive) of date range to request (must not be later than today’s date). Defaults to yesterday. |
format |
required | string | Output format. |
Supported metrics
The following metrics (<metric-name>) are supported:
- daily_device_change: contains the 3 series representing the number of new, continued and lost devices with the given snap installed compared to the previous day.
- installed_base_by_channel: contains one series per channel representing the number of devices with the given snap installed, channels with no data across the entire interval are omitted.
- installed_base_by_country: contains one series per country representing the number of devices with the given snap installed.
- installed_base_by_operating_system: contains one series per operating_system representing the number of devices with the given snap installed.
- installed_base_by_version: contains one series per version representing the number of devices with the given snap installed.
- installed_base_by_architecture: contains one series per architecture representing the number of devices with the given snap installed.
- weekly_device_change: similar to the ‘daily_device_change’ metric but operates on a 7 day window. i.e. new contains the number of devices that were seen during the last 7 days but not in the previous 7 day and so on for continued and lost.
- weekly_installed_base_by_channel: similar to the installed_base_by_channel metric but operates in a 7 day window.
- weekly_installed_base_by_country: similar to the installed_base_by_country metric but operates in a 7 day window.
- weekly_installed_base_by_operating_system: similar to the installed_base_by_operating_system metric but operates in a 7 day window.
- weekly_installed_base_by_version: similar to the installed_base_by_version metric but operates in a 7 day window.
- weekly_installed_base_by_architecture: similar to the installed_base_by_architecture metric but operates in a 7 day window.
Each metric has a query that includes a start and end date. The returned data, if available, will include all the days in-between. Weekly installed numbers still generated daily with the provided numbers being the averages for the 7 day window ending on the specified day.
Output format
The snapcraft metrics command outputs either as JSON string or a table.
JSON output
When using --format=json, a JSON string matching the response from the Snap Store API server for the given metric is output.
This output is driven and provided by the Snap Store API and may be extended in the future.
Example daily_device_change output:
$ snapcraft metrics my-snap --name daily_device_change \
--start 2021-07-01 --end 2021-07-01 --format=json
{'buckets': ['2021-07-01'], 'metric_name': 'daily_device_change',
'series': [{'name': 'continued', 'values': [66]}, {'name': 'lost', 'values': [55]},
{'name': 'new', 'values': [77]}], 'snap_id': '<snap-id>', 'status': 'OK'}
If the JSON object returned from the API is response, snapcraft will output the pertinent data at response["metrics"][0]. The relevant API documentation can be found on dashboard.snapcraft.io.
Table output
When using --format=table, a table-based interpretation of the returned data, with columns for the requested date ranges and rows of the requested data series, is output.
As the output for most queries will be large, a pager is used to make the output more easily navigable. It is recommended that the user output this to a file and use an editor of choice.
if the query returns with a “None” data point, it is replaced with a “-” to indicate zero (or not applicable depending on context).
Example table output
Example daily_device_change output:
$ snapcraft metrics my-snap --name daily_device_change \
--start 2021-07-01 --end 2021-07-01 --format=table
Devices 2021-07-01
Continued 49
Lost 21
New 19
Example installed_base_by_channel output:
$ snapcraft metrics my-snap --name installed_base_by_channel \
--start 2021-07-01 --end 2021-07-01 --format=table
Channel 2021-07-01 2021-07-02 2021-07-03
Beta 245 255 240
Candidate 1 1 0
Edge 68 78 85
Stable 401 405 409
Example installed_base_by_country output:
$ snapcraft metrics my-snap --name installed_base_by_country \
--start 2021-07-01 --end 2021-07-01 --format=table
Country 2021-07-01 2021-07-02 2021-07-03
Ar 6 6 6
At 2 2 1
Au 6 6 3
Be 3 3 2
Bg 1 2 1
Br 14 14 10
Ca 12 13 12
Ch 3 3 2
Cl 0 1 1
Cn 3 2 2
Co 1 1 1
Cy 1 1 0
Cz 1 1 0
De 12 9 10
Dk 1 2 1
Es 9 10 8
Fi 1 1 1
Fr 8 8 8
Gb 30 27 21
Ge 0 1 1
Gr 4 4 3
Hk 1 1 1
Hu 3 2 2
Id 1 1 1
Ie 2 2 2
Im 3 3 3
In 12 12 11
It 6 9 4
Jp 1 1 1
Ke 1 1 1
Lt 1 0 0
Nl 4 4 6
None 50 48 31
Np 1 0 0
Nz 2 3 3
Pk 2 2 1
Pl 5 5 4
Pt 5 5 3
Qa 1 1 1
Ro 1 1 1
Ru 5 5 5
Se 8 7 6
Sg 2 2 2
Sk 4 2 2
Tr 6 5 6
Tw 5 5 5
Us 53 44 39
Uy 2 2 2
Vn 1 0 0
Example installed_base_by_operating_system output:
$ snapcraft metrics my-snap --name installed_base_by_operating_system --start 2021-07-01 --end 2021-07-01 --format=table
OS 2021-07-01 2021-07-02 2021-07-03
Arch/ 2 1 1
Centos/7 2 2 2
Debian/10 3 3 2
Elementary/5.1.7 2 2 2
Elementary/6 1 0 0
Fedora/34 1 1 1
Linuxmint/20.1 1 1 1
Manjaro/ 1 2 1
Pop/20.10 1 1 1
Pop/21.04 1 1 1
Ubuntu/16.04 10 10 11
Ubuntu/18.04 68 66 77
Ubuntu/19.04 1 1 0
Ubuntu/19.10 1 1 1
Ubuntu/20.04 255 260 250
Ubuntu/20.10 9 9 7
Ubuntu/21.04 88 92 99
Ubuntu/21.10 2 2 5
Example installed_base_by_version output:
$ snapcraft metrics my-snap --name installed_base_by_version --start 2021-07-01 --end
Version 2021-07-01 2021-07-02 2021-07-03
2.4.3 1 0 0
2.4.4 1 1 1
2.4.5 4 4 4
2.5.0 28 28 16
Handling credentials
The Snap Store metrics API, used by the snapcraft metrics command, requires the package_metrics permission granted for the given credentials of the current snapcraft user.
Any currently logged in user will not have this permission granted to their existing cached credentials. They will likely require re-authentication to obtain it. Future logins will not require re-authentication as Snapcraft will request this permission during all future logins.
If you see an error such as the following, it’s likely you need to use snapcraft logout followed by snapcraft login to refresh your credentials:
Errors:
- Code: macaroon-permission-required
Message: Permission "package_metrics" is required as a macaroon caveat.
Extra: {'permission': 'package_metrics'}