| Name | borg-space JSON |
| Version |
2.2
JSON |
| download |
| home_page | |
| Summary | Accessory for Emborg used to report and track the size of your Borg repositories |
| upload_time | 2023-06-13 03:23:36 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | |
| keywords |
emborg
borg
backups
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
Borg-Space — Report and track the size of your Emborg repositories
==================================================================
.. image:: https://pepy.tech/badge/borg-space/month
:target: https://pepy.tech/project/borg-space
.. image:: https://img.shields.io/pypi/v/borg-space.svg
:target: https://pypi.python.org/pypi/borg-space
.. image:: https://img.shields.io/pypi/pyversions/borg-space.svg
:target: https://pypi.python.org/pypi/borg-space/
:Author: Ken Kundert
:Version: 2.2
:Released: 2023-06-12
*Borg-Space* is an accessory for Emborg_. It reports on the space consumed by
your *BorgBackup* repositories. You can get this information using the
``emborg info`` command, but there are several reasons to prefer *Borg-Space*.
#. *Borg-Space* is capable of reporting on many repositories at once.
#. The *Emborg* *info* command gives a great deal of information,
whereas *Borg-Space* only reports the space consumed by the repository,
so is much more compact.
#. The report is user customizable.
#. *Borg-Space* can record the size of your repositories each time it is run
so you can track the space requirements over time.
#. Finally, *Borg-Space* can graph the recorded values.
To show the size of one or more repositories, simply run::
# borg-space home
home: 12.81 GB
You can specify any number of repositories, and they can be composites. In the
following example, *home* is an alias that expands to *borgbase* and *rsync*::
> borg-space home cache
borgbase: 2.44 GB
cache: 801 MB
rsync: 2.81 GB
You can specify repositories that are owned by others or that are on remote
machines. In this case you will need permission to read the *Emborg* data
directory for the repository. Specifically,
❬host❭:~❬user❭/.local/share/emborg/❬config❭.latest.nt must be accessible.
❬config❭ is the name of the *Emborg* configuration to be reported on, ❬host❭ is
the name of the host on which the *Emborg create* command was run, and ❬user❭ is
the name of the user that ran the command.
To specify these repositories, a special naming scheme is used::
❬config❭@❬host❭~❬user❭
This is referred to as the full repository specification, or repository spec.
Both ``@❬host❭`` and ``~❬user❭`` are optional, ❬host❭ is not needed when
referring to the local host and ❬user❭ is not needed when referring to the
current user. Thus the *Emborg* configuration named *primary* owned by *root*
on the host with the SSH name *neptune* is accessed with::
# borg-space primary@neptune~root
primary@neptune~root: 57.74 GB
Usage
-----
*Borg-Space* supports the following command line arguments::
Usage:
borg-space [--quiet] [--style <style>] [--record] [<spec>...]
borg-space [--graph] [--svg <file>] [--log-y] [--record] [<spec>...]
Options:
-r, --record save the result
-q, --quiet do not output the size message
-s <style>, --style <style> the report style
choose from compact, table, tree, nt, json
-g, --graph graph the previously recorded sizes over time
-l, --log-y use a logarithmic Y-axis when graphing
-S <file>, --svg <file> produce plot as SVG file rather than display it
Repository specs take the form ``❬name❭`` or ``❬config❭[@❬host❭][~❬user❭]``.
Items in brackets are optional and ❬name❭ is the name given for a repository the
repositories setting.
The available styles are *compact*, *table*, *tree*, *nt* or *nestedtext*, or
*json*. If you specify something other than the these, what you give is taken
to be a *compact format* specification.
Results are saved to ~/.local/share/borg-space/<full_spec>.nt.
Settings are held in ~/.config/borg-space/settings.nt.
Settings
--------
You can create a NestedText_ settings file to specify default behaviors and
define composite repositories. For example::
default repository: home
report style: tree
compact format: {name}: {size:{fmt}}. Last back up: {last_create:ddd, MMM DD}. Last squeeze: {last_squeeze:ddd, MMM DD}.
table format: {host:<8} {user:<5} {config:<9} {size:<8.2b} {last_create:ddd, MMM DD}
table header: HOST USER CONFIG SIZE LAST BACK UP
report fields: size last_create last_squeeze
tree report fields: size
date format: D MMMM YYYY
size format: .b
repositories:
# define some convenient aliases
root: root~root
dev: root@dev~root
mail: root@mail~root
files: root@files~root
bastion: root@bastion~root
media: root@media~root
web: root@web~root
cluster: home@cluster
# define useful combinations
home:
children: rsync borgbase cluster
servers:
children:
- dev
- mail
- files
- bastion
- media
- web
all:
children: home servers root
default repository:
The name of the repository to be used if none are given on the command line.
report style:
The report style to be used if none is specified on the command line.
Choose from *compact*, *table*, *tree*, *nestedtext* or *nt*, or *json*.
compact format:
The format to be used for the line when the requested report style is
*compact*. The *name*, *spec*, *full_spec*, *config*, *host*, *user*,
*size*, *fmt*, *last_create*, *last_prune*, *last_compact* and
*last_squeeze* fields are replaced by the corresponding values. *name* is
the name given the repository in the *repositories* setting. *spec* is the
specification given as specified, and *full_spec* is the full specification
(any pieces missing from *spec* are filled in). If a name is not available,
*name* becomes the same as *spec*. *last_squeeze* is simply the later of
*last_prune* and *last_compact*. *size* is a QuantiPhy_ *Quantity* and the
*last_* fields are all Arrow_ objects (see the example in the next section
for examples on how to specify formatting on *QuantiPhy* and *Arrow*
objects). The remaining field values are strings.
The default is::
{name}: {size:{fmt}}
table format:
The format to be used for the line when the requested report style is
*table*. The *name*, *spec*, *host*, *user*, *config*, *size*, *fmt*,
*last_create*, *last_prune*, *last_compact* and *last_squeeze* fields will
be replaced by the corresponding values. *last_squeeze* is simply the later
of *last_prune* and *last_compact*. *size* is a QuantiPhy_ *Quantity* and
the *last_* fields are all Arrow_ objects. The remaining field values are
strings.
The default is::
{host:8} {user:8} {config:8} {size:<8.2b} {last_create:ddd, MMM DD}
table header:
The header to be printed just before the table report. It is used to give
column headers. Leave empty to suppress the header.
The default is::
HOST USER CONFIG SIZE LAST BACK UP
report fields:
The fields to include in *tree*, *nestedtext* and *json* style reports by
default. Default is *size*, *last_create*, and *last_squeeze*.
tree report fields:
The fields to include in *tree* style reports. If not given it defaults to
the value of *report fields*.
nestedtext report fields:
The fields to include in *nestedtext* style reports. If not given it
defaults to the value of *report fields*.
json report fields:
The fields to include in *json* style reports. If not given it defaults to
all available size and date fields.
size format:
The format to be used when giving the size of the repository. This is
a QuantiPhy_ format string. In the example, ``.2b`` means that a binary
format with two extra digits is used (one digit is required. so ``.2b``
prints with three digits of precision. If not given, it defaults to
``.2b``.
date format:
The Arrow_ format to be used for the date when the requested report style is
*tree* or *nestedtext*. If not given, it defaults to ``D MMMM YYYY``.
repositories:
Defines repository aliases and composite repositories. Given as
a collection of name:value pairs. The value may contain zero or more
repository specifications. The specifications may be a strings or
dictionaries. The following forms are accepted::
repositiories:
home:
# home becomes an alias for home on localhost for current user
repositiories:
home: home-primary
# home becomes an alias for home-primary on localhost for current user
repositiories:
home: home@host~user
# home becomes an alias for home@host~user
repositiories:
home:
# home becomes an alias for home@host~user
config: home
host: host
user: user
repositiories:
all: home@host~user work@host~user
# all contains home@host~user and work@host~user
repositiories:
all:
# all contains home@host~user and work@host~user
- home@host~user
- work@host~user
repositiories:
all:
# all contains home@host~user and work@host~user
-
config: home
host: host
user: user
-
config: work
host: host
user: user
repositiories:
home: home@host~user
# home becomes an alias for home@host~user
work: work@host~user
# work becomes an alias for work@host~user
all: home work
# all contains home and work
Graphing
--------
To graph the size of a repository over time you must first routinely record its
size. You can record the sizes with::
> borg-space -r home
The sizes are added to the file ``~/.local/share/borg-space/❬full_spec❭.nt``.
Typically you do not manually run *Borg-Space* to record the sizes of your
repositories. Instead, you can record sizes automatically in two different
ways. In the first, you simply use crontab to automatically record the sizes at
fixed times::
00 12 * * * borg-space -q -r home
In this case the command runs at noon every day and uses the ``-q`` option to
suppress the output to stdout. This approach can be problematic if *Emborg*
needs access to SSH or GPG keys to run.
The other approach is to add *Borg-Space* to the *run_after_backup* setting in
your *Emborg* configs. That way it is run every time you run backup::
run_after_backup = [
'borg-space -r {config_name}'
]
Once you have recorded some values, you can graph them using::
> borg-space -g home
This displays the graph on the screen. Alternately, you can save the graph to
a file in SVG format using::
> borg-space -S home.svg home
I routinely monitor the repositories for over a dozen hosts, and to make it
convenient I create a composite *Emborg* configuration containing all the hosts,
and then use the ``--log-y`` option so that I can easily see all the results
scaled nicely on the same graph::
> borg-space -l all
Installation
------------
*Borg-Space* requires *Emborg* version 1.37 or newer.
Install with::
> pip3 install borg-space
.. _emborg: https://emborg.readthedocs.io
.. _nestedtext: https://nestedtext.org
.. _arrow: https://arrow.readthedocs.io/en/latest/guide.html#supported-tokens
.. _quantiphy: https://quantiphy.readthedocs.io/en/stable/api.html#quantiphy.Quantity.format
Raw data
{
"_id": null,
"home_page": "",
"name": "borg-space",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "emborg,borg,backups",
"author": "",
"author_email": "Ken Kundert <emborg@nurdletech.com>",
"download_url": "https://files.pythonhosted.org/packages/9c/df/ca04e75ae4591c098dd2e54e01f1ef5d83106281e40b47eed9f09c3c4182/borg_space-2.2.tar.gz",
"platform": null,
"description": "Borg-Space \u2014 Report and track the size of your Emborg repositories\n==================================================================\n\n.. image:: https://pepy.tech/badge/borg-space/month\n :target: https://pepy.tech/project/borg-space\n\n.. image:: https://img.shields.io/pypi/v/borg-space.svg\n :target: https://pypi.python.org/pypi/borg-space\n\n.. image:: https://img.shields.io/pypi/pyversions/borg-space.svg\n :target: https://pypi.python.org/pypi/borg-space/\n\n:Author: Ken Kundert\n:Version: 2.2\n:Released: 2023-06-12\n\n*Borg-Space* is an accessory for Emborg_. It reports on the space consumed by \nyour *BorgBackup* repositories. You can get this information using the\n``emborg info`` command, but there are several reasons to prefer *Borg-Space*.\n\n#. *Borg-Space* is capable of reporting on many repositories at once.\n#. The *Emborg* *info* command gives a great deal of information,\n whereas *Borg-Space* only reports the space consumed by the repository,\n so is much more compact.\n#. The report is user customizable.\n#. *Borg-Space* can record the size of your repositories each time it is run\n so you can track the space requirements over time.\n#. Finally, *Borg-Space* can graph the recorded values.\n\nTo show the size of one or more repositories, simply run::\n\n # borg-space home\n home: 12.81 GB\n\nYou can specify any number of repositories, and they can be composites. In the \nfollowing example, *home* is an alias that expands to *borgbase* and *rsync*::\n\n > borg-space home cache\n borgbase: 2.44 GB\n cache: 801 MB\n rsync: 2.81 GB\n\nYou can specify repositories that are owned by others or that are on remote \nmachines. In this case you will need permission to read the *Emborg* data \ndirectory for the repository. Specifically, \n\u276chost\u276d:~\u276cuser\u276d/.local/share/emborg/\u276cconfig\u276d.latest.nt must be accessible.\n\u276cconfig\u276d is the name of the *Emborg* configuration to be reported on, \u276chost\u276d is \nthe name of the host on which the *Emborg create* command was run, and \u276cuser\u276d is \nthe name of the user that ran the command.\n\nTo specify these repositories, a special naming scheme is used::\n\n \u276cconfig\u276d@\u276chost\u276d~\u276cuser\u276d\n\nThis is referred to as the full repository specification, or repository spec. \nBoth ``@\u276chost\u276d`` and ``~\u276cuser\u276d`` are optional, \u276chost\u276d is not needed when \nreferring to the local host and \u276cuser\u276d is not needed when referring to the \ncurrent user. Thus the *Emborg* configuration named *primary* owned by *root* \non the host with the SSH name *neptune* is accessed with::\n\n # borg-space primary@neptune~root\n primary@neptune~root: 57.74 GB\n\n\nUsage\n-----\n\n*Borg-Space* supports the following command line arguments::\n\n Usage:\n borg-space [--quiet] [--style <style>] [--record] [<spec>...]\n borg-space [--graph] [--svg <file>] [--log-y] [--record] [<spec>...]\n\n Options:\n -r, --record save the result\n -q, --quiet do not output the size message\n -s <style>, --style <style> the report style\n choose from compact, table, tree, nt, json\n -g, --graph graph the previously recorded sizes over time\n -l, --log-y use a logarithmic Y-axis when graphing\n -S <file>, --svg <file> produce plot as SVG file rather than display it\n\nRepository specs take the form ``\u276cname\u276d`` or ``\u276cconfig\u276d[@\u276chost\u276d][~\u276cuser\u276d]``. \nItems in brackets are optional and \u276cname\u276d is the name given for a repository the\nrepositories setting.\n\nThe available styles are *compact*, *table*, *tree*, *nt* or *nestedtext*, or \n*json*. If you specify something other than the these, what you give is taken \nto be a *compact format* specification.\n\nResults are saved to ~/.local/share/borg-space/<full_spec>.nt.\nSettings are held in ~/.config/borg-space/settings.nt.\n\n\nSettings\n--------\n\nYou can create a NestedText_ settings file to specify default behaviors and \ndefine composite repositories. For example::\n\n default repository: home\n report style: tree\n compact format: {name}: {size:{fmt}}. Last back up: {last_create:ddd, MMM DD}. Last squeeze: {last_squeeze:ddd, MMM DD}.\n table format: {host:<8} {user:<5} {config:<9} {size:<8.2b} {last_create:ddd, MMM DD}\n table header: HOST USER CONFIG SIZE LAST BACK UP\n report fields: size last_create last_squeeze\n tree report fields: size\n date format: D MMMM YYYY\n size format: .b\n\n repositories:\n # define some convenient aliases\n root: root~root\n dev: root@dev~root\n mail: root@mail~root\n files: root@files~root\n bastion: root@bastion~root\n media: root@media~root\n web: root@web~root\n cluster: home@cluster\n\n # define useful combinations\n home:\n children: rsync borgbase cluster\n servers:\n children:\n - dev\n - mail\n - files\n - bastion\n - media\n - web\n all:\n children: home servers root\n\ndefault repository:\n The name of the repository to be used if none are given on the command line.\n\nreport style:\n The report style to be used if none is specified on the command line. \n Choose from *compact*, *table*, *tree*, *nestedtext* or *nt*, or *json*.\n\ncompact format:\n The format to be used for the line when the requested report style is \n *compact*. The *name*, *spec*, *full_spec*, *config*, *host*, *user*, \n *size*, *fmt*, *last_create*, *last_prune*, *last_compact* and \n *last_squeeze* fields are replaced by the corresponding values. *name* is \n the name given the repository in the *repositories* setting. *spec* is the \n specification given as specified, and *full_spec* is the full specification \n (any pieces missing from *spec* are filled in). If a name is not available, \n *name* becomes the same as *spec*. *last_squeeze* is simply the later of \n *last_prune* and *last_compact*. *size* is a QuantiPhy_ *Quantity* and the \n *last_* fields are all Arrow_ objects (see the example in the next section \n for examples on how to specify formatting on *QuantiPhy* and *Arrow* \n objects). The remaining field values are strings.\n\n The default is::\n\n {name}: {size:{fmt}}\n\ntable format:\n The format to be used for the line when the requested report style is \n *table*. The *name*, *spec*, *host*, *user*, *config*, *size*, *fmt*, \n *last_create*, *last_prune*, *last_compact* and *last_squeeze* fields will \n be replaced by the corresponding values. *last_squeeze* is simply the later \n of *last_prune* and *last_compact*. *size* is a QuantiPhy_ *Quantity* and \n the *last_* fields are all Arrow_ objects. The remaining field values are \n strings.\n\n The default is::\n\n {host:8} {user:8} {config:8} {size:<8.2b} {last_create:ddd, MMM DD}\n\ntable header:\n The header to be printed just before the table report. It is used to give \n column headers. Leave empty to suppress the header.\n\n The default is::\n\n HOST USER CONFIG SIZE LAST BACK UP\n\nreport fields:\n The fields to include in *tree*, *nestedtext* and *json* style reports by \n default. Default is *size*, *last_create*, and *last_squeeze*.\n\ntree report fields:\n The fields to include in *tree* style reports. If not given it defaults to \n the value of *report fields*.\n\nnestedtext report fields:\n The fields to include in *nestedtext* style reports. If not given it \n defaults to the value of *report fields*.\n\njson report fields:\n The fields to include in *json* style reports. If not given it defaults to \n all available size and date fields.\n\nsize format:\n The format to be used when giving the size of the repository. This is \n a QuantiPhy_ format string. In the example, ``.2b`` means that a binary \n format with two extra digits is used (one digit is required. so ``.2b`` \n prints with three digits of precision. If not given, it defaults to \n ``.2b``.\n\ndate format:\n The Arrow_ format to be used for the date when the requested report style is \n *tree* or *nestedtext*. If not given, it defaults to ``D MMMM YYYY``.\n\nrepositories:\n Defines repository aliases and composite repositories. Given as \n a collection of name:value pairs. The value may contain zero or more \n repository specifications. The specifications may be a strings or \n dictionaries. The following forms are accepted::\n\n repositiories:\n home:\n # home becomes an alias for home on localhost for current user\n\n repositiories:\n home: home-primary\n # home becomes an alias for home-primary on localhost for current user\n\n repositiories:\n home: home@host~user\n # home becomes an alias for home@host~user\n\n repositiories:\n home:\n # home becomes an alias for home@host~user\n config: home\n host: host\n user: user\n\n repositiories:\n all: home@host~user work@host~user\n # all contains home@host~user and work@host~user\n\n repositiories:\n all:\n # all contains home@host~user and work@host~user\n - home@host~user\n - work@host~user\n\n repositiories:\n all:\n # all contains home@host~user and work@host~user\n -\n config: home\n host: host\n user: user\n -\n config: work\n host: host\n user: user\n\n repositiories:\n home: home@host~user\n # home becomes an alias for home@host~user\n work: work@host~user\n # work becomes an alias for work@host~user\n all: home work\n # all contains home and work\n\n\nGraphing\n--------\n\nTo graph the size of a repository over time you must first routinely record its \nsize. You can record the sizes with::\n\n > borg-space -r home\n\nThe sizes are added to the file ``~/.local/share/borg-space/\u276cfull_spec\u276d.nt``.\n\nTypically you do not manually run *Borg-Space* to record the sizes of your\nrepositories. Instead, you can record sizes automatically in two different\nways. In the first, you simply use crontab to automatically record the sizes at\nfixed times::\n\n 00 12 * * * borg-space -q -r home\n\nIn this case the command runs at noon every day and uses the ``-q`` option to\nsuppress the output to stdout. This approach can be problematic if *Emborg*\nneeds access to SSH or GPG keys to run.\n\nThe other approach is to add *Borg-Space* to the *run_after_backup* setting in\nyour *Emborg* configs. That way it is run every time you run backup::\n\n run_after_backup = [\n 'borg-space -r {config_name}'\n ]\n\nOnce you have recorded some values, you can graph them using::\n\n > borg-space -g home\n\nThis displays the graph on the screen. Alternately, you can save the graph to \na file in SVG format using::\n\n > borg-space -S home.svg home\n\nI routinely monitor the repositories for over a dozen hosts, and to make it \nconvenient I create a composite *Emborg* configuration containing all the hosts, \nand then use the ``--log-y`` option so that I can easily see all the results \nscaled nicely on the same graph::\n\n > borg-space -l all\n\n\nInstallation\n------------\n\n*Borg-Space* requires *Emborg* version 1.37 or newer.\n\nInstall with::\n\n > pip3 install borg-space\n\n\n.. _emborg: https://emborg.readthedocs.io\n.. _nestedtext: https://nestedtext.org\n.. _arrow: https://arrow.readthedocs.io/en/latest/guide.html#supported-tokens\n.. _quantiphy: https://quantiphy.readthedocs.io/en/stable/api.html#quantiphy.Quantity.format\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Accessory for Emborg used to report and track the size of your Borg repositories",
"version": "2.2",
"project_urls": {
"changelog": "https://github.com/KenKundert/ntlog/blob/master/CHANGELOG.rst",
"documentation": "https://github.com/KenKundert/borg-space/blob/master/README.rst",
"homepage": "https://github.com/kenkundert/borg-space",
"repository": "https://github.com/kenkundert/borg-space"
},
"split_keywords": [
"emborg",
"borg",
"backups"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25d96b48c5da39126425b00b81105e9508aa75e70bb4992ae030085f7b8c44d7",
"md5": "6681084a034194933abfbd854bc7aaaf",
"sha256": "309e19005e83a284f91fec7aa085aa790fa7519b14bce9c04705a183d70fbf7b"
},
"downloads": -1,
"filename": "borg_space-2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6681084a034194933abfbd854bc7aaaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 25709,
"upload_time": "2023-06-13T03:23:34",
"upload_time_iso_8601": "2023-06-13T03:23:34.607916Z",
"url": "https://files.pythonhosted.org/packages/25/d9/6b48c5da39126425b00b81105e9508aa75e70bb4992ae030085f7b8c44d7/borg_space-2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9cdfca04e75ae4591c098dd2e54e01f1ef5d83106281e40b47eed9f09c3c4182",
"md5": "ff87c2bb63c213aa044f182e2c4f1102",
"sha256": "14f915e796cdf0956c9915ceb93d68162037072c5c74f948a9f38c6d8fb5ff92"
},
"downloads": -1,
"filename": "borg_space-2.2.tar.gz",
"has_sig": false,
"md5_digest": "ff87c2bb63c213aa044f182e2c4f1102",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 26737,
"upload_time": "2023-06-13T03:23:36",
"upload_time_iso_8601": "2023-06-13T03:23:36.720128Z",
"url": "https://files.pythonhosted.org/packages/9c/df/ca04e75ae4591c098dd2e54e01f1ef5d83106281e40b47eed9f09c3c4182/borg_space-2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-13 03:23:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KenKundert",
"github_project": "ntlog",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "borg-space"
}
