zipkin

Class TraceKeys

java.lang.Object

zipkin.TraceKeys

public final class TraceKeys
extends Object

Well-known binary annotation aka Tag 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_ROUTE The route which a request matched or "" (empty string) if routing is supported, but there was no match.
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.
static String	SQL_QUERY The query executed for SQL call.

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 as a filter or to clarify the request path for a given route. For example, the path for a route "/objects/:objectId" could be "/objects/abdc-ff". This does not limit cardinality like HTTP_ROUTE can, so is not a good input to a span name.

The Zipkin query api only supports equals filters. 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. Dropping query parameters also limits the security impact of this tag.

Historical note: This was commonly expressed as "http.uri" in zipkin, even though it was most

See Also:

Constant Field Values

HTTP_ROUTE

public static final String HTTP_ROUTE

The route which a request matched or "" (empty string) if routing is supported, but there was no match. Ex "/objects/{objectId}"

Often used as a span name when known, with empty routes coercing to "not_found" or "redirected" based on HTTP_STATUS_CODE.

Unlike HTTP_PATH, this value is fixed cardinality, so is a safe input to a span name function or a metrics dimension. Different formats are possible. For example, the following are all valid route templates: "/objects" "/objects/:objectId" "/objects/*"

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..."

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

SQL_QUERY

public static final String SQL_QUERY

The query executed for SQL call. Ex. "select * from customers where id = ?"

Used to understand the complexity of a request

See Also:

Constant Field Values