Skip to main content
This topic explains how to use the LaunchDarkly observability query builder and search syntax to find specific sessions, errors, logs, traces, and metrics. You build queries by adding filters that compare the properties and attributes of your observability data to the values you choose.

​
Build queries with the query builder

The query builder is available in the search field on observability pages. It appears in these areas: The query builder represents each condition in your query as a filter. A filter has three parts: a field, an operator, and one or more values. For example, a filter with the field service_name, the operator is, and the value checkout matches data from the checkout service.
The query builder on the Traces page, with filters and the field menu open.

The query builder on the Traces page, with filters and the field menu open.

​
Add and edit filters

Here are the controls for adding, updating, and deleting filters:
ActivityControls
Add a filterClick an empty spot in the query builder, including the space between two filters, to display the fields, operators, and logical operators you can add at that spot. Type characters to filter the available selections. The query builder highlights the best match.

Press Tab or Enter to add the highlighted option, or click a name in the menu.
Add a field and operator togetherType a suggested field name followed by an operator, such as service_name= or service_name is not. The query builder adds both the field and operator and moves to the value entry. You can type the operator as a symbol or as its label.
Add a filter for a field that isn’t suggestedType the field name, then select the “Search for field” option.
Add multiple valuesUse checkboxes in the menu to select multiple values, or use commas to separate multiple, typed values.
Update a filterClick an existing field, operator, or value to change it.
Delete a filterClick the x icon next to the filter. You can also press Backspace to delete one character at a time. Deleting the last character of a field removes the filter.
Run the queryPress Enter when the menu is closed.
When you highlight an option in the menu, a details panel describes it. For fields, the details panel includes the field’s type, its “Most used values,” and when you last searched for it.

​
Operators

Each field offers the operators that apply to its type. If you select more than one value for a filter, the is and is not operators change to display is one of and is not one of. Here are the available operators and the search syntax each one produces:
OperatorField typesSearch syntax
existsAllkey EXISTS
does not existAllkey NOT EXISTS
isAllkey=value
is notAllkey!=value
containsStringkey="*value*"
does not containStringkey!="*value*"
starts withStringkey="value*"
ends withStringkey="*value"
matchesStringkey="/regex/"
does not matchStringkey!="/regex/"
is greater thanNumeric, duration, timestampkey>value
is greater than or equal toNumeric, duration, timestampkey>=value
is less thanNumeric, duration, timestampkey<value
is less than or equal toNumeric, duration, timestampkey<=value
For fields that measure duration, such as duration or fields with names that end in _duration, you can include a unit in the value: h, m, s, ms, us, or ns. For example, duration>=500ms.

​
Combine filters

The query builder joins filters with an implicit AND unless you add a logical operator between them. The “Operators” category in the menu includes these logical operators:
  • AND: Match when both filter expressions are true.
  • OR: Match when either filter expression is true.
  • NOT: Exclude matches for the next filter expression.
  • Logical Group: Group filter expressions in parentheses to evaluate them first.
