The Wavefront Query Language lets you retrieve and display the data that has been ingested into Wavefront.
- Time series data The query language is particularly well suited to time series data because it accommodates the periodicity, potential irregularity, and streaming nature of that data type.
- Histograms The query language includes functions for manipulating histograms.
- Traces and spans Use the tracing UI to query traces and spans.
Watch these videos to get you started. The videos use the v1 UI, but the basic workflow remains the same in the v2 UI.
Step 0: What’s a Query?
Before you run your first query, let’s examine a time series and look at the anatomy of a query.
What’s a Time Series?
A time series measures a particular phenomenon over time. In the example below:
- The time series metric is
- Two types are
forehead. In Wavefront, the types can show up as values of a
- This diagram does not show sources, but in Wavefront, you can have a source associated with each time series. In this example, we can have a different time series for each patient.
Anatomy of a Query
Now, let’s look at the anatomy of a query (shown in Chart Builder):
Each query has the following components. Only the metric is required, the other elements are optional, but they help you get the information you’re really interested in.
- A metric (or a constant, such as
10). Above, the metric is temperature. In this example, the metric is
- One or more sources. Above, sources would have been patients. Here, sources could be the host, VM, container, etc. In this example, the source is
app-*– that means metrics that come from
- One or more point tags. Above, we have the
locationpoint tag -
forehead. In this example, we have the
envpoint tag with value
production. Only valid point tags can be queried.
- One or more functions. This example uses the
avg()function, and the
mmedian()function with a 10-minute time window. The Query Language Reference lists each function with a short description and points to reference pages.
Here’s how the same query looks in the Query Editor.
Step 1: Retrieve a Metric
The Chart Builder UI makes it easy to show any metric that’s currently flowing into your Wavefront instance. Follow these steps to explore the sample data, included with each Wavefront instance.
Here’s an annotated screenshot of the first chart you’ll see.
- Chart names are easy to change just by typing.
- For quick zoom in/out, use the hover time selector, which appears when the cursor is on the chart.
- As you zoom in or out, the bucket size (chart resolution) changes.
- Use Share chart or Quick share to share with others.
- Use the Query Editor toggle for some advanced query functionality.
- Notice events that are shown on the time line. These events are often system events associated with alerts, but they can also be user-defined events.
- Make sure that you Save the chart to a new or existing dashboard.
Things to Try
In the chart:
- Use the Hover Time Selector to zoom in and out. You can also select-drag to see part of the chart, then click + or - to return to the default settings.
- Hover over event icons in the Y axis to get details for the event.
- Hover over a time series to see the legend. Press Shift+P to pin the legend.
In Chart Builder:
- Query other
- Switch to Query Editor and add a constant (e.g., 100) – but note that you can’t switch back to Chart Builder!
Step 2: Filter by Source and Point Tag
The example chart is quite busy, but we can use filters to focus in.
|1. Make sure Data is still ~sample.cpu.loadavg.1m.|
|2. Click Filters, select source and type app-* to include only time series if the source name starts with app-. This query uses a wildcard character.|
|3. Press Enter.|
|4. Click the Add button and select env > production as the second filter.|
Things to Try
- Explore the effect of using different source and point tag filters.
- Add more than one filter for each category, for example, several sources.
- Click the Query Editor toggle
</>to see the results in Query Editor.
- Clone the query to experiment more. If you accidentally make a change in the query while you’re in the Query Editor, you can’t return to Chart Builder, so using a clone helps.
- With multiple queries in place, show and hide queries, and drag them to change query order.
Step 3: Apply an Aggregation Function
Aggregation functions allow you to combine points from multiple time series, and to group the results. Let’s take the average first, and then let’s remove the
env filter and instead group by environment.
|1. Make sure Data is still ~sample.cpu.loadavg.1m.|
2. Click Functions, and pick Favorites > avg. The result is a single aggregated time series.
In Query Editor, this query looks like this:
|3. Remove the `env` filter.|
|4. Click Functions > Favorites > avg again.|
5. Select Group by, then select env, and click Apply.
The result is two aggregated time series. You can hover over each line to see which environment it shows.
In the Query Editor, you can add the literal , pointTags (you need the comma!), so the query looks like this:
6. Add a second function. For example, you can use the deriv() function to show the rate of change per second for the average.
Things to Try
Experiment with some of our other functions, either in Chart Builder or in Query Editor.
- Use one of the Moving Window Time Functions to combine or test the values of a time series over a time sliding window.
- Experiment with Filtering and Comparison Functions. For example, use
topk()to return the top
Step 4: See What’s There
Wavefront Query Language has a rich set of functions for many purposes. The Query Language Reference has the details, here’s an overview (in pictures).
Aggregation, Predictive, and Filtering & Comparison Functions
1. Let’s drill down and look at the first set of functions. The image on the right shows the aggregation, filtering, and predictive functions. The Query Language Reference has the syntax for each function. The function syntax links to a reference page.
Standard Time, Moving Time Window, and Missing Data Functions
2. Next, let's look at a second set of functions. The image on the right shows the standard time, moving window time, and missing data functions. The Query Language Reference has the syntax for each function. The function syntax links to a reference page.
Math, String Manipulation, and Miscellaneous functions
3. Finally, we look at the math, string manipulation, and miscellaneous functions (shown in more detail in the query language reference. The Query Language Reference has the syntax for each function. The function syntax links to a reference page.
What’s next depends on the type of data you’re interested in, and how you want to interact with your data.
Query Types for Different Data
Most Wavefront users query for time series metrics, but we support interacting with other data.
Charts for metrics also support the following types of queries:
- Events: Query Wavefront events with
- Histograms: Query histograms with
- Traces and spans: Query trace data from the tracing UI with the tracing Query Builder.
Docs, Videos, and Query Language Recipes
Wavefront documentation includes videos, tutorials, reference, and guides on the query language.
- Query Language Videos get you started and Use Case Videos show off some compelling examples.
- Query builder (for v1) and Chart builder (for v2) can help you come up to speed quickly while using the product.
- If you’re logged in to Wavefront, select Integrations in the taskbar and find the Tutorial or the Tour Pro integration. The Tutorial includes an Interactive Query Language Explorer that shows examples for each function.
- Wavefront Query Language Reference lists each function and gives query language syntax element. Each function name is a link to a reference page for the function.
- For in-depth discussions and examples, we have a reference page for each function and some Query Language Recipes.
This doc set includes videos and explanations from the engineering team that helps you come up to speed quickly:
|How can I combine multiple series?||Aggregating Time Series||Time Series and Interpolation|
|Why does my query return NO DATA?||Maybe the time series don’t match. See When Multiple Series Match (Or Not).|
|I got a warning about pre-aligned data. Why?||Wavefront improves performance by wrapping
|How can I use Wavefront for anomaly detection?||You can use Anomaly Detection on Charts or detect anomalies with functions and statistical functions.||Anomaly Detection with Functions</ul>|
|How can I improve query performance?||Consider bucketing with align(). Investigate internal metrics for optimizing performance.|