Debian Codegraph @

upstream/debian-unstable/man1/systemd-report.1

raw
1 '\" t
2 .TH "SYSTEMD\-REPORT" "1" "" "systemd 261~rc3" "systemd-report"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-report \- Generate report of system metrics
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-report\fR\ 'u
26 \fBsystemd\-report\fR [OPTIONS...]
27 .SH "DESCRIPTION"
28 .PP
29 \fINote: 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\&.\fR
30 .PP
31 \fBsystemd\-report\fR
32 requests metrics from the system and writes them to standard output\&.
33 .SH "COMMANDS"
34 .PP
35 The following commands are understood:
36 .PP
37 \fBmetrics\fR [MATCH...]
38 .RS 4
39 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
40 \fIany\fR
41 of the specified matches are shown\&.
42 .sp
43 Added in version 260\&.
44 .RE
45 .PP
46 \fBdescribe\fR [MATCH...]
47 .RS 4
48 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\&.
49 .sp
50 Match expressions supported by
51 \fBmetrics\fR
52 are supported by
53 \fBdescribe\fR
54 too\&.
55 .sp
56 Added in version 260\&.
57 .RE
58 .PP
59 \fBgenerate\fR [MATCH...]
60 .RS 4
61 Acquire a list of metrics and build a JSON report\&.
62 .sp
63 Match expressions supported by
64 \fBmetrics\fR
65 are supported here too\&.
66 .sp
67 Added in version 261\&.
68 .RE
69 .PP
70 \fBupload\fR [MATCH...]
71 .RS 4
72 This command can be used to send the report built by
73 \fBgenerate\fR
74 to an external server\&. Two upload mechanisms are supported\&. If an
75 "http://"
76 or
77 "https://"
78 URL is specified with
79 \fB\-\-url=\fR, an HTTP upload will be performed to the specified location\&. Otherwise, any sockets under
80 /run/systemd/metrics\-upload/
81 will be used to call
82 \fBio\&.systemd\&.Report\&.Upload()\fR\&.
83 .sp
84 Match expressions supported by
85 \fBmetrics\fR
86 are supported here too\&.
87 .sp
88 Added in version 261\&.
89 .RE
90 .PP
91 \fBlist\-sources\fR
92 .RS 4
93 Show list of known metrics sources\&.
94 .sp
95 Added in version 260\&.
96 .RE
97 .SH "OPTIONS"
98 .PP
99 The following options are understood:
100 .PP
101 \fB\-\-system\fR, \fB\-\-user\fR
102 .RS 4
103 Query per\-system metrics sources (the default), or the per\-user metrics sources\&.
104 .sp
105 Added in version 260\&.
106 .RE
107 .PP
108 \fB\-\-no\-pager\fR
109 .RS 4
110 Do not pipe output into a pager\&.
111 .RE
112 .PP
113 \fB\-\-json=\fR\fB\fIMODE\fR\fR
114 .RS 4
115 Shows output formatted as JSON\&. Expects one of
116 "short"
117 (for the shortest possible output without any redundant whitespace or line breaks),
118 "pretty"
119 (for a pretty version of the same, with indentation and line breaks) or
120 "off"
121 (to turn off JSON output, the default)\&.
122 .RE
123 .PP
124 \fB\-j\fR
125 .RS 4
126 Equivalent to
127 \fB\-\-json=pretty\fR
128 if running on a terminal, and
129 \fB\-\-json=short\fR
130 otherwise\&.
131 .RE
132 .PP
133 \fB\-\-no\-legend\fR
134 .RS 4
135 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
136 .RE
137 .PP
138 \fB\-h\fR, \fB\-\-help\fR
139 .RS 4
140 Print a short help text and exit\&.
141 .RE
142 .PP
143 \fB\-\-version\fR
144 .RS 4
145 Print a short version string and exit\&.
146 .RE
147 .PP
148 \fB\-\-url=\fR\fB\fIURL\fR\fR
149 .RS 4
150 Upload the collected report to the specified address instead of writing it to standard output\&.
151 \fIURL\fR
152 must point to a server accepting POST requests with a JSON\-formatted report body\&.
153 .sp
154 Note: both
155 "http://"
156 and
157 "https://"
158 URLs are supported, but
159 \fIconnections over plain HTTP are made without encryption\fR\&. 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
160 "https://"
161 is recommended\&.
162 .sp
163 Added in version 261\&.
164 .RE
165 .PP
166 \fB\-\-key=\fR\fB\fIFILENAME\fR\fR
167 .RS 4
168 Takes a path to a SSL key file in PEM format, used for client certificate authentication when uploading\&. Can also be set to
169 "\-", to disable client certificate authentication\&. Defaults to
170 /etc/ssl/private/systemd\-report\&.pem\&.
171 .sp
172 Added in version 261\&.
173 .RE
174 .PP
175 \fB\-\-cert=\fR\fB\fIFILENAME\fR\fR
176 .RS 4
177 Takes a path to a SSL certificate file in PEM format, used for client certificate authentication when uploading\&. Defaults to
178 /etc/ssl/certs/systemd\-report\&.pem\&.
179 .sp
180 Added in version 261\&.
181 .RE
182 .PP
183 \fB\-\-trust=\fR\fB\fIFILENAME\fR\fR\fB|\fR\fB\fBall\fR\fR
184 .RS 4
185 Takes a path to a SSL CA certificate file in PEM format used to verify the server certificate, or the literal string
186 \fBall\fR
187 to disable certificate checking entirely\&. Defaults to
188 /etc/ssl/ca/trusted\&.pem\&.
189 .sp
190 Added in version 261\&.
191 .RE
192 .PP
193 \fB\-\-network\-timeout=\fR\fB\fISEC\fR\fR
194 .RS 4
195 Timeout for the network upload operation\&. Takes a value in seconds (or in other time units if suffixed with
196 "ms",
197 "min",
198 "h", etc\&.); see
199 \fBsystemd.time\fR(7)
200 for details\&. Defaults to 30 seconds\&.
201 .sp
202 Added in version 261\&.
203 .RE
204 .PP
205 \fB\-\-extra\-header=\fR\fB\fINAME\fR\fR\fB: \fR\fB\fIVALUE\fR\fR
206 .RS 4
207 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
208 \fB\-\-extra\-header=\fR
209 uses\&.
210 .sp
211 Added in version 261\&.
212 .RE
213 .SH "EXIT STATUS"
214 .PP
215 On success, 0 is returned, a non\-zero failure code otherwise\&.
216 .SH "SEE ALSO"
217 .PP
218 \fBsystemd\fR(1)