Shared library for reporting zipkin spans onto transports including http, kafka and scribe. Requires JRE 6 or later.
These components can be called when spans have been recorded and ready to send to zipkin.
The span encoder is a specialized form of Zipkin's Codec, which only deals with encoding one span.
It is also extensible in case the type of span reported is not zipkin.Span
After recording an operation into a span, it needs to be reported out of process. There are two builtin reporter implementations in this library, although you are free to create your own.
The simplest mechanism is printing out spans as they are reported.
Reporter.CONSOLE.report(span);
AsyncReporter is how you actually get spans to zipkin. By default, it waits up to a second before flushes any pending spans out of process via a Sender.
reporter = AsyncReporter.builder(URLConnectionSender.create("http://localhost:9411/api/v1/spans"))
.build();
// Schedules the span to be sent, and won't block the calling thread on I/O
reporter.report(span);
By default AsyncReporter starts a thread to flush the queue of reported spans. Spans are encoded before enqueuing so it is easiest to relate the backlog as a function of bytes.
Here are the most important properties to understand when tuning.
Property | Description |
---|---|
queuedMaxBytes |
Maximum backlog of span bytes reported vs sent. Default 1% of heap |
messageMaxBytes |
Maximum bytes sendable per message including overhead. Default Sender.messageMaxBytes |
messageTimeout |
Maximum time to wait for messageMaxBytes to accumulate before sending. Default 1 second |
When messageTimeout
is non-zero, a single thread is responsible for
bundling spans into a message for the sender. If you are using a blocking
sender, a surge of reporting activity could lead to a queue backup. This
will show in metrics as spans dropped. If you get into this position,
switch to an asynchronous sender (like kafka), or increase the concurrency
of your sender.
The sender component handles the last step of sending a list of encoded spans onto a transport.
This involves I/O, so you can call Sender.check()
to check its health on a given frequency.
Sender is used by AsyncReporter, but you can also create your own if you need to.
class CustomReporter implements Flushable {
--snip--
URLConnectionSender sender = URLConnectionSender.create("http://localhost:9411/api/v1/spans");
Callback callback = new IncrementSpanMetricsCallback(metrics);
// Is the connection healthy?
public boolean ok() {
return sender.check().ok;
}
public void report(Span span) {
pending.add(Encoder.THRIFT.encode(span));
}
@Override
public void flush() {
if (pending.isEmpty()) return;
List<byte[]> drained = new ArrayList<byte[]>(pending.size());
pending.drainTo(drained);
if (drained.isEmpty()) return;
sender.sendSpans(drained, callback);
}
By default, components use thrift encoding, as it is the most compatible and efficient. However, json is readable and helpful during debugging.
Here's an example of how to switch to json encoding:
sender = URLConnectionSender.builder()
.encoding(Encoding.JSON)
.endpoint("http://localhost:9411/api/v1/spans")
.build();