Learn how to write spans() queries.

Summary

spans("<operationName>" [and|or|not <filterName>="<filterValue>"])

spans(<filterName>="<filterValue>" [and|or|not <filterName>="<filterValue>"])

Returns the spans that match the specified operation and filters. You normally limit the results by combining spans() with one or more spans filtering functions.

Parameters

ParameterDescription
operationName Name of the operation that each matching span must represent. For example, specify "dispatch" to match the spans that represent calls to an operation named dispatch. Omit this parameter to find the spans that represent calls to any operation.
filterName A span filter that each matching span must match. Span filters let you limit which spans to return traces for. You can optionally specify multiple span filters separated by the Boolean operators (and, or, not).
filterValue Value accepted by a specified filterName.

Description

The spans() function finds spans that match the description you specify. You describe the spans of interest by providing an operation name, one or more filters, or a combination of these, to specify the characteristics the spans must match.

You submit a spans() function using the Query Editor in the Traces browser. You can use autocompletion to discover the span filters available for your query.

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

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 spans() with the limit() function.

To return the spans for calls to `makeShirt:

  • limit(100, spans("makeShirts" and application="beachshirts" and service="styling"))

To return the spans for any operation in the styling service:

  • limit(100, spans(application="beachshirts" and service="styling"))

To return the spans for any operation in the beachshirts application executing on either of two specified hosts:

  • limit(100, spans(application="beachshirts" and source=prod-app1 or source=prod-app10))

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

FilterDescriptionExample
application Name that identifies an instrumented application, for example, beachshirts. Matches the spans that represent operations that are performed by the specified application. spans(application="beachshirts")
service Name that identifies an instrumented microservice, for example, delivery. Matches the spans that represent operations that are performed by the specified microservice. spans(service="delivery")
cluster Name of a group of related hosts that serves as a cluster or region in which an instrumented application runs, for example, us-west-2. Matches the spans that represent operations that are executed on the specified cluster. spans(cluster="us-west-2")
shard Name of a subgroup of hosts within a cluster, for example, secondary. Matches the spans that represent operations that are executed on the specified shard. spans(shard="secondary")
source Host or container that an instrumented application is running on. Matches the spans that represent operations that are executed on the specified source. spans(source="prod-app1")
traceId Unique identifier for a trace. Matches all spans that belong to the specified trace. spans(traceId="5b309723-fb83-4c9c-afb6-f0dc4b2bff13")
<spanTag> Custom tag defined in your application code. Matches spans that are associated with the specified custom span tag. spans(environment="production")

Spans Filtering Functions

You can use spans filtering functions to provide additional levels of filtering for the set of spans that are matched by the spans() function.

Note: To keep query execution manageable, it is highly recommended that you combine spans() with at least the limit() function.

Each spans filtering function has a spansExpression parameter, which can be a spans() function or one of the other spans filtering functions. For example, to return traces for up to 100 qualifying spans that are longer than 30 milliseconds, you can combine the limit(), highpass(), and spans() functions as follows:

  • limit(100, highpass(30ms, spans("dispatch", application="beachshirts" and service="delivery")))
Spans Filtering FunctionDescription and Example
limit(<numberOfSpans>, <spansExpression>) Limits the set of spans that are matched by spansExpression to the specified numberOfSpans.
Note: Because the ordering of matched spans is unpredictable, you cannot use limit() to page through a set of results to obtain the traces that contain the next group of spans.

Example: Limit the set of qualifying spans to 50:
limit(50, spans("makeShirts", application="beachshirts"))
highpass(<spanDuration>, <spansExpression>) Limits the set of spans that are matched by spansExpression to include only spans that are longer than spanDuration. Specify spanDuration as an integer number of milliseconds, seconds, minutes, hours, days or weeks (1ms, 1s, 1m, 1h, 1d, 1w).

Example: Return the qualifying spans that are longer than 3 seconds:
highpass(3s, spans("makeShirts", application="beachshirts"))
lowpass(<spanDuration>, <spansExpression>) Limits the set of spans that are matched by spansExpression to include only spans that are shorter than spanDuration. Specify spanDuration as an integer number of milliseconds, seconds, minutes, hours, days or weeks (1ms, 1s, 1m, 1h, 1d, 1w).

Example: Return the qualifying spans that are shorter than 10 milliseconds:
lowpass(10ms, spans("makeShirts", application="beachshirts"))