systemd-report - Man Page

systemd-report [Options...]

Note: this command is experimental for now​. While it is likely to become a regular component of systemd, it might still change in behaviour and interface​.

systemd-report requests metrics from the system and writes them to standard output​.

The following commands are understood:

metrics [MATCH...]

Acquire a list of metrics values from all local services providing them, and write them to standard output​. Optionally takes one or more match expressions for filtering the metrics to show​. The expression either may be a literal metric family name to search for, or a prefix of one (which will be matched only at dot boundaries)​. If multiple matches are specified as multiple parameters, any metric matching any of the specified matches are shown​.

Added in version 260​.

describe [MATCH...]

Acquire a list of metric families from all local services providing them, and write them to standard output​. This returns primarily static information about metrics, their data types and human readable description, without values​.

Match expressions supported by metrics are supported by describe too​.

Added in version 260​.

generate [MATCH...]

Acquire a list of metrics and build a JSON report​.

Match expressions supported by metrics are supported here too​.

Added in version 261​.

upload [MATCH...]

This command can be used to send the report built by generate to an external server​. Two upload mechanisms are supported​. If an "http://" or "https://" URL is specified with --url=, an HTTP upload will be performed to the specified location​. Otherwise, any sockets under /run/systemd/report​.upload/ will be used to call io​.systemd​.Report​.Uploader​.Upload()​.

Match expressions supported by metrics are supported here too​.

Added in version 261​.

list-sources

Show list of known metrics sources​.

Added in version 260​.

The following options are understood:

--system,  --user

Query per-system metrics sources (the default), or the per-user metrics sources​.

Added in version 260​.

--no-pager

Do not pipe output into a pager​.

--json=MODE

Shows output formatted as JSON​. Expects one of "short" (for the shortest possible output without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, the default)​.

-j

Equivalent to --json=pretty if running on a terminal, and --json=short otherwise​.

--no-legend

Do not print the legend, i​.e​. column headers and the footer with hints​.

-h,  --help

Print a short help text and exit​.

--version

Print a short version string and exit​.

--url=URL

Upload the collected report to the specified address instead of writing it to standard output​. URL must point to a server accepting POST requests with a JSON-formatted report body​.

Note: both "http://" and "https://" URLs are supported, but connections over plain HTTP are made without encryption​. Thus, this mode should only be used in specific situations where integrity and confidentiality of the report is not required or is ensured through some other means​. Using "https://" is recommended​.

Added in version 261​.

--key=FILENAME

Takes a path to a SSL key file in PEM format, used for client certificate authentication when uploading​. Can also be set to "-", to disable client certificate authentication​. Defaults to /etc/ssl/private/systemd-report​.pem​.

Added in version 261​.

--cert=FILENAME

Takes a path to a SSL certificate file in PEM format, used for client certificate authentication when uploading​. Defaults to /etc/ssl/certs/systemd-report​.pem​.

Added in version 261​.

--trust=FILENAME|all

Takes a path to a SSL CA certificate file in PEM format used to verify the server certificate, or the literal string all to disable certificate checking entirely​. Defaults to /etc/ssl/ca/trusted​.pem​.

Added in version 261​.

--network-timeout=SEC

Timeout for the network upload operation​. Takes a value in seconds (or in other time units if suffixed with "ms", "min", "h", etc​.); see systemd.time(7) for details​. Defaults to 30 seconds​.

Added in version 261​.

--extra-header=NAME: VALUE

Inject an additional HTTP header into the upload request​. May be specified multiple times to add several headers​. Passing an empty string clears any headers added by previous --extra-header= uses​.

Added in version 261​.

--sign=MODE

Controls whether and how the report generated by generate or uploaded by upload is cryptographically signed​. Signatures are acquired by calling io​.systemd​.Report​.Signer​.Sign() on each socket found under /run/systemd/report​.sign/​.

When signing is requested (any value other than no) the report is emitted as a JSON-SEQ stream: the report object comes first, followed by one signature object per acquired signature (possibly none, in best-effort mode), each covering the precise binary representation of the report object​. With no the report is emitted as a single plain JSON object​. Takes one of the following values:

no

Do not sign the report; it is emitted as a single plain JSON object​. This is the default​.

Added in version 262​.

best-effort

Never fail because of signing​. Any acquired signatures are included​. The operation succeeds even if none could be acquired, in which case the JSON-SEQ stream simply contains no signature objects​.

Added in version 262​.

require-one

Require at least one signature​. Individual signers that fail or return no signature are tolerated, but the operation fails if not a single signature could be acquired​.

Added in version 262​.

require-all

Require every signer to succeed with at least one signature​. The operation fails if no signer is present, if any signer returns an error, or if any signer returns no signature​.

Added in version 262​.

Defaults to no​.

Added in version 262​.

On success, 0 is returned, a non-zero failure code otherwise​.

systemd(1)