Learn how to write spans() queries.

Summary

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

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

Returns the traces that contain one or more qualifying spans, where a qualifying span matches 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 qualifying 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 qualifying 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, and then returns the set of traces that contain one or more of these spans. 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. For more information about the set of returned traces, see Understanding Trace Queries.

You submit a spans() function using the Query Editor on the Traces page. You can use autocompletion to discover the span filters available for your query. Using the spans() function is a power-user alternative to using Query Builder.

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 display the traces that include spans for calls to makeShirt, run the following query:

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

To display the traces that include spans for any operation in the styling service, run the following query:

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

To display the traces that include spans for any operation in the beachshirts application executing on either of two specified hosts, run the following query:

  • limit(20, 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 20 qualifying spans that are longer than 30 milliseconds, you can combine the limit(), highpass(), and spans() functions as follows:

  • limit(20, 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 15, and return just the traces that contain the spans from that limited set:
limit(15, 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 traces in which the qualifying spans 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 traces in which the qualifying spans are shorter than 10 milliseconds:
lowpass(10ms, spans("makeShirts", application="beachshirts"))