API query syntax

Use UQL in the API

You can use Cloud Observability’s Unified Query Language (UQL) for most of the endpoints where query strings are needed.

The Streams and Snapshots endpoints use a different query syntax.

Learn about UQL:

• UQL cheat sheet
• UQL reference

Query syntax for Streams and Snapshots

The Streams and Snapshot endpoints use our legacy query syntax. Use the following key/value pairs. Use IN or NOT IN to build the query. Values must be an exact match - capitalization matters.

Supported keys

Key	Value	Example
service	Service’s name	service IN (“iOS”) Returns spans from the iOS service service NOT IN (“android”) Returns spans from every service but android
operation	Operation’s name	operation IN (“/api/get-profile”) Returns spans from the /api/get-profile operation
attribute_name	Custom attribute’s name, in quotes. For example customer or aws-region	aws-region IN (“east”) Returns spans where the aws-region tag value is east.
lightstep.span_id lightstep.trace_id lightstep.tracer_id	Cloud Observability generated attributes. The ID for a span, trace, or tracer.	lightstep.span_id IN (ad5490ghl) Returns that specific span lightstep.trace_id NOT IN (cebr0875xl) Returns spans in traces other than the cebr0875xl trace lightstep.tracer_id NOT IN (cebr0875xl) Returns spans that were produced from tracers other than the cebr0875xl tracer

Querying Multiple Keys and Values

Use the following syntax rules to build complex queries:

• Use a comma to query multiple values for a key. Multiple values are treated as OR operations.

  Example:
  service IN (“iOS”,“android”)
  Returns spans that are from either the iOS or android service

  “customer” NOT IN (“smith”,”jones”)
  Returns spans that do not have smith or jones as the value for the customer tag.

• Only one set of values per key are allowed.

  Example:
  Valid:
  service IN (“iOS”, “android”) Not valid:
  service IN (“iOS”, “android”) AND service IN (“web”)

• Use AND operations to build queries with multiple key/value sets (the OR operation is not supported).

  Example:
  service IN (“iOS”,“android”) AND “aws_region” IN (“us_east”)
  Returns spans that are in either the iOS or android service and are in the us_east AWS region.

  "lightstep.trace_id" NOT IN (“etla347uz”, “aeo7584xco”) AND “error” IN (“true”)
  Returns spans that are not in traces with the ID etla347uz or aeo7584xco and have the value true for the error tag.

Full Example

service IN (“iOS”, “android) AND operation IN (“auth”, “transaction-db”) AND “aws-region” NOT IN (“us-west”) AND "lightstep.span_id" IN (“ad753587das”, “zb18857cat”)

Returns spans with the ID of either ad753587das or zb18857cat that are in either the iOS or android service, from either the auth or transaction-db operation, and are not in the us-west AWS region.

Updated Jan 6, 2023