riemannx v2.2.0 Riemannx View Source
Riemannx is a riemann client that supports UDP/TCP sockets and also supports a hybrid connection where smaller packets are sent via UDP and the rest over TCP.
Examples
To use riemannx all you need to do is fill out some config entries - after that everything just happens automagically (save for the actual sending of course):
config :riemannx, [
# Client settings
host: "127.0.0.1",
tcp_port: 5555,
udp_port: 5555,
max_udp_size: 16384, # Must be the same as server side, the default is riemann's default.
type: :combined, # A choice of :tcp, :udp, :combined or :tls
retry_count: 5, # How many times to re-attempt a TCP connection before crashing.
retry_interval: 1, # Interval to wait before the next TCP connection attempt.
ssl_opts: [], # Used for tls, see TLS section for details.
# Poolboy settings
pool_size: 5, # Pool size will be 10 if you use a combined type.
max_overflow: 5, # Max overflow will be 10 if you use a combined type.
strategy: :fifo, # See Riemannx.Settings documentation for more info.
]
Riemannx supports two send
methods, one asynchronous the other synchronous:
Synchronous Send
Synchronous sending allows you to handle the errors that might occur during send, below is an example showing both how this error looks and what happens on a successful send:
event = [service: "riemannx-elixir",
metric: 1,
attributes: [a: 1],
description: "test"]
case Riemannx.send(event) do
:ok ->
"Success!"
[error: error, msg: encoded_msg] ->
# The error will always be a string so you can output it as it is.
#
# The encoded message is a binary blob but you can use the riemannx proto
# msg module to decode it if you wish to see it in human readable form.
msg = encoded_msg |> Riemannx.Proto.Msg.decode()
end
Asynchronous Send
Asynchronous sending is much faster but you never really know if your message made it, in a lot of cases this kind of sending is safe enough and for most use cases the recommended choice. It’s fairly simple to implement:
event = [service: "riemannx-elixir",
metric: 1,
attributes: [a: 1],
description: "test"]
Riemannx.send_async(event)
# Who knows if it made it? Who cares? 60% of the time it works everytime!
NOTE: If a worker is unable to send it will die and be restarted giving it a chance to return to a ‘correct’ state. On an asynchronous send this is done by pattern matching :ok with the send command, for synchronous sends if the return value is an error we kill the worker before returning the result.
TLS
TLS support allows you to use a secure TCP connection with your riemann server, to learn more about how to set this up take a look here: Secure Traffic
If you choose to use TLS you will be using a purely TCP setup, combined is not supported (and shouldn’t be either) with TLS:
config :riemannx, [
host: "127.0.0.1",
tcp_port: 5555,
type: :tls,
# SSL Opts are passed to the underlying ssl erlang interface
# See available options here: http://erlang.org/doc/man/ssl.html
ssl_opts: [
keyfile: "path/to/key",
certfile: "path/to/cert",
verify_peer: true
]
]
Assuming you have set up the server-side correctly this should be all you need to get started.
Querying the index
Riemann has the concept of a queryable index which allows you to search for specific events, indexes must be specially created in your config otherwise the server will return a “no index” error.
# Lets send an event that we can then query
Riemannx.send([service: "riemannx", metric: 5.0, attributes: [v: "2.2.0"]])
# Let's fish it out
events = Riemannx.query('service ~= "riemannx"')
# [%{attributes: %{"v" => "2.2.0"}, description: nil, host: _,
# metric: nil, service: "riemannx", state: nil, tags: [],
# time: _, ttl: _}]
For more information on querying and the language features have a look at the Core Concepts.