mirror of https://github.com/borgbackup/borg.git
commit
0e3560b6cd
|
@ -31,3 +31,4 @@ hash-table of all chunks that already exist.
|
||||||
|
|
||||||
internals/security
|
internals/security
|
||||||
internals/data-structures
|
internals/data-structures
|
||||||
|
internals/frontends
|
||||||
|
|
|
@ -0,0 +1,159 @@
|
||||||
|
.. include:: ../global.rst.inc
|
||||||
|
.. highlight:: none
|
||||||
|
|
||||||
|
.. _json_output:
|
||||||
|
|
||||||
|
All about JSON: How to develop frontends
|
||||||
|
========================================
|
||||||
|
|
||||||
|
Borg does not have a public API on the Python level. That does not keep you from writing :code:`import borg`,
|
||||||
|
but does mean that there are no release-to-release guarantees on what you might find in that package, not
|
||||||
|
even for point releases (1.1.x), and there is no documentation beyond the code and the internals documents.
|
||||||
|
|
||||||
|
Borg does on the other hand provide an API on a command-line level. In other words, a frontend should to
|
||||||
|
(for example) create a backup archive just invoke :ref:`borg_create`.
|
||||||
|
|
||||||
|
Logging
|
||||||
|
-------
|
||||||
|
|
||||||
|
Especially for graphical frontends it is important to be able to convey and reformat progress information
|
||||||
|
in meaningful ways. The ``--log-json`` option turns the stderr stream of Borg into a stream of JSON lines,
|
||||||
|
where each line is a JSON object. The *type* key of the object determines its other contents.
|
||||||
|
|
||||||
|
Since JSON can only encode text, any string representing a file system path may miss non-text parts.
|
||||||
|
|
||||||
|
The following types are in use:
|
||||||
|
|
||||||
|
archive_progress
|
||||||
|
Output during operations creating archives (:ref:`borg_create` and :ref:`borg_recreate`).
|
||||||
|
The following keys exist, each represents the current progress.
|
||||||
|
|
||||||
|
original_size
|
||||||
|
Original size of data processed so far (before compression and deduplication)
|
||||||
|
compressed_size
|
||||||
|
Compressed size
|
||||||
|
deduplicated_size
|
||||||
|
Deduplicated size
|
||||||
|
nfiles
|
||||||
|
Number of (regular) files processed so far
|
||||||
|
path
|
||||||
|
Current path
|
||||||
|
|
||||||
|
file_status
|
||||||
|
This is only output by :ref:`borg_create` and :ref:`borg_recreate` if ``--list`` is specified. The usual
|
||||||
|
rules for the file listing applies, including the ``--filter`` option.
|
||||||
|
|
||||||
|
status
|
||||||
|
Single-character status as for regular list output
|
||||||
|
path
|
||||||
|
Path of the file system object
|
||||||
|
|
||||||
|
log_message
|
||||||
|
Any regular log output invokes this type. Regular log options and filtering applies to these as well.
|
||||||
|
|
||||||
|
created
|
||||||
|
Unix timestamp (float)
|
||||||
|
levelname
|
||||||
|
Upper-case log level name (also called severity). Defined levels are: DEBUG, INFO, WARNING, CRITICAL
|
||||||
|
name
|
||||||
|
Name of the emitting entity
|
||||||
|
message
|
||||||
|
Formatted log message
|
||||||
|
|
||||||
|
Standard output
|
||||||
|
---------------
|
||||||
|
|
||||||
|
*stdout* is different and more command-dependent. Commands like :ref:`borg_info`, :ref:`borg_create`
|
||||||
|
and :ref:`borg_list` implement a ``--json`` option which turns their regular output into a single JSON object.
|
||||||
|
|
||||||
|
Dates are formatted according to ISO-8601 with the strftime format string '%a, %Y-%m-%d %H:%M:%S',
|
||||||
|
e.g. *Sat, 2016-02-25 23:50:06*.
|
||||||
|
|
||||||
|
The root object at least contains a *repository* key with an object containing:
|
||||||
|
|
||||||
|
id
|
||||||
|
The ID of the repository, normally 64 hex characters
|
||||||
|
location
|
||||||
|
Canonicalized repository path, thus this may be different from what is specified on the command line
|
||||||
|
last_modified
|
||||||
|
Date when the repository was last modified by the Borg client
|
||||||
|
|
||||||
|
The *encryption* key, if present, contains:
|
||||||
|
|
||||||
|
mode
|
||||||
|
Textual encryption mode name (same as :ref:`borg_init` ``--encryption`` names)
|
||||||
|
keyfile
|
||||||
|
Path to the local key file used for access. Depending on *mode* this key may be absent.
|
||||||
|
|
||||||
|
The *cache* key, if present, contains:
|
||||||
|
|
||||||
|
path
|
||||||
|
Path to the local repository cache
|
||||||
|
stats
|
||||||
|
Object containing cache stats:
|
||||||
|
|
||||||
|
total_chunks
|
||||||
|
Number of chunks
|
||||||
|
total_unique_chunks
|
||||||
|
Number of unique chunks
|
||||||
|
total_size
|
||||||
|
Total uncompressed size of all chunks multiplied with their reference counts
|
||||||
|
total_csize
|
||||||
|
Total compressed and encrypted size of all chunks multiplied with their reference counts
|
||||||
|
unique_size
|
||||||
|
Uncompressed size of all chunks
|
||||||
|
unique_csize
|
||||||
|
Compressed and encrypted size of all chunks
|
||||||
|
|
||||||
|
.. rubric:: Archive formats
|
||||||
|
|
||||||
|
:ref:`borg_info` uses an extended format for archives, which is more expensive to retrieve, while
|
||||||
|
:ref:`borg_list` uses a simpler format that is faster to retrieve. Either return archives in an
|
||||||
|
array under the *archives* key, while :ref:`borg_create` returns a single archive object under the
|
||||||
|
*archive* key.
|
||||||
|
|
||||||
|
Both formats contain a *name* key with the archive name, and the *id* key with the hexadecimal archive ID.
|
||||||
|
|
||||||
|
info and create further have:
|
||||||
|
|
||||||
|
start
|
||||||
|
Start timestamp
|
||||||
|
end
|
||||||
|
End timestamp
|
||||||
|
duration
|
||||||
|
Duration in seconds between start and end in seconds (float)
|
||||||
|
stats
|
||||||
|
Archive statistics (freshly calculated, this is what makes "info" more expensive)
|
||||||
|
|
||||||
|
original_size
|
||||||
|
Size of files and metadata before compression
|
||||||
|
compressed_size
|
||||||
|
Size after compression
|
||||||
|
deduplicated_size
|
||||||
|
Deduplicated size (against the current repository, not when the archive was created)
|
||||||
|
nfiles
|
||||||
|
Number of regular files in the archive
|
||||||
|
limits
|
||||||
|
Object describing the utilization of Borg limits
|
||||||
|
|
||||||
|
max_archive_size
|
||||||
|
Float between 0 and 1 describing how large this archive is relative to the maximum size allowed by Borg
|
||||||
|
command_line
|
||||||
|
Array of strings of the command line that created the archive
|
||||||
|
|
||||||
|
The note about paths from above applies here as well.
|
||||||
|
|
||||||
|
:ref:`borg_info` further has:
|
||||||
|
|
||||||
|
hostname
|
||||||
|
Hostname of the creating host
|
||||||
|
username
|
||||||
|
Name of the creating user
|
||||||
|
comment
|
||||||
|
Archive comment, if any
|
||||||
|
|
||||||
|
.. rubric:: File listings
|
||||||
|
|
||||||
|
Listing the contents of an archive can produce *a lot* of JSON. Each item (file, directory, ...) is described
|
||||||
|
by one object in the *files* array of the :ref:`borg_list` output. Refer to the *borg list* documentation for
|
||||||
|
the available keys and their meaning.
|
|
@ -15,7 +15,8 @@ General
|
||||||
.. include:: usage_general.rst.inc
|
.. include:: usage_general.rst.inc
|
||||||
|
|
||||||
In case you are interested in more details (like formulas), please see
|
In case you are interested in more details (like formulas), please see
|
||||||
:ref:`internals`.
|
:ref:`internals`. For details on the available JSON output, refer to
|
||||||
|
:ref:`json_output`.
|
||||||
|
|
||||||
Common options
|
Common options
|
||||||
++++++++++++++
|
++++++++++++++
|
||||||
|
|
Loading…
Reference in New Issue