Package zipkin2.reporter

Interface BytesMessageSender

  • All Superinterfaces:
    Closeable
    All Known Implementing Classes:
    BytesMessageSender.Base, Sender
    public interface BytesMessageSender
extends Closeable
    Sends a list of encoded spans to a transport such as HTTP or Kafka. Usually, this involves encoding them into a message and enqueueing them for transport in a corresponding client library. The typical end recipient is a zipkin collector.

    Unless mentioned otherwise, senders are not thread-safe. They were designed to be used by a single reporting thread, hence the operation is blocking

    Those looking to initialize eagerly can send(List) with an empty list. This can be used to reduce latency on the first send operation, or to fail fast.

    Implementation notes

    The parameter is a list of encoded spans as opposed to an encoded message. This allows implementations flexibility on how to encode spans into a message. For example, a large span might need to be sent as a separate message to avoid kafka limits. Also, logging transports like scribe will likely write each span as a separate log line.

    This accepts a list of encoded spans, as opposed a list of spans like zipkin2.Span. This allows senders to be re-usable as model shapes change. This also allows them to use their most natural message type. For example, kafka would more naturally send messages as byte arrays.

    Since:
    3.2

    • Method Detail

      • encoding

        Encoding encoding()
        Returns the encoding this sender requires spans to have.

      • messageMaxBytes

        int messageMaxBytes()
        Maximum bytes sendable per message including overhead. This can be calculated using messageSizeInBytes(List)

        Defaults to 500KB as a conservative default. You may get better or reduced performance by changing this value based on, e.g., machine size or network bandwidth in your infrastructure. Finding a perfect value will require trying out different values in production, but the default should work well enough in most cases.

      • messageSizeInBytes

        int messageSizeInBytes​(List<byte[]> encodedSpans)
        Before invoking send(List), callers must consider message overhead, which might be more than encoding overhead. This is used to not exceed messageMaxBytes().

        Note this is not always Encoding.listSizeInBytes(List), as some senders have inefficient list encoding. For example, Scribe base64's then tags each span with a category.

      • messageSizeInBytes

        int messageSizeInBytes​(int encodedSizeInBytes)
        Like messageSizeInBytes(List), except for a single-span. This is used to ensure a span is never accepted that can never be sent.

        Note this is not always Encoding.listSizeInBytes(int), as some senders have inefficient list encoding. For example, Stackdriver's proto message contains other fields.

        Parameters:
        encodedSizeInBytes - the encoded size of a span

      • send

        void send​(List<byte[]> encodedSpans)
   throws IOException
        Sends a list of encoded spans to a transport such as HTTP or Kafka.

        Empty input is permitted. While async reporters in this repository will always send a non-empty list. Some external callers might use an empty send for fail-fast checking. If you obviate empty lists, you might break them. See /RATIONALE.md for more.

        Parameters:
        encodedSpans - a potentially empty list of encoded spans.
        Throws:
        IllegalStateException - if close was called.
        IOException