zipkin

Class TraceKeys

java.lang.Object

zipkin.TraceKeys

public final class TraceKeys
extends Object

Well-known binary annotation keys.

Overhead of adding Trace Data

Overhead is directly related to the size of trace data exported out of process. Accordingly, it is better to tag what's important for latency troubleshooting, i.e. a whitelist vs. collecting everything and filtering downstream. The keys listed here are very common in tracing tools, and are considerate to the issue of overhead.

When evaluating new keys, consider how much additional data it implies, and if that data is critical to classifying, filtering or displaying traces. More data often means larger systems, less retention, or a lower sample rate.

For example, in zipkin, a thrift-encoded span with an "sr" annotation is 82 bytes plus the size of its name and associated service. The maximum size of an HTTP cookie is 4096 bytes, roughly 50x that. Even if compression helps, if you aren't analyzing based on cookies, storing them displaces resources that could be used for more traces. Meanwhile, you have another system storing private data! The takeaway isn't never store cookies, as there are valid cases for this. The takeaway is to be conscious about what's you are storing.

Field Summary

Fields

Modifier and Type	Field and Description
static String	HTTP_HOST The domain portion of the URL or host header.
static String	HTTP_METHOD The HTTP method, or verb, such as "GET" or "POST".
static String	HTTP_PATH The absolute http path, without any query parameters.
static String	HTTP_REQUEST_SIZE The size of the non-empty HTTP request body, in bytes.
static String	HTTP_RESPONSE_SIZE The size of the non-empty HTTP response body, in bytes.
static String	HTTP_STATUS_CODE The HTTP status code, when not in 2xx range.
static String	HTTP_URL The entire URL, including the scheme, host and query parameters if available.

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HTTP_HOST

public static final String HTTP_HOST

The domain portion of the URL or host header. Ex. "mybucket.s3.amazonaws.com"

Used to filter by host as opposed to ip address.

See Also:

Constant Field Values

HTTP_METHOD

public static final String HTTP_METHOD

The HTTP method, or verb, such as "GET" or "POST".

Used to filter against an http route.

See Also:

Constant Field Values

HTTP_PATH

public static final String HTTP_PATH

The absolute http path, without any query parameters. Ex. "/objects/abcd-ff" Used to filter against an http route, portably with zipkin v1.

In zipkin v1, only equals filters are supported. Dropping query parameters makes the number of distinct URIs less. For example, one can query for the same resource, regardless of signing parameters encoded in the query line. This does not reduce cardinality to a HTTP single route. For example, it is common to express a route as an http URI template like /resource/{resource_id}. In systems where only equals queries are available, searching for http/path=/resource won't match if the actual request was /resource/abcd-ff.

Historical note: This was commonly expressed as "http.uri" in zipkin, eventhough it was most often just a path.

See Also:

Constant Field Values

HTTP_URL

public static final String HTTP_URL

The entire URL, including the scheme, host and query parameters if available. Ex. "https://mybucket.s3.amazonaws.com/objects/abcd-ff?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Algorithm=AWS4-HMAC-SHA256..."

Combined with HTTP_METHOD, you can understand the fully-qualified request line.

This is optional as it may include private data or be of considerable length.

See Also:

Constant Field Values

HTTP_STATUS_CODE

public static final String HTTP_STATUS_CODE

The HTTP status code, when not in 2xx range. Ex. "503"

Used to filter for error status.

See Also:

Constant Field Values

HTTP_REQUEST_SIZE

public static final String HTTP_REQUEST_SIZE

The size of the non-empty HTTP request body, in bytes. Ex. "16384"

Large uploads can exceed limits or contribute directly to latency.

See Also:

Constant Field Values

HTTP_RESPONSE_SIZE

public static final String HTTP_RESPONSE_SIZE

The size of the non-empty HTTP response body, in bytes. Ex. "16384"

Large downloads can exceed limits or contribute directly to latency.

See Also:

Constant Field Values