Query mode¶

In query mode, riemann-client takes one mandatory argument: the query itself. It must be a single argument, which will be sent to Riemann as-is, and the response dumped to the standard output, or, in case of an error, the error message will be written to the standard error.

See the Riemann documentation http://riemann.io/concepts.html for more information about the query syntax.

Apart from the mandatory argument, the riemann-client accepts the following options in query mode:

-j, --json

Print the result in JSON format, instead of the default, human-readable one.

-T, --tcp

Send the event via TCP (the default).

-G, --tls

Send the event via TLS.

-o, --option option=value

Set one client option to the given value.

Available client options are:

Submit mode¶

In submit mode, riemann-client accepts the following options:

-s, --state STATE

The state the event should describe, free-form text, optional.

-S, --service SERVICE

The service the event is coming from.

-h, --host HOST

The host the event originates from. Not to be confused with the optional HOST parameter of riemann-client itself, which sets where to send the events to.

-D, --description DESCRIPTION

The description of the event, optional.

-t, --tag TAG

This option can be used multiple times to add tags to the event.

-a, --attribute NAME=VALUE

This option can be used multiple times to add custom attributes to the event.

-i, --metric-sint64 METRIC

Sets the metric for the event, using integer precision.

-d, --metric-d METRIC

Sets the metric of the event, using double precision.

-f, --metric-f METRIC

Sets the metric of the event, using floating point precision.

-L, --ttl TTL

An optional time-to-live of the event, in seconds (floating point number).

-T, --tcp

Send the event via TCP (the default).

-U, --udp

Send the event via UDP.

-G, --tls

Send the event via TLS.

-o, --option option=value

Set one client option to the given value.

Available client options are:

-0, --stdin

Continuously read and send metrics and states from standard input. Uses all other fields specified on the command line. For each line on standard input, a new event will be sent to Riemann. If the input is a number, it will be used as a metric. If not, it will be used as the state. If it is a number, followed by a space and some string, then both metric and state will be set for the outgoing event.

Sending an event¶

$ riemann-client send --state ok \


                      --service "client-test" \


                      --host "my-host" \


                      --description "A message from the Manual" \


                      --tag tag-1 --tag tag-2 \


                      --attribute x-manual=best-friend \


                      --metric-sint64 1 \


                      --ttl 300.5 \


                      --tcp

Sending metrics / state from standard input¶

$ echo "1.5 ok" |  \


  riemann-client send --service "client-test: stdin" \


                      --host "my-host" \


                      --description "A message from STDIN" \


                      --tag stdin \


                      --tcp \


                      --stdin

Querying Riemann¶

$ riemann-client query 'host = "my-host"'

Using TLS¶

$ riemann-client query 'host = "my-host"' \


                       --tls \


                       --option cafile=tests/data/cacert.pem \


                       --option certfile=tests/data/client.crt \


                       --option keyfile=tests/data/client.key \


                       --option priorities=NORMAL \


                       localhost 5554