Skip to content

Shared library for reporting zipkin spans on transports such as http or kafka

License

Notifications You must be signed in to change notification settings

openzipkin/zipkin-reporter-java

Folders and files

NameName
Last commit message
Last commit date

Latest commit

743ca74 · Sep 4, 2016

History

29 Commits
Aug 11, 2016
Sep 4, 2016
Sep 4, 2016
Sep 4, 2016
Sep 4, 2016
Sep 4, 2016
Aug 11, 2016
Sep 4, 2016
Sep 4, 2016
Aug 11, 2016
Aug 11, 2016
Aug 11, 2016
Aug 11, 2016
Aug 10, 2016
Sep 4, 2016
Aug 11, 2016
Aug 11, 2016
Sep 4, 2016

Repository files navigation

Gitter chat Build Status Download

zipkin-reporter-java

Shared library for reporting zipkin spans onto transports including http, kafka and scribe. Requires JRE 6 or later.

Usage

These components can be called when spans have been recorded and ready to send to zipkin.

Encoder

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

Reporter

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

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);

Tuning

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

Dealing with span backlog

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.

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);
  }

Json Encoding

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();