Lightstep offers scatter plots for spans_sample
queries.
This page describes spans_sample
queries and shows several examples.
The content is for anyone looking to query and learn about their trace data.
Query overview
spans_sample
queries are part of Lightstep’s Unified Query Language (UQL),
and they work with trace data.
spans_sample
queries give you contextual, trace-level insights into your data.
They let you filter on a span attribute, and then further filter on attributes across that span’s trace.
With spans_sample
queries, you can:
- Explore latency issues within traces.
- Find every service involved in a trace.
- Investigate specific spans from a customer-specific trace, even if the customer attribute is on a different span.
You can use spans_sample
queries in notebooks or dashboards.
And Lightstep visualizes the output in scatter plots.
Understand spans
vs. spans_sample
UQL supports spans
and spans_sample
queries.
The queries have different approaches to trace data:
spans |
spans_sample |
|
---|---|---|
Visualizations | Visualize unsampled time series in line charts. | Visualize sampled spans in scatter plots. |
Query behavior | Operate on specific spans. | Operate on whole traces. |
This diagram uses a simplified case to highlight the query-behavior difference:
The diagram has two traces.
The first trace has two spans, and one span has the service == supernova
attribute.
The second trace has three spans, and one span has the service == supernova
attribute.
spans
and spans_sample
queries give you different insights into that data:
spans
queries only operate on the two spans whereservice == supernova
.spans_sample
queries operate on the twoservice == supernova
spans and the other three spans.
spans_sample
queries focus on the whole trace, giving you more contextual insights into your data.
Example queries and scatter plots
The sections below show several spans_sample
examples.
The examples use notebooks, but you can also run the queries in dashboards.
View trace-level data
Use spans_sample
queries to explore trace-level data.
This query returns spans from traces where at least one span has this attribute: service == warehouse
:
1
spans_sample service == warehouse | assemble
The scatter plot below visualizes the results. And the table shows the End time and Duration for sample spans. You can also click Export to csv to export the data to a file with comma-separated values.
View service impact
Use trace_filter
to explore the impact of a service within specific traces.
This query returns spans for one service (warehouse
) filtered to spans from traces where at least one span has the android
service:
1
spans_sample service == warehouse | assemble | trace_filter service == "android"
The scatter plot below visualizes the results. And the table shows the End time and Duration for sample spans. You can also click Export to csv to export the data to a file with comma-separated values.
View customer impact
Use trace_filter
to explore spans related to an attribute, even if that attribute is on a different span.
This query returns spans for an operation (database-update
) filtered to spans from traces where at least one span has the ProWool
customer:
1
spans_sample operation == "database-update" | assemble | trace_filter customer == "ProWool"
The scatter plot below visualizes the results. And the table shows the End time and Duration for sample spans. You can also click Export to csv to export the data to a file with comma-separated values.
View all services
Use summarize_by
to group results by specific trace-level attributes.
This query returns all services related to a specific operation (/api/get-catalog
):
1
spans_sample operation = "/api/get-catalog" | assemble | summarize_by [service]
The scatter plot below visualizes the results. The tables also display query results:
-
Aggregates - Each row in the service column shows an unordered list of services involved in that trace.
For example, in the image below, one trace with
operation = "/api/get-catalog"
involves these services:iOS
,krakend-api-gateway
, andmemcached
. And another involves only these services:apache
,auth
, andweb
. -
Span samples - Each row shows the End time and Duration for a span that started the trace and where
operation = "/api/get-catalog"
. The service column shows an unordered list of services involved in that span’s trace.
Next, visit the links below to learn more about UQL, data visualization, and spans
queries.