riemanngo

README

Riemann client (Golang)

Introduction

A Go client library for Riemann.

Features:

• Idiomatic concurrency
• Sending events, queries.
• Support TCP, UDP, TLS clients.
• Second and Microsecond time resolution

This client is a fork of Goryman, a Riemann go client written by Christopher Gilbert. Thanks and full credit to him!

The initial Goryman repository has been deleted. We've used @rikatz's fork to create this repository.

We've also renamed the client to riemanngo instead of goryman to make its purpose clearer.

Build Status

Installation

To install the package for use in your own programs:

go get github.com/riemann/riemann-go-client

If you're a developer, Riemann uses Google Protocol Buffers, so make sure that's installed and available on your PATH.

go get github.com/golang/protobuf/{proto,protoc-gen-go}

Getting Started

First, we'll need to import the library:

import (
    "github.com/riemann/riemann-go-client"
)

Next, we'll need to establish a new client. The parameters are the Riemann address and the connection timeout duration. You can use a TCP client:

c := riemanngo.NewTCPClient("127.0.0.1:5555", 5*time.Second)
err := c.Connect()
if err != nil {
    panic(err)
}

Or a UDP client:

c := riemanngo.NewUDPClient("127.0.0.1:5555", 5*time.Second)
err := c.Connect()
if err != nil {
    panic(err)
}

You can also create a TLS client. The second parameter is the path to your client certificate, the third parameter the path to your client key. The next parameter allows you to create an insecure connection (insecure certificate check). The last parameter is the connect and write timeout. You can find more informations about how to configure TLS in Riemann here.

c := riemanngo.NewTLSClient("127.0.0.1:5554", "/path/to/cert.pem", "/path/to/key.key", true, 5*time.Second)
err := c.Connect()
if err != nil {
    panic(err)
}

Don't forget to close the client connection when you're done:

defer c.Close()

Sending events is easy (list of valid event properties):

result, err := riemanngo.SendEvent(c, &riemanngo.Event{
		Service: "hello",
		Metric:  100,
		Tags: []string{"riemann ftw"},
	})

The host name and time in events will automatically be replaced with the hostname of the server and the current time if none is specified.

You can also send batch of events:

events = []riemanngo.Event {
    riemanngo.Event{
        Service: "hello",
        Metric:  100,
        Tags: []string{"hello"},
    },
riemanngo.Event{
        Service: "goodbye",
        Metric:  200,
        Tags: []string{"goodbye"},
    },
}

You can also query the Riemann index (using the TCP or TLS client):

events, err := c.QueryIndex("service = \"hello\"")
if err != nil {
    panic(err)
}

Uint metric type

The event Metric value can have uint (or uint32, uint64) as type. In this case, this value will be converted to int64, which can cause issues.

Tests

You can lauch tests using

make test

and integration tests using:

make integ-test

This command will download Riemann, start it, launch integration tests, and kill it.

You can also use:

go test -tags=integration

if you already have a Riemann instance listening on localhost

Copyright

See LICENSE document

Documentation

Overview

A Riemann client for Go, featuring concurrency, sending events and state updates, queries

Copyright (C) 2014 by Christopher Gilbert <christopher.john.gilbert@gmail.com>

Index

• Constants
• func EventToProtocolBuffer(event *Event) (*proto.Event, error)
• func GetTLSConfig(serverName string, certPath string, keyPath string, insecure bool) (*tls.Config, error)
• func SendEvent(c Client, e *Event) (*proto.Msg, error)
• func SendEvents(c Client, e *[]Event) (*proto.Msg, error)
• type Client
• type Event
  • func ProtocolBuffersToEvents(pbEvents []*proto.Event) []Event
• type IndexClient
• type TCPClient
  • func NewTCPClient(addr string, timeout time.Duration) *TCPClient
  • func NewTLSClient(addr string, tlsConfig *tls.Config, timeout time.Duration) (*TCPClient, error)
  • func (c *TCPClient) Close() error
  • func (c *TCPClient) Connect() error
  • func (c *TCPClient) QueryIndex(q string) ([]Event, error)
  • func (c *TCPClient) Send(message *proto.Msg) (*proto.Msg, error)
• type UDPClient
  • func NewUDPClient(addr string, timeout time.Duration) *UDPClient
  • func (c *UDPClient) Close() error
  • func (c *UDPClient) Connect() error
  • func (c *UDPClient) Send(message *proto.Msg) (*proto.Msg, error)

Constants

const MaxUDPSize = 16384

MaxUDPSize is the maximum allowed size of a UDP packet before automatically failing the send

Functions

func EventToProtocolBuffer

func EventToProtocolBuffer(event *Event) (*proto.Event, error)

EventToProtocolBuffer convert an event to a protobuf Event

func GetTLSConfig

func GetTLSConfig(serverName string, certPath string, keyPath string, insecure bool) (*tls.Config, error)

GetTLSConfig returns a *tls.Config

func SendEvent

func SendEvent(c Client, e *Event) (*proto.Msg, error)

SendEvent send an event using a client

func SendEvents

func SendEvents(c Client, e *[]Event) (*proto.Msg, error)

SendEvents send multiple events using a client

Types

type Client

type Client interface {
	Send(message *proto.Msg) (*proto.Msg, error)
	Connect() error
	Close() error
}

Client is an interface to a generic client

type Event

type Event struct {
	TTL         time.Duration
	Time        time.Time
	Tags        []string
	Host        string
	State       string
	Service     string
	Metric      interface{} // Could be Int, Float32, Float64
	Description string
	Attributes  map[string]string
}

Event is a wrapper for Riemann events

func ProtocolBuffersToEvents

func ProtocolBuffersToEvents(pbEvents []*proto.Event) []Event

ProtocolBuffersToEvents converts an array of proto.Event to an array of Event

type IndexClient

type IndexClient interface {
	QueryIndex(q string) ([]Event, error)
}

IndexClient is an interface to a generic Client for index queries

type TCPClient

type TCPClient struct {
	// contains filtered or unexported fields
}

TCPClient is a type that implements the Client interface

func NewTCPClient

func NewTCPClient(addr string, timeout time.Duration) *TCPClient

NewTCPClient - Factory

func NewTLSClient

func NewTLSClient(addr string, tlsConfig *tls.Config, timeout time.Duration) (*TCPClient, error)

NewTLSClient - Factory

func (*TCPClient) Close

func (c *TCPClient) Close() error

Close will close the TCPClient

func (*TCPClient) Connect

func (c *TCPClient) Connect() error

Connect the tcp client

func (*TCPClient) QueryIndex

func (c *TCPClient) QueryIndex(q string) ([]Event, error)

QueryIndex query the server for events using the client

func (*TCPClient) Send

func (c *TCPClient) Send(message *proto.Msg) (*proto.Msg, error)

Send queues a request to send a message to the server

type UDPClient

type UDPClient struct {
	// contains filtered or unexported fields
}

UDPClient is a type that implements the Client interface

func NewUDPClient

func NewUDPClient(addr string, timeout time.Duration) *UDPClient

NewUDPClient - Factory

func (*UDPClient) Close

func (c *UDPClient) Close() error

Close will close the UDPClient

func (*UDPClient) Connect

func (c *UDPClient) Connect() error

Connect the udp client

func (*UDPClient) Send

func (c *UDPClient) Send(message *proto.Msg) (*proto.Msg, error)

Send queues a request to send a message to the server