SYSTEMD-REPORT(1)

💖 systemd-report — the metrics gossip girl 💖

okay bestie, so systemd-report is a thing in the systemd family (that's systemd(1), the manual you already know and love) and it does exactly what the name says: it goes out, asks the system for metrics, and writes them to standard output. like a little reporter with a notepad. slay.

---

✨ SYNOPSIS ✨

systemd-report [OPTIONS...]

---

🧪 EXPERIMENTAL 🧪

⚠️ bestie. listen. this component is experimental and it can change without advance notice. it's gonna get stabilized and get a backward-compatibility guarantee in a future release, but it might also just… get removed?? 😭 no promises. so like, don't build your whole personality on it yet.

---

🌸 DESCRIPTION 🌸

systemd-report requests metrics from the system and writes them to standard output. that's the whole vibe. it's giving very focused. 💅

---

👑 COMMANDS 👑

these are the commands it understands, fr fr:

• metrics [MATCH...] — goes and acquires a whole list of metrics values from every local service that's providing them, and writes them to standard output. optionally takes one or more match expressions to filter which metrics show up. an expression is either a literal metric family name to search for, or a prefix of one — and that prefix only matches at dot boundaries, no sneaky mid-word matches. if you pass several matches as separate parameters, anything matching any of them gets shown.

Added in version 260.

• describe [MATCH...] — acquires a list of metric families from every local service providing them, and writes them to standard output. this one is mostly the static info: what the metrics are, their data types, and a human readable description. no values, just lore. 📖

the match expressions that metrics supports? describe supports them too.

Added in version 260.

• generate [MATCH...] — acquires a list of metrics and builds a JSON report out of them. ✨

match expressions supported by metrics work here too.

Added in version 261.

• upload [MATCH...] — this one takes the report that generate built and sends it off to an external server. there are two upload mechanisms, pick your fighter:
  • if you specify an "http://" or "https://" URL with --url=, it does an HTTP upload to that location.
  • otherwise, any sockets hanging out under /run/systemd/report.upload/ get used to call io.systemd.Report.Uploader.Upload().

match expressions supported by metrics work here too.

Added in version 261.

• list-sources — shows you the list of known metrics sources. that's it. that's the command. 🫶

Added in version 260.

---

💅 OPTIONS 💅

here's everything it understands, one by one, no skipping:

• --system, --user — query per-system metrics sources (that's the default, bestie) or the per-user metrics sources.

Added in version 260.

• --no-pager — do not pipe the output into a pager. raw output, straight to your terminal, no middleman.
• --json=MODE — shows output formatted as JSON. it expects one of:
  • "short" — the shortest possible output, no redundant whitespace, no line breaks.
  • "pretty" — the pretty version of the same thing, with indentation and line breaks. 💖
  • "off" — turns JSON output off. this is the default.
• -j — equivalent to --json=pretty if you're running on a terminal, and --json=short otherwise. it reads the room. ✨
• --no-legend — do not print the legend, meaning the column headers and that footer with the hints. no context, just data.
• -h, --help — print a short help text and exit. classic.
• --version — print a short version string and exit. also classic.
• --url=URL — upload the collected report to the specified address instead of writing it to standard output. URL must point to a server that accepts 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. so this mode should only be used in specific situations where integrity and confidentiality of the report isn't 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.

⚠️ yes, all means no certificate checking at all. iykyk. be careful bestie.

Added in version 261.

• --network-timeout=SEC — timeout for the network upload operation. takes a value in seconds (or in other time units if you suffix it with "ms", "min", "h", etc.); see systemd.time(7) for the details. defaults to 30 seconds.

Added in version 261.

• --extra-header=NAME: VALUE — inject an additional HTTP header into the upload request. can 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 these 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 get 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. all or nothing, periodt. 👑

Added in version 262.

defaults to no.

Added in version 262.

---

🚦 EXIT STATUS 🚦

on success, 0 is returned. a non-zero failure code otherwise. that's it. zero means we ate, non-zero means we did not. 💀

---

🌈 SEE ALSO 🌈

• systemd(1)

---

okay that's the whole page, bestie, go forth and report some metrics 🦋

this was systemd 262.1, dated SYSTEMD-REPORT(1) — mwah, love u, bye 💜✨