Query Syntax

You can build queries for services, operations, tags, span IDs and trace IDs using 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
"tag_name"	Custom tag’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"	Lightstep generated tags. 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.