traces() Function

Summary

traces("<fullOperationName>" [,|and|or [not] <filterName>="<filterValue>"] ...)

traces(<filterName>="<filterValue>" [,|and|or [not] <filter2Name>="<filter2Value>"] ...)

traces(<spansExpression>, [<spansExpression])

Returns the traces that contain one or more qualifying spans, where a qualifying span matches the specified operation and span filters. Available only in the Query Editor in the Traces browser. Can be combined with one or more filtering functions.

Parameters

Description

The traces() function returns a set of traces. Each trace contains at least one qualifying member span. A span qualifies if it matches the description you specify, which might consist of an operation name, one or more span filters, or a combination of these.

You submit a traces() function using the Query Editor in the Traces browser. Using the traces() function is a power-user alternative to using Query Builder.

traces() returns a trace:

• If it contains a member span that matches the entire specified description.

• If the description is a Boolean expression that combines multiple span filters, then the same span must satisfy all the filters.

  For example, the result set for traces(service=shopping and source=web1) includes any trace that has at least one member span that is associated with both of the tags service=shopping and source=web1. The result set does not include, e.g., a trace that has one member span with service=shopping and a different member span with source=web1.

To keep query execution manageable, combine traces() with a filtering function such as limit() in the same query.

To qualify spans based on their length, specify a spans() query that is wrapped in a spans filtering function such as highpass().

Examples

Assume your team has instrumented an application called beachshirts for tracing. This application has a service called styling that executes an operation called makeShirts. The application is deployed on several hosts in each of several clusters.

Note: To keep query execution manageable, these examples use traces() with the limit() function.

Display the traces that include spans for calls to makeShirt:

limit(100, traces("beachshirts.styling.makeShirts"))

Display the traces that include spans for any operation in the styling service:

limit(100, traces("beachshirts.styling.*"))

Display the traces that include spans for any operation in the beachshirts application executing on either of two specified hosts:

limit(100, traces("beachshirts.*.*" and (source="prod-app1" or source="prod-app10")))

Display the traces that include spans for calls to makeShirt that are shorter than 3 milliseconds:

limit(100, traces(lowpass(3ms, spans("beachshirts.styling.makeShirts"))))

Span Filters

Span filters allow you to limit which spans to return traces for. Span filters are key/value pairs associated with spans. Developers define the available span filters (also called application tags) as part of instrumenting the application code for tracing. If you did not instrument the code yourself, you can use autocompletion in the Query Editor to discover the available span filters.

The general format for a span filter is <filterName>="filterValue".

Filtering Functions

You can use filtering functions to provide additional levels of filtering for the results of the traces() function.

You can combine filtering functions. For example, to return up to 100 traces that are longer than 30 milliseconds, you can combine the limit(), highpass(), and traces() functions as follows:

• limit(100, highpass(30ms, traces("beachshirts.delivery.dispatch")))

Note: To keep query execution manageable, combine traces() with at least the limit() function.