fireboard-client-java

A Java client library to create and post status messages to Fireboard (https://fireboard.verticle.io) .

Setup & Usage

Requirements

The library requires a JDK which supports the letsencrypt CA:

Java 7 >= 7u111 or
Java 8 >= 8u101 or
Java 9

Dependencies: none

The lib is written as low level as possible, without any dependencies and potentially compatible with JDK 6. Note, that the above JDKs are supported because of the letscencrypt CA cert. If you want to use a version below you have to import the CA certificate into your truststore.

Maven

This library can be retrieved via Jitpack:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.verticleio</groupId>
    <artifactId>fireboard-client-java</artifactId>
    <version>LATEST</version>
</dependency>

Configuration

Configuration is read from System.properties.

Mandatory properties:

fireboard.tenant - your tenant ID
fireboard.bucket - the bucket you want to store the status to
fireboard.api.token - your API token (open Fireboard UI to retrieve it)

Optional:

fireboard.api.endpoint - is preset but can be altered if necessary
fireboard.debug - to enable debug output

Message Format

StatusEvent

field	type	description	example
event	string	the event, should be short	'service started'
message	string	detail message	'The backend service has successfully started and connected to elasticsearch'
category	string `[a-z0-9._-]`	a category name	'backend_services'
link	URL, optional	fully qualified deep link to navigate for details	'backend.elasticsearch.bootstrap'
ident	string	a qualifier for this message	'backend.elasticsearch.bootstrap'
status	enum `success,warn,error,info`	the status level	'success'
severity	number `1-6`, optional	1 (low) - 6 (high)
uuid	string	unique message identifier, applied by service
created	timestamp	applied by service
correlationId	string	not yet implemented
messagepropertiessection	array of `MessagePropertiesSection`, optional	section for key/values to store

A uuid for this message and a timestamp will be applied by the service

MessagePropertiesSection

field	type	description	example
name	string	the section name	'service meta properties'
uuid	string	optional unique identifier
messageproperties	array of `MessageProperty`	optional section for key/values to store

NOTE: the section prefix "_" is reserved for Fireboard namespaces.

MessageProperty

field	type	description	example
name	string	the property key	'service.id'
value	string	the property value	'elastic-bridge'

NOTE: all strings need to be JSON compatible! Escape them if needed.

Example


try {
    FireboardClient.post(
        new FireboardMessageBuilder()
            .event("service started")
            .category("backend_services")
            .severity(3)
            .ident("ident")
            .link(new URL("https://fireboard.verticle.io"))
            .message("The backend service has successfully started and connected to elasticsearch")
            .status(StatusEnum.success)
            .properties(
                new MessagePropertyHelper()
                    .section("service meta properties")
                    .property("service.id", "elastic-bridge")
                    .section("all foos")
                    .property("foo1", "bar1")
                    .property("foo2", "bar2")
                    .build()
        ).build()
    );

} catch (Exception e) {
    // you should always catch anything
    //  so your own logic is not interrupted
    e.printStackTrace();
}

Licence

MIT

verticle-io / fireboard-client-java Goto Github PK