You can also type AND, OR, or NOT followed by a space to add a logical operator. To change an existing AND to OR, or an OR to AND, click it. To group filters with the keyboard:
  • Type ( before a filter to group it with every filter after it, up to the end of the query or of the group that contains it.
  • Type ) inside a group to end the group there. The filters after it move out of the group.
  • Select filters and type ( or ) to group only the selection.
  • Type ( after the last filter to add an empty group.
On the Traces page, the menu also includes a “Relational Fields” category with span functions, such as Any span and No span. A span function groups filters that other spans in the same trace must match. To learn more, read Span functions for trace search. On the Sessions page, the “Relational Fields” category includes Span, No span, Log, and No log. These group filters that a span or log in the same session must match. To require that events occur in order, add THEN between two of these groups.

​
Copy and paste queries

When you copy filters from the query builder, LaunchDarkly copies them as search syntax, such as service_name=checkout AND environment!=production. When you paste search syntax into the query builder, LaunchDarkly converts it to filters. The page URL also stores your query in search syntax. You can share the URL to link others to your search results.

​
Keyboard shortcuts

Here are the keyboard shortcuts the query builder supports:
ShortcutAction
Shift+Left arrow or Shift+Right arrowSelect filters and logical operators.
Cmd+A or Ctrl+ASelect all.
Cmd+C or Ctrl+CCopy the selection as search syntax.
Cmd+X or Ctrl+XCut the selection.
Delete or BackspaceDelete the selection.
( or )Group the selection in parentheses.
Cmd+Z or Ctrl+ZUndo.
Cmd+Shift+Z, Ctrl+Shift+Z, or Ctrl+YRedo.
Left arrow or Right arrowMove the cursor one character, or into the space between filters.
Alt+Left arrow or Alt+Right arrowMove the cursor one word.
Cmd+Left arrow or Ctrl+Left arrowMove to the start of the query.
Cmd+Right arrow or Ctrl+Right arrowMove to the end of the query.
Tab or EnterAdd the highlighted option in the menu.
EnterRun the query when the menu is closed.

​
Search query syntax

The query builder stores each query in the search syntax that this section describes. Search syntax appears in the page URL and when you copy a query, and you can paste it into the query builder to create filters. Compose your search query with one or more expressions. Each expression can be a comparison between a key and a value, or a logical combination of other expressions. Keywords such as AND, OR, NOT, and EXISTS are not case-sensitive. For example, not exists and NOT EXISTS are equivalent. Here are some examples of search queries:
Find sessions associated with a specific feature flag.
Enter a search value without a key to search on a default key. For logs, the default key is the message, and for traces it is the span_name.
You can also filter for custom attributes you send in sessions, logs, and traces.

​
Keys and values

Keys are identifiers, which can include any combination of alphanumeric characters, underscores (_), periods (.), dashes (-), and wildcards, which are indicated by asterisks (*). Values are strings with any character. To use spaces or special characters, you must enclose the string in quotes (", '). You can use wildcards (*) in values to match on part of a pattern. For example:
  • span_name=gorm.* matches all span_name values that start with gorm.
  • span_name=*.Query matches all span_name values that end with .Query
  • span_name=*orm* matches all values that contain orm
If you want to use a value with a space or special character, you must wrap the value in quotations.

​
Trace and span ID values

LaunchDarkly stores the trace_id, span_id, and parent_span_id fields in the hexadecimal format that OpenTelemetry uses. Datadog displays the same identifiers as decimal numbers. When you filter one of these three fields with a decimal value copied from Datadog, LaunchDarkly also matches the hexadecimal form it stored at ingest. You do not need to convert the identifier yourself. This behavior applies on the Logs, Traces, and Errors pages. Here is an example query that uses a Datadog decimal trace ID:

​
Regex expressions

You can search with regex expressions by using the matches query operator: =/[your regex here]/. For example:
  • clickTextContent=/\w.+\w/ matches all clickTextContent that start and end with any word
  • browser_version=/\d\.\d\.\d/ matches all browser_version values in the form [0-9].[0-9].[0-9]
If you want to use a regex expression with a space or special character, you must wrap the value in quotations. For example:
  • tag="/\w \w/"
  • visited-url="/https://app.launchdarkly.com/\d/.+/"

​
Comparisons

Use operators to compare two different elements in your search query. The following operators are supported:
  • =: Equals
  • !=: Does not equal
  • <: Less than
  • <=: Less than or equal to
  • >: Greater than
  • >=: Greater than or equal to

​
Exist and does not exist

You can search if a key exists or does not exist with the EXISTS operator. For example, to return all the traces with a connected session, use the following query:
EXISTS also works with the NOT keyword. For example, when you only want the root level spans when searching traces, use this query:
You can combine expressions with the logical operators AND, OR, and NOT:
  • AND: Both expressions must be true.
  • OR: At least one of the expressions must be true.
  • NOT: The following expression must be false.
Filters are combined with an implicit AND unless you specify OR. For example:
This is equivalent to:
You can also use parentheses ( AND ) to group values in an expression. For example:
You can also use parentheses to group values in an expression:
The search functionality on the Traces page returns individual spans that make up traces. Span functions help you filter results to show only those spans for traces that contain or don’t contain spans that match one or more conditions. The following span functions are available when you search on the Traces page:
  • any_span( expression ) limits results to spans where the trace contains at least one span that matches the expression.
  • any_span2() and any_span3() operate in the same way as any_span(). The unique function names let you require different spans in the trace to satisfy different conditions in the same query. To learn more, read Using multiple span aliases.
  • no_span( expression ) limits results to spans where the trace contains no spans that match the inner expression.
  • child_span( expression ) limits results to spans that have at least one direct child span matching the expression.
  • parent_span( expression ) limits results to spans where the direct parent span matches the expression.
  • root_span( expression ) limits results to spans where the trace’s root span matches the expression.
Span functions wrap a normal search expression in parentheses. Inside the parentheses, you can use any of the existing operators, including comparisons, EXISTS, AND, OR, and NOT. Here is an example that returns spans whose trace contains at least one span from the auth-service:
Here is an example that returns spans whose trace contains at least one error in an auth-service span:
Here is an example that returns spans whose trace contains no spans with errors:
Here is an example that returns spans that have a direct child span that lasts longer than one second:
Here is an example that returns spans where the direct parent span belongs to the auth-service:
Here is an example that returns spans where the trace’s root span is named checkout:

​
Using multiple span aliases

If you call any_span() more than once in a query, the conditions accumulate against the same span. For example, this query requires a single span in the trace to match both conditions:
To require that different spans in the trace satisfy each condition, use any_span2() or any_span3() for the second condition. Here is an example that returns spans whose trace contains at least one checkout span and another, different span that contains errors:

​
Combining span functions with regular search expressions

You can combine span functions with regular search expressions in the same query. Regular expressions filter the displayed spans by their own properties, while span functions filter the displayed spans by conditions that apply to the same trace. Here is an example:
This query returns spans in the production environment whose trace also contains at least one auth-service span that lasts longer than one second.

​
Limitations

You can only use span functions as top-level filters in a query. Span functions have the following restrictions:
  • You cannot wrap span functions in parentheses.
  • All span functions at the top level of a query are joined with an implicit AND operator. You cannot combine span functions using AND, OR, or NOT outside of the function call.
These restrictions apply to the span function itself. Inside the parentheses, the inner expression supports the full set of search operators, including AND, OR, NOT, EXISTS, and grouping.

​
Saved searches

Saved searches are a set of search filters that apply to sessions or errors. Saved searches are useful if you want to quickly view sessions or errors that relate to a certain population of your end users. To save a search, click the Save button below the query builder. The searches you build are reflected in the URL parameters when you’re accessing sessions through the LaunchDarkly UI. You can share these URLs with others to deep link to search results, or create them programmatically.

​
Session-specific searching

To learn more about search terms and defaults specific to session replays, read Search in the Session replay topic. LaunchDarkly flattens the nested properties of the track events your application records. This lets you query each individual property. To learn more, read Search by track event properties.

​
Configure error views

You can configure the Errors page to display different subsets of errors. Use the date menu to select a time range, and use the query builder to filter the errors.