README.md
1Riemann C client library
2========================
3
4[](https://ci.madhouse-project.org/algernon/riemann-c-client)
5[](http://www.gnu.org/licenses/lgpl.html)
6
7This is a C client library for the [Riemann][riemann] monitoring
8system, providing a convenient and simple API, high test coverage and
9a copyleft license, along with API and ABI stability.
10
11 [riemann]: http://riemann.io/
12
13The library uses [semantic versioning][semver].
14
15 [semver]: http://semver.org/
16
17Features
18--------
19
20 * Sending events over TCP, TLS and UDP
21 * Launching queries (TCP & TLS only)
22 * Support for tags and attributes on events
23 * Ability to send multiple events in a single message
24 * Convenient and straightforward API (see the [API docs][api-docs]
25 and the [demo](#demo) below!)
26 * A comprehensive test suite
27 * API and ABI stability (including symbol versioning on platforms
28 where it is available).
29
30 [api-docs]: docs/API.md#readme
31
32Demo
33----
34
35A simple program that sends a static event to [Riemann][riemann] is
36included below. A few more useful programs are included in the
37[src][src] directory of the source code.
38
39 [src]: src/
40
41```c
42#include <riemann/riemann-client.h>
43#include <riemann/simple.h>
44
45#include <errno.h>
46#include <stdio.h>
47#include <stdlib.h>
48#include <string.h>
49#include <unistd.h>
50
51int
52main (void)
53{
54 riemann_client_t *client;
55 riemann_message_t *r;
56
57 client = riemann_client_create (RIEMANN_CLIENT_TCP, "localhost", 5555);
58 if (!client)
59 {
60 fprintf (stderr, "Error while connecting to Riemann: %s\n",
61 strerror (errno));
62 exit (EXIT_FAILURE);
63 }
64
65 r = riemann_communicate_event
66 (client,
67 RIEMANN_EVENT_FIELD_HOST, "localhost",
68 RIEMANN_EVENT_FIELD_SERVICE, "demo-client",
69 RIEMANN_EVENT_FIELD_STATE, "ok",
70 RIEMANN_EVENT_FIELD_TAGS, "demo-client", "riemann-c-client", NULL,
71 RIEMANN_EVENT_FIELD_NONE);
72
73 if (!r)
74 {
75 fprintf (stderr, "Error while sending message: %s\n", strerror (errno));
76 exit (EXIT_FAILURE);
77 }
78
79 if (r->ok != 1)
80 {
81 fprintf (stderr, "Error communicating with Riemann: %s\n",
82 (r->error) ? r->error : strerror (errno));
83 exit (EXIT_FAILURE);
84 }
85
86 riemann_message_free (r);
87 riemann_client_free (client);
88
89 return EXIT_SUCCESS;
90}
91```
92
93Installation
94------------
95
96The library follows the usual autotools way of installation:
97
98 $ git clone https://git.madhouse-project.org/algernon/riemann-c-client.git
99 $ cd riemann-c-client
100 $ autoreconf -i
101 $ ./configure && make && make check && make install
102
103For the build to succeed, one will need libtool 2.2+ (only if building
104from a git checkout), the [protobuf-c compiler][protoc]. Optionally,
105for TLS support, one needs [GnuTLS][gnutls] 2.8+, and to enable the
106JSON output support in `riemann-client`, one also needs the
107[json-c][json-c] library installed.
108
109 [protoc]: http://protobuf-c.googlecode.com
110 [gnutls]: http://www.gnutls.org/
111 [json-c]: https://github.com/json-c/json-c/wiki
112
113From this point onward, the library is installed and fully functional,
114and one can use `pkg-config` to compile programs against it:
115
116 ${CC} $(pkg-config --cflags --libs riemann-client) demo.c -o demo -Wall
117
118If, for some reason the build fails, one may need to regenerate the
119`protobuf-c-compiler` generated headers (changes in the compiler are
120known to cause issues). To do this, do a `make distclean` first, and
121then start over from `configure`.
122
){kind=link}