Eventtracker, a Java library for the Dwarf Collector¶ ↑

The eventtracker library is a Java library to send events to the Collector (github.com/pierre/collector).

Please refer to the serialization library FAQ for an overview of the Event concept: pierre.github.com/dwarf/serialization/faq.html

4.x.x release¶ ↑

Starting with 4.0.0, the eventtracker library is now broken into submodules:

• com.ning:metrics.eventtracker-common: common classes, not useful by itself

• com.ning:metrics.eventtracker-http: http sender classes, not useful by itself

• com.ning:metrics.eventtracker-scribe: Thrift/Scribe sender (functionality equivalent to pre 4.0.0)

• com.ning:metrics.eventtracker-smile: http sender, using Json/Smile serialization protocol (uses the collector POST API)

Usage¶ ↑

Scribe¶ ↑

For Guice integration, you need to install the CollectorControllerScribeModule module. To expose JMX stats, you need to install the CollectorControllerScribeMBeanModule module.

Smile over HTTP¶ ↑

For Guice integration, you need to install the CollectorControllerSmileModule module. To expose JMX stats, you need to install the CollectorControllerHttpMBeanModule module.

Maven¶ ↑

The eventtracker library is synced to Maven Central. Simply add the dependency to your pom.xml:

<dependency>
    <groupId>com.ning</groupId>
    <!-- Pick one! -->
    <artifactId>metrics.eventtracker-{http,scribe}</artifactId>
    <version>4.0.0</version>
</dependency>

The library offers a simple method to send events. Here is a complete working example to send one Thrift event (we assume myShinyEvent is a Thrift object):

ThriftEnvelopeEvent eventToSend = ThriftToThriftEnvelopeEvent.extractEvent("MyShinyEvent", myShinyEvent);

// See the Javadocs for fine-tuning of the parameters
// There is also a Guice module which uses config-magic for parameters injection:
//        Injector injector = Guice.createInjector(new CollectorControllerModule());
//        CollectorController controller = injector.getInstance(CollectorController.class);
EventTrackerConfig eventTrackerConfig = new EventTrackerConfig();
eventTrackerConfig.setScribeHost("collector-vip.company.com");

CollectorController controller = ScribeCollectorFactory.createScribeController(eventTrackerConfig);

controller.offerEvent(eventToSend);

// Optional, see below
controller.commit();
controller.flush();

You can send any type of Event (not necessarily Thrift) via the library (see below).

How does it work?¶ ↑

Each event accepted via the offerEvent(Event) API is directly serialized to disk using the com.ning:metrics.serialization-writer library for persistency. Events are then de-serialized and sent to the collector periodically and/or after a certain number of events have been offered.

The library supports all Collector APIs: HTTP based and Scribe (Thrift).

The CollectorController class provides the commit() call to force a promotion from the temporary queue of events to the final queue: only events in the final queue are sent (a separate thread wakes up periodically to see if there is anything to send). The commit() call bypasses the promotion rules mentioned above.

One can force a flush to the final queue by calling flush() on the controller object. This forces all events in the queue to be sent remotely.

Serialization to disk is done using the Java Serialization mechanisms (ObjectOutputStream to file). The whole Event object is written to disk. This is not configurable.

Final serialization on the wire is configurable (e.g. Java Serialization, Thrift). You can extend your event to support your own serialization protocol by implementing getSerializedBytes(). These bytes are sent on the wire.

License (see LICENSE-2.0.txt file for full license)¶ ↑

Copyright 2010-2011 Ning

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.