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.

Link to this section Summary

Link to this section Types

Link to this section Functions

Link to this function create_events_msg(events) View Source
Link to this function query(query, timeout \\ 5000) View Source