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:

Simplified spans vs. spans_sample visual

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 where service == supernova.
  • spans_sample queries operate on the two service == 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.

Scatter plot for view trace-level data

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.

Scatter plot for view service impact

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.

Scatter plot for view customer impact

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, and memcached. And another involves only these services: apache, auth, and web.

  • 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.

Scatter plot for view all services

Next, visit the links below to learn more about UQL, data visualization, and spans queries.