NAME

Riemann::Client - A Perl client for the Riemann event system

SYNOPSIS

    use Riemann::Client;

    # host and port are optional
    my $r = Riemann::Client->new(
        host => 'localhost',
        port => 5555,
    );

    # send a simple event
    $r->send({service => 'testing', metric => 2.5});

    # Or a more complex one
    $r->send({
        host    => 'web3', # defaults to Net::Domain::hostfqdn()
        service => 'api latency',
        state   => 'warn',
        metric  => 63.5,
        time    => time() - 10, # defaults to time()
        description => '63.5 milliseconds per request',
    });

    # send several events at once
    my @events = (
        { service => 'service1', ... },
        { service => 'service2', ... },
    );
    $r->send(@events);

    # Get all the states from the server
    my $res = $r->query('true');

    # Or specific states matching a query
    $res = $r->query('host =~ "%.dc1" and state = "critical"');

DESCRIPTION

Riemann::Client sends events and/or queries to a Riemann server.

METHODS

new

Returns an instance of the Riemann::Client. These are the optional arguments accepted:

host

The Riemann server. Defaults to localhost

port

Port where the Riemann server is listening. Defaults to 5555

use_udp

By default Riemann::Client will use TCP to communicate over the network. You can force the usage of UDP setting this argument to true. UDP datagrams have a maximum size of 16384 bytes by Riemann's default. If you force the usage of UDP and try to send a larger message, an exception will be raised.

send

Accepts a list of events (as hashrefs) and sends them over the wire to the server.

query

Accepts a string and returns a message.

MESSAGE SPECS

This is the specification of the messages in Google::ProtocolBuffers format:

    message State {
      optional int64 time = 1;
      optional string state = 2;
      optional string service = 3;
      optional string host = 4;
      optional string description = 5;
      optional bool once = 6;
      repeated string tags = 7;
      optional float ttl = 8;
    }

    message Event {
      optional int64 time = 1;
      optional string state = 2;
      optional string service = 3;
      optional string host = 4;
      optional string description = 5;
      repeated string tags = 7;
      optional float ttl = 8;

      optional sint64 metric_sint64 = 13;
      optional double metric_d = 14;
      optional float metric_f = 15;
    }

    message Query {
      optional string string = 1;
    }

    message Msg {
      optional bool ok = 2;
      optional string error = 3;
      repeated State states = 4;
      optional Query query = 5;
      repeated Event events = 6;
    }

SEE ALSO

• All About Riemann http://aphyr.github.com/riemann/

• Ruby client https://github.com/aphyr/riemann-ruby-client

AUTHOR

• Miquel Ruiz <mruiz@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Miquel Ruiz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.