riemann-client(1)

1RIEMANN-CLIENT(1)              riemann-c-client              RIEMANN-CLIENT(1)
2
3
4

NAME

6       riemann-client - Riemann communication tool
7
8

SYNOPSIS

10       riemann-client query [OPTIONS...] QUERY [HOST] [PORT]
11       riemann-client send [OPTIONS...] [HOST] [PORT]
12       riemann-client --help|-?
13       riemann-client --version
14
15

DESCRIPTION

17       riemann-client  is a very simple tool to faciliate communication with a
18       Riemann event stream processing server. It can be used both for sending
19       events to one, and to query it too.
20
21

OPTIONS

23       In  both  query  and  send mode, HOST and PORT default to localhost and
24       5555, respectively.
25
26
27   Query mode
28       In query mode, riemann-client takes one mandatory argument:  the  query
29       itself.  It  must  be  a single argument, which will be sent to Riemann
30       as-is, and the response dumped to the standard output, or, in  case  of
31       an error, the error message will be written to the standard error.
32
33
34       See  the Riemann documentation http://riemann.io/concepts.html for more
35       information about the query syntax.
36
37
38       Apart from the mandatory argument, the riemann-client accepts the  fol‐
39       lowing options in query mode:
40
41
42       -j, --json
43              Print  the  result  in  JSON  format,  instead  of  the default,
44              human-readable one.
45
46
47       -T, --tcp
48              Send the event via TCP (the default).
49
50
51       -G, --tls
52              Send the event via TLS.
53
54
55       -o, --option option=value
56              Set one client option to the given value.
57
58              Available client options are:
59
60
61              cafile Path to the file containing trusted certificate authority
62                     certificates. Only used for TLS connections.
63
64
65              certfile
66                     Path  to  the  file containing the public client certifi‐
67                     cate. Only used for TLS connections.
68
69
70              keyfile
71                     Path to the file containing the private client key.  Only
72                     used for TLS connections.
73
74
75              priorities
76                     Priorities  for the cipher suites to be used for the ses‐
77                     sion.
78
79
80   Submit mode
81       In submit mode, riemann-client accepts the following options:
82
83
84       -s, --state STATE
85              The state the event should describe, free-form text, optional.
86
87
88       -S, --service SERVICE
89              The service the event is coming from.
90
91
92       -h, --host HOST
93              The host the event originates from. Not to be confused with  the
94              optional  HOST  parameter  of  riemann-client itself, which sets
95              where to send the events to.
96
97
98       -D, --description DESCRIPTION
99              The description of the event, optional.
100
101
102       -t, --tag TAG
103              This option can be used multiple times to add tags to the event.
104
105
106       -a, --attribute NAME=VALUE
107              This option can be used multiple times to add custom  attributes
108              to the event.
109
110
111       -i, --metric-sint64 METRIC
112              Sets the metric for the event, using integer precision.
113
114
115       -d, --metric-d METRIC
116              Sets the metric of the event, using double precision.
117
118
119       -f, --metric-f METRIC
120              Sets the metric of the event, using floating point precision.
121
122
123       -L, --ttl TTL
124              An  optional  time-to-live  of  the  event, in seconds (floating
125              point number).
126
127
128       -T, --tcp
129              Send the event via TCP (the default).
130
131
132       -U, --udp
133              Send the event via UDP.
134
135
136       -G, --tls
137              Send the event via TLS.
138
139
140       -o, --option option=value
141              Set one client option to the given value.
142
143              Available client options are:
144
145
146              cafile Path to the file containing trusted certificate authority
147                     certificates. Only used for TLS connections.
148
149
150              certfile
151                     Path  to  the  file containing the public client certifi‐
152                     cate. Only used for TLS connections.
153
154
155              keyfile
156                     Path to the file containing the private client key.  Only
157                     used for TLS connections.
158
159
160              priorities
161                     Priorities  for the cipher suites to be used for the ses‐
162                     sion.
163
164
165       -0,  --stdin
166              Continously read and  send  metrics  and  states  from  standard
167              input.  Uses all other fields specified on the command line. For
168              each line on standard input, a new event will be  sent  to  Rie‐
169              mann.  If the input is a number, it will be used as a metric. If
170              not, it will be used as the state. If it is a  number,  followed
171              by  a  space and some string, then both metric and state will be
172              set for the outgoing event.
173
174

EXAMPLES

176   Sending an event
177       $ riemann-client send --state ok \
178                             --service "client-test" \
179                             --host "my-host" \
180                             --description "A message from the Manual" \
181                             --tag tag-1 --tag tag-2 \
182                             --attribute x-manual=best-friend \
183                             --metric-sint64 1 \
184                             --ttl 300.5 \
185                             --tcp
186
187
188   Sending metrics / state from standard input
189       $ echo "1.5 ok" |  \
190         riemann-client send --service "client-test: stdin" \
191                             --host "my-host" \
192                             --description "A message from STDIN" \
193                             --tag stdin \
194                             --tcp \
195                             --stdin
196
197
198   Querying Riemann
199       $ riemann-client query 'host = "my-host"'
200
201
202   Using TLS
203       $ riemann-client query 'host = "my-host"' \
204                              --tls \
205                              --option cafile=tests/data/cacert.pem \
206                              --option certfile=tests/data/client.crt \
207                              --option keyfile=tests/data/client.key \
208                              --option priorities=NORMAL \
209                              localhost 5554
210
211

AUTHOR

213       Gergely Nagy algernon@madhouse-project.org
214
215
216
217The MadHouse Project              March 2016                 RIEMANN-CLIENT(1)