spans() Function

Summary

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

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

Returns the spans that match the specified operation and filters. You use spans() as a parameter of the traces() function, typically after combining spans() with one or more spans filtering functions.

Parameters

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 that the spans must match.

You use spans() by including it as a parameter of the traces() function. Doing so allows you to filter traces according to the duration of a particular span. For example, the following query returns a trace only if it has at least one span that both represents a makeShirts operation and lasts longer than 11 seconds:

limit(100, traces(highpass(11s, spans("beachshirts.styling.makeShirts"))))

This is different from a query that wraps highpass around traces(). For example, the following query returns a trace only if the entire end-to-end trace is longer than 11 seconds.

limit(100, highpass(11s, traces(spans("beachshirts.styling.makeShirts"))))

Note: the following two queries are equivalent:

limit(100, traces("beachshirts.styling.makeShirts"))          //  spans() is implicit
limit(100, traces(spans("beachshirts.styling.makeShirts")))   //  spans() is explicit

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 the several clusters.

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

• To display the traces that include long spans for calls to makeShirt:

  limit(100, traces(highpass(11s, spans("beachshirts.styling.makeShirts"))))
  

• To display the traces that include short spans for any operation in the styling service:

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

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

  limit(100, traces(spans("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".

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.

Each spans filtering function has a spansExpression parameter, which can be a spans() function or one of the other spans filtering functions.

Spans Operators

Use the following operators to get details or find the relationship between services in an application and their operations using the spans() functions.