Interface BytesMessageSender
-
- All Superinterfaces:
Closeable
- All Known Implementing Classes:
BaseHttpSender
,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 likezipkin2.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
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
BytesMessageSender.Base
Base class for implementation, which implementsBytesMessageSender.Base.messageSizeInBytes(List)
andBytesMessageSender.Base.messageSizeInBytes(List)
with a given Encoding
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Encoding
encoding()
Returns the encoding this sender requires spans to have.int
messageMaxBytes()
Maximum bytes sendable per message including overhead.int
messageSizeInBytes(int encodedSizeInBytes)
LikemessageSizeInBytes(List)
, except for a single-span.int
messageSizeInBytes(List<byte[]> encodedSpans)
Before invokingsend(List)
, callers must consider message overhead, which might be more than encoding overhead.void
send(List<byte[]> encodedSpans)
Sends a list of encoded spans to a transport such as HTTP or Kafka.
-
-
-
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 usingmessageSizeInBytes(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 invokingsend(List)
, callers must consider message overhead, which might be more than encoding overhead. This is used to not exceedmessageMaxBytes()
.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)
LikemessageSizeInBytes(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
- theencoded 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
- ifclose
was called.IOException
-
-