goryman

README

Riemann client (Golang)

Introduction

Go client library for Riemann.

This client library was inspired by Raidman, and Riemann NodeJS Client.

Features:

• Idiomatic concurrency
• Sending events, state updates, queries.
• Feature parity with the reference implementation written in Ruby.

Installation

To install the package for use in your own programs:

go get github.com/bigdatadev/goryman

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

go get code.google.com/p/goprotobuf/{proto,protoc-gen-go}

Getting Started

First we'll need to import the library:

import (
    "github.com/bigdatadev/goryman"
)

Next we'll need to establish a new client:

c := goryman.NewGorymanClient("localhost:5555")
err := c.Connect()
if err != nil {
    panic(err)
}

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

defer c.Close()

Just like the Riemann Ruby client, the client sends small events over UDP by default. TCP is used for queries, and large events. There is no acknowledgement of UDP packets, but they are roughly an order of magnitude faster than TCP. We assume both TCP and UDP are listening on the same port.

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

err = c.SendEvent(&goryman.Event{
    Service: "moargore",
    Metric:  100,
    Tags: []string{"nonblocking"},
})
if err != nil {
    panic(err)
}

You can also query events:

events, err := c.QueryEvents("host = \"goryman\"")
if err != nil {
    panic(err)
}

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

Integrations

Martini: GoryMartini

Contributing

Just send me a pull request. Please take a look at the project issues and see how you can help. Here are some tips:

• please add more tests.
• please check your syntax.

Author

Christopher Gilbert

• Web: http://cjgilbert.me
• Twitter: @bigdatadev
• Linkedin: /in/christophergilbert

Copyright

See LICENSE document

Documentation

Overview

A Riemann client for Go, featuring concurrency, sending events and state updates, queries, and feature parity with the reference implementation written in Ruby.

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

Index

• func EventToProtocolBuffer(event *Event) (*proto.Event, error)
• func StateToProtocolBuffer(state *State) (*proto.State, error)
• type Event
  • func ProtocolBuffersToEvents(pbEvents []*proto.Event) []Event
• type GorymanClient
  • func NewGorymanClient(addr string) *GorymanClient
  • func (c *GorymanClient) Close() error
  • func (c *GorymanClient) Connect() error
  • func (c *GorymanClient) SendEvent(e *Event) error
  • func (c *GorymanClient) SendState(s *State) error
• type State
• type Transport
  • func NewTcpTransport(conn net.Conn) *Transport
  • func (t *Transport) Close() error
  • func (t *Transport) Send(message *proto.Msg) error

Functions

func EventToProtocolBuffer

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

EventToProtocolBuffer converts an Event type to a proto.Event

func StateToProtocolBuffer

func StateToProtocolBuffer(state *State) (*proto.State, error)

StateToProtocolBuffer converts a State type to a proto.State

Types

type Event

type Event struct {
	Ttl         float32
	Time        int64
	Tags        []string
	Host        string // Defaults to os.Hostname()
	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 GorymanClient

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

GorymanClient is a client library to send events to Riemann

func NewGorymanClient

func NewGorymanClient(addr string) *GorymanClient

NewGorymanClient - Factory

func (*GorymanClient) Close

func (c *GorymanClient) Close() error

Close the connection to Riemann

func (*GorymanClient) Connect

func (c *GorymanClient) Connect() error

Connect creates a UDP and TCP connection to a Riemann server

func (*GorymanClient) SendEvent

func (c *GorymanClient) SendEvent(e *Event) error

Send an event

func (*GorymanClient) SendState

func (c *GorymanClient) SendState(s *State) error

Send a state update

type State

type State struct {
	Ttl         float32
	Time        int64
	Tags        []string
	Host        string // Defaults to os.Hostname()
	State       string
	Service     string
	Once        bool
	Metric      interface{} // Could be Int, Float32, Float64
	Description string
	Attributes  map[string]string
}

State is a wrapper for Riemann states

type Transport

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

func NewTcpTransport

func NewTcpTransport(conn net.Conn) *Transport

NewTcpTransport - Factory

func (*Transport) Close

func (t *Transport) Close() error

Close implements the io.Closer interface.

func (*Transport) Send

func (t *Transport) Send(message *proto.Msg) error

Send, queues a message to send a the Riemann server.