Cisco Observability Platform Query Service API

UQL Types

This topic describes the Unified Query Language types and functions.

AttributeNames

Represents a list of attribute names with their count in an aggregation group of items.

count(): Long

Number of items in an aggregation group that has the respective attribute.

Return type: Long

name(): String

Name of the attribute that is present on the items in an aggregation group.

Return type: String

Attributes

Represents a single attribute (name-value pair) or a group of attributes.

The default attributes observation set is {name, value}

name(): String

It returns the attribute name.

Return type: String

value(): Any

It returns the attribute value.

The attribute value type is defined in a schema. If it is not defined in the schema, the attribute value type is String.

Return type: Any

Baseline

The baseline is a time-lagged metric calculation (usually average) that provides a basis for comparisons of the past metric values to the current values.

The platform provides a configuration tool to define multiple calculation strategies for baselines. For example an average of the last 7 days or an average of the same time during past days. This type represents a result of a single baseline calculation.

standardDeviation(): Number

The standard deviation of the baseline.

Return type: Number

value(): Number

The value of the baseline.

See also standardDeviation. Combination of the baseline value with the standard deviation provides a capability to define the upper and the lower boundary of normal values of the metric.

Return type: Number

CommonEntity

Represents a single entity or a group of entities.

Entity functions can be used in topology filters (in FROM clause) or fetched (FETCH clause).

attributes(): EntityAttributes

Retrieves all attributes. The result is a table containing columns with attribute names and values. Multi-value attributes are listed multiple times for each of their value.

Return type: EntityAttributes

attributes(attributeName: String): Any

Retrieves the attribute value by the given name.

Parameters:

  • attributeName - name of the attribute associated with the retrieved value.

Return type: Any

Example:

Fetch the ID and the cluster name for the pods that are not in cluster_a.

Code Snippet
CopyFETCH pods.id, pods.attributes("k8s.cluster.name")
FROM pods: entities(k8s:pod)[attributes("k8s.cluster.name") != "cluster_a"]

coalesceAttributes(attributeNames: ...String): Any

Returns the first non-null value of the attributes with the given names. It can be fetched, used in filters, and used for ordering.

It is useful when an entity name is represented by different attributes for different entity types.

Parameters:

  • attributeNames - names of the attributes associated with the non-null value.

Return type: Any

Example:

Code Snippet
CopyFETCH id, name: coalesceAttributes(spacefleet.shield.id, spacefleet.torpedo.id)
FROM entities(spacefleet:torpedo, spacefleet:shield)

createdAt(): Timestamp

Retrieve a timestamp an entity was created at.

Return type: Timestamp

events(eventIds: ...EventTypeId): CommonEvent

Retrieves the events in the following ways:

  • fetch events for the fetched entities

    FETCH events(...eventIds) FROM entities

  • fetch events without topology restrictions

    FETCH events(...eventIds)

It is possible to provide a filter to constrain the list of events fetched. Also, a list of event-related observations can be provided to override default set of observations.

Parameters:

  • eventIds - event type identifiers to retrieve the events.

Return type: CommonEvent

hasTag(tagName: String): Boolean

Checks whether an entity contains a tag with the given name.

Parameters:

  • tagName - name of the tag associated with an entity.

Return type: Boolean

id(): ObjectId

Retrieves an entity identifier.

Return type: ObjectId

isActive(): Boolean

Checks whether an entity was active in the selected time interval. Note that the time interval can be specified by using timerange SINCE and UNTIL.

Return type: Boolean

metrics(): CommonMetric

Retrieves the measurements of the fetched entities.

Return type: CommonMetric

metrics(metricId: MetricTypeId): CommonMetric

Retrieves the measurements of the given metric type of the fetched entities.

The resulting measurements are returned separately for each metric source that they were reported by.

Parameters:

  • metricId - The metric type identifier to retrieve the measurements.

Return type: CommonMetric

metrics(metricId: MetricTypeId, source: String): CommonMetric

Retrieves the measurements of the given metric type and source of the fetched entities.

Parameters:

  • metricId - The metric type identifier to retrieve the measurements.

  • source - The particular metric source to retrieve the measurements.

Return type: CommonMetric

ofType(typeId: EntityTypeId, typeIds: ...EntityTypeId): Boolean

Checks whether an entity is of the given type.

Parameters:

  • typeId - Type ID to check for the entities.
  • typeIds - Optional or additional type IDs to check for the entities.

Return type: Boolean

spans(): Span

Fetches spans. You can specify filter to constrain the returned list of spans.

A list of span-related observations can be provided. If missing, default set of observations is returned.

Return type: Span

Example:

Fetch spans of trace trace1234 and return only spanId, name, duration and attributes of the spans.

Code Snippet
CopyFETCH spans()[traceId = 'trace1234']{spanId, name, duration, attributes}

sources(metricId: MetricTypeId): ObservationSet

Retrieves the metric sources of the given metric type the measurements were reported by the fetched entities.

Parameters:

  • metricId - The metric type identifier to retrieve the metric sources for.

Return type: ObservationSet

tags(): Tags

Retrieves all tags. The result is a table containing columns with tag names and values. Multi-value tags are listed multiple times for each of their value.

Return type: Tags

tags(tagName: String): Tag

Retrieves tag value by the given name.

Parameters:

  • tagName - name of the tag for which the value is retrieved.

Return type: Tag

traces(): Trace

Fetches traces.

Traces are filtered to only those that passed through entities resolved in the FROM clause, should the FROM clause be provided. The trace pass through an entity if the entity ID is reported in theentityIds list of the trace.

Filter can be provided to further constrain the returned list of traces.

A list of trace-related observations can be provided. If missing, default set of observations will be returned.

Return type: Trace

Example:

Fetch traces that have some errors reported. Return only traceId, name, startedAt and numErrors of the traces.

Code Snippet
CopyFETCH traces()[numErrors > 0]{ traceId, name, startedAt, numErrors }
FROM entities(spacefleet:torpedo)

tracesByOrigin(): Trace

Fetches traces that originated in entities resolved from FROM clause.

Traces are filtered to only those that originated in entities resolved in the FROM clause, should the FROM clause be provided. The trace originated in an entity if the entity ID is reported in the trace's originEntityIds list.

If FROM clause is not provided, tracesByOrigin() behaves exactly the same as traces().

Filter can be provided to further constrain the returned list of traces.

A list of trace-related observations can be provided. If missing, default set of observations will be returned.

Return type: Trace

Example:

Fetch traces that have some errors reported and return only traceId, name, startedAt and numErrors of the traces.

Code Snippet
CopyFETCH tracesByOrigin()[numErrors > 0]{ traceId, name, startedAt, numErrors }
FROM entities(spacefleet:torpedo)

type(): TypeId

Retrieves fully qualified entity type name. For example spacefleet:torpedo.

Return type: TypeId

updatedAt(): Timestamp

Retrieves the timestamp when the entity was last updated.

Return type: Timestamp

CommonEvent

Represents the result of events function.

attributeCardinality(attributeName: String): Long

Aggregation function retrieves number of unique values of a given attribute.

Parameters:

  • attributeName

Return type: Long

attributes(): Attributes

Retrieves all attributes of an event. The result is a table containing columns with attribute names and values. Multi-value attributes are listed multiple times for each of their value.

Return type: Attributes

attributes(attributeName: String): EventAttribute

Retrieves the value of an attribute with given name.

Parameters:

  • attributeName

Return type: EventAttribute

count(): Long

Aggregation function that retrieves the number of events in the observation group.

Return type: Long

entityId(): ObjectId

Retrieves the entity ID of the entity that reported the event or events in the observation group.

Return type: ObjectId

lastEvent(): CommonEvent

Aggregation function that retrieves the chronologically last or new event that was recorded for the observation group. The standard event dimensions are selectable for the last events.

You need to specify an aggregation dimension to the aggregation function.

Return type: CommonEvent

Example:

Fetch latest event for each value of attribute type of the shield_event.

Code Snippet
CopyFETCH events(spacefleet:shield_event){
    attributes("type"),
    lastEvent(){
        timestamp,
        attributes("description")
    }
}

raw(): String

Retrieves raw representation of the event. An event might not have a raw representation, only attributes and tags.

Return type: String

recordId(): DocumentId

Retrieves a unique identifier of the event. This value could be used later in the filter of events function to retrieve a specific event.

Return type: DocumentId

source(): String

Retrieves the name of the source that reported the event.

Return type: String

sum(valueExtractor: EventDimension): Double

Retrieves the mathematical sum of the attribute name for the event. It requires the selection of an event dimension, which at this time, only attribute is supported. The given attribute must be of a numeric type or an array of a numeric type.

Parameters:

  • valueExtractor - The event dimension that serves as the value to be summed.

Return type: Double

Example:

Count the torpedoes that were reloaded during the last 15 minutes.

Code Snippet
CopyFETCH events(spacefleet:torpedoes_reloaded)
    { sum(attributes(count)) }
SINCE now - 15m

spanId(): String

Retrieves the span ID of the span during which the event was reported.

Return type: String

tags(): Tags

Retrieves all tags of an event. The result is a table containing columns with tag names and values. Multi-value tags are listed multiple times for each of their value.

Return type: Tags

tags(tagName: String): Tag

Retrieves the value of a tag with the given name.

Parameters:

  • tagName

Return type: Tag

timeBucket(): Timestamp

Function specifies an aggregation dimension to be used together with an aggregation function. The events will be grouped by their timestamp into default-sized buckets.

Return type: Timestamp

timeBucket(size: Duration): Timestamp

Function specifies an aggregation dimension to be used together with an aggregation function. The events is grouped by their timestamp into buckets with given size.

Parameters:

  • size

Return type: Timestamp

timestamp(): Timestamp

Retrieves the event creation timestamp.

Return type: Timestamp

traceId(): String

Retrieves the trace ID of the trace during which the event was reported.

Return type: String

type(): EventTypeId

Retrieves the type of the event.

Return type: EventTypeId

CommonMetric

Represents the result of the metrics function.

attributes(attributeName: String): String

Returns the value of the specified attribute of the metric.

Must be used together with at least one consumption function (e.g. sum). The returned values of the specified consumption functions is sliced by the given attribute values.

If the given attribute is not present, the specified consumption functions do not return any data.

Parameters:

  • attributeName - The name of the attribute to retrieve.

Return type: String

average(): Number

Returns an average (arithmetic mean) value of the metric.

Return type: Number

baseline(baselineId: BaselineConfig): Baseline

The baseline aggregation function returns the computed baseline values of the metric.

Parameters:

  • baselineId - The baseline ID to get the baseline values.

Return type: Baseline

count(): Number

Returns a number denoting how many times a given metric was reported during the given time interval.

Return type: Number

groupCount(): Number

Denotes a number of entities participating in a space aggregation.

Return type: Number

histogram(bucketCount: Long): MetricHistogram

The histogram consumption returns the count of reported values distributed in groups. Each group is a bucket with a range of values. The number of buckets is determined by the bucketCount parameter.

Note that the actual number of buckets may be lower than the specified bucketCount.

The range of values in each bucket is determined by the platform.

Parameters:

  • bucketCount - The upper bound of the number of buckets to be returned. The actual number of buckets may be lower.

Return type: MetricHistogram

max(): Number

Denotes the maximal reported value of the given measurement.

Return type: Number

min(): Number

Denotes the minimal reported value of the given measurement.

Return type: Number

percentile(percentile: Double): Number

Returns the n-th percentile of the reported metric.

Parameters:

  • percentile - The percentile to be calculated. The value must be between 0 and 100 (both inclusive).

Return type: Number

pRange(leftBoundary: Double, rightBoundary: Double): Number

Returns a number between 0 and 1 denoting a fraction of reported metric values that fall within the provided range as a parameter.

Note that

  • pRange(0, x) is equivalent to pRange(x)
  • pRange(x, y) is equivalent to pRange(y) - pRange(x)

Parameters:

  • leftBoundary - The left boundary of the value range.

  • rightBoundary - The right boundary of the value range.

Return type: Number

pRange(rightBoundary: Double): Number

Returns a number between 0 and 1 denoting a fraction of reported metric values that were less or equal to the provided parameter. As such, it is an inversion of the percentile consumption function.

Note that

  • pRange(x) is equivalent to pRange(0, x)
  • pRange(x) * 100 = y while percentile(y) = x

Parameters:

  • rightBoundary - The right boundary of the value range.

Return type: Number

ratePerMin(): Number

Returns the average rate of change per minute.

It is the sum of the reported values during a particular time span divided by the number of minutes of that time span.

Return type: Number

ratePerSec(): Number

Returns the average rate of change per second.

It is the sum of the reported values during a particular time span divided by the number of seconds of that time span.

Return type: Number

source(): String

Returns the source of the metric.

It must be used together with at least one consumption function, for example, sum. The returned values of the specified consumption functions is sliced into buckets denoted by different sources.

Return type: String

stdDev(): Number

Denotes the standard deviation of the reported values of the given metric.

Return type: Number

sum(): Number

Denotes the mathematical sum of the reported values of the given metric.

Return type: Number

sumCumulative(): Number

Returns the latest sum value of cumulative metrics.

Return type: Number

tags(tagName: String): String

Returns the value of the specified tag of the metric.

It must be used together with at least one consumption function, for example, sum. The returned values of the specified consumption functions is sliced by the given tag values.

If the given tag is not present, the specified consumption functions do not return any value.

Parameters:

  • tagName - The name of the tag.

Return type: String

timestamp(): Timestamp

Returns the timestamp of the reported metric value.

It must be used together with at least one consumption function, for example, sum. The returned values of the specified consumption functions will be returned as time series.

The granularity of the time series, which is the duration of the data points is controlled globally from the LIMITS clause of the UQL query. The granularity varies from one minute to longer periods depending on the duration of the time range and the age of the reported values.

The returned time series granularity is never higher than the specified global granularity.

Return type: Timestamp

value(): Number

Denotes the time aggregated reported value of the given measurement.

The semantics of the value function is determined by the type of the measurement.

Return type: Number

weightValue(): Number

Denotes the weight value of the given metric.

The weightValue and weightValueSquare are used to calculate the standard deviation. The formula for the weightValue is determined by the type of the measurement.

Return type: Number

weightValueSquare(): Number

Denotes the weight value of the given metric.

The weightValueSquare and weightValue are used to calculate the standard deviation. The formula for the weightValueSquare is determined by the type of the measurement.

Return type: Number

EntityAttributes

Represents a single entity attribute (name-value pair) or group of entity attributes.

The default entity attributes observation set is {name, value}

value(): Any

Returns the attribute value. The attribute value type is defined in a schema or is String for attributes undefined in the schema.

Return type: Any

name(): String

It returns the attribute name. Return type: String

MetricHistogram

Represents the result of the metric histogram function.

The histogram function result denotes a set of buckets, each bucket representing a range of measurements. The bucket is defined by the start measurement value and the size. The measurements falling into the bucket are greater or equal to the start value and less than the start value of the next bucket.

count(): Long

The number of the reported measurements falling into a particular histogram bucket.

Return type: Long

size(): Number

The size of the histogram bucket.

The size of the bucket is the difference between the start value of the bucket and the start value of the next bucket.

Return type: Number

startValue(): Number

The start value of the histogram bucket.

The measurements falling into the bucket are greater or equal to this value while less than the next bucket.

Return type: Number

Span

Represents the result of the spans function.

attributeNames(): AttributeNames

List of attributes present on spans in the aggregation group.

Returns names of attributes and their count. The count is the number of spans in the aggregation group where the attribute is present.

Return type: AttributeNames

attributes(): Attributes

List of attributes of the span. Return type: Attributes

attributes(attributeName: String): String

Value of individual attribute of the span.

Returns null if the span does not have an attribute of the given name.

Parameters:

  • attributeName - Name of attribute the value is retrieved for

Return type: String

count(): Long

Number of spans in the aggregation group.

If it is not combined with a dimension, count represents the total number of spans with respect to the FROM clause, the SINCE .. UNTIL time range and the potential filter on spans().

Return type: Long

Example:

Fetch distinct names of spans and the number of spans that share each name.

Code Snippet
CopyFETCH spans(){ name, count }

downstream(): Span

List of downstream-linked spans.

Downstream-linked spans are spans that are related to an aggregation group span and happened before it.

For each aggregation group, downstream-linked spans of all aggregation group spans are listed together.

If linked spans are needed for each span, add the spanId dimension. This effectively limits aggregation groups to individual spans, suppressing the aggregation effect:

Code Snippet
CopyFETCH spans()[traceId = 'trace1234']{ spanId, downstream() }

Note: spans() need to be filtered to fetch linked spans.

The filter can be provided to constrain the returned list of downstream-linked spans.

A list of span-related observations can be provided. If missing, a default set of observations is returned for the linked spans.

Note: upstream or downstream observations cannot be fetched for downstream-linked spans.

Return type: Span

Example:

Fetch spans of trace trace1234. Return only name and spanKind dimensions and a list of downstream-linked spans of all spans that share the name and spanKind values. Return only downstream-linked spans that have duration > 1 minute.

Code Snippet
CopyFETCH spans()[traceId = 'trace1234']
{  name,  spanKind,  downstream()[duration > 1m]{ traceId, spanId, name, duration, attributes }  }

duration(): Duration

Duration of the span.

Duration is returned in the ISO-8601 format. For example, PT1M3S for one minute and three seconds.

In a filter, the duration can be provided either in the ISO-8601 format or in the "Jira-like" format. For example, [ duration > PT10S && duration <= 1m ] for the duration between 10 seconds and 1 minute.

Return type: Duration

endedAt(): Timestamp

Timestamp when the span was finished.

endedAt is subject to timestamp formatting options (see OPTIONS clause).

Return type: Timestamp

entityIds(): List

List of IDs of the entity that reported the span.

The list contains the ID of the entity that reported the span and the IDs of the possible parent entities of the reporting entity.

When used in a filter, it is always filtered as an array of values.

For example, [ entityIds() >= 'spacefleet:bridge:h29BA24fOs22SPe1KgkU9g' ] (one value) is the same as [ entityIds() >= ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] (array with only one value)

Return type: List

Example:

Fetch the name and the list of entity IDs for spans that were reported by entity with the ID spacefleet:bridge:h29BA24fOs22SPe1KgkU9g or the ID spacefleet:room:23CiUf2FPGSn0ufu1awZvQ:

Code Snippet
CopyFETCH spans()[ entityIds() IN [ spacefleet:bridge:h29BA24fOs22SPe1KgkU9g, spacefleet:room:23CiUf2FPGSn0ufu1awZvQ] ] { name, entityIds() }

entityIds(entityType: EntityTypeId): List

List of IDs of entity that reported the span. The list contains ID of entity that reported the span and the IDs of possible parent entities of the reporting entity. The list contains only the IDs of the given entity type.

When used in the filter, it is always filtered as an array of values.

For example, [ entityIds(spacefleet:bridge) >= 'spacefleet:bridge:h29BA24fOs22SPe1KgkU9g' ] (one value) is the same as [ entityIds(spacefleet:bridge) >= ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] (array with only one value).

The possible IDs of different entity types are completely ignored and don't influence the array filter operators.

For example, [ entityIds(spacefleet:bridge) = ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] will pass for a span with entity IDs [ spacefleet:bridge:h29BA24fOs22SPe1KgkU9g, spacefleet:room:23CiUf2FPGSn0ufu1awZvQ ]

Parameters:

  • entityType - Entity type to filter entity IDs.

Return type: List

Example:

Fetch name and list of all spacefleet:bridge-type entity IDs for spans that were reported by entity with ID spacefleet:room:h29BA24fOs22SPe1KgkU9g, regardless of any IDs of other entity types:

Code Snippet
CopyFETCH spans()[ entityIds(spacefleet:room) = [ spacefleet:room:h29BA24fOs22SPe1KgkU9g ] ] { name, entityIds(spacefleet:bridge) }

errorMessage(): String

Error message of the span.

Return type: String

name(): String

Name of a span.

Return type: String

parentId(): String

ID of a parent span.

Root spans have no parent span and parentId is null for them.

Return type: String

source(): String

Source of a span as reported by the agent.

For example, common values are APM, opentelemetry, infra-agent, and unknown.

Return type: String

spanId(): String

ID of a span.

Return type: String

spanKind(): String

Kind of a span.

Common values are e.g. CLIENT, CONSUMER, INTERNAL, PRODUCER, SERVER or UNKNOWN.

Return type: String

startedAt(): Timestamp

Timestamp when a span is started.

startedAt is subject to timestamp formatting options. See OPTIONS clause.

Return type: Timestamp

statusCode(): String

Status code of the span.

For example, common values are OK, ERROR and UNSET.

Return type: String

tags(): Tags

List of tags of the span.

Return type: Tags

tags(tagName: String): Tag

Value of an individual tag of a span.

Returns null if the span does not have the tag of the given name.

Parameters:

  • tagName

Return type: Tag

traceId(): String

ID of a trace associated with a span.

Return type: String

upstream(): Span

List of upstream-linked spans.

The upstream-linked spans are spans that are related to an aggregation group span and happened after it.

For each aggregation group, upstream-linked spans of all aggregation group spans are listed together.

If linked spans are needed for each individual span, add spanId dimension. This effectively limits aggregation groups to individual spans, suppressing the aggregation effect:

Code Snippet
CopyFETCH spans()[traceId = 'trace1234']{ spanId, upstream() }

Note: spans() needs to be filtered to fetch linked spans.

Filter can be provided to constrain the returned list of upstream-linked spans.

A list of span-related observations can be provided. If missing, default set of observations is returned for the linked spans.

Note: The upstream or downstream observations cannot be fetched for upstream-linked spans.

Return type: Span

Example:

Fetch spans of trace trace1234. Return only name and spanKind dimensions and a list of upstream-linked spans of all spans that share the name and spanKind values. Return only upstream-linked spans that have duration > 1 minute.

Code Snippet
CopyFETCH spans()[traceId = 'trace1234']
{  name,  spanKind,  upstream()[duration > 1m]{ traceId, spanId, name, duration, attributes }  }

Tag

Represents the value of a single tag. The value of a tag is a list of strings. By default, this list is concatenated into a single string.

anyItem(): Any

Reduces the array of tag values into one of them. It is not specified which one of the values will be chosen as a representative.

Return type: Any

array(): Json

Returns the tag value as an array.

Return type: Json

concat(): String

Concatenates the array of tag values into a single string. This is the default behavior. Comma is used as the delimiter.

Return type: String

Example:

Suppose the name tag has the following value: ["bridge", "mess_hall", "sick_bay"].

Code Snippet
Copytags(room).concat()

The preceding query produces the output: "bridge,mess_hall,sick_bay"

concat(delimiter: String): String

Concatenates the array of tag values into a single string using a custom delimiter.

Parameters:

  • delimiter - string used in between values.

Return type: String

Example:

Suppose the name tag has the following value: ["bridge", "mess_hall", "sick_bay"].

Code Snippet
Copytags(room).concat("; ")

The preceding query produces the output: "bridge; mess_hall; sick_bay"

concat(delimiter: String, prefix: String, suffix: String): String

Concatenates the array of tag values into a single string using a custom delimiter, prefix and suffix.

Parameters:

  • delimiter - string used in between values.
  • prefix - string that will start with.
  • suffix - string that will end with.

Return type: String

Example:

Suppose the name tag has the following value: ["bridge", "mess_hall", "sick_bay"].

Code Snippet
Copytags(room).concat("; ", "( ", " )")

The preceding query produces the output: "( bridge; mess_hall; sick_bay )"

csv(): String

Produces a comma separated values string from the tag's value.

Return type: String

json(): Json

Produces a JSON array from the tag's value.

Return type: Json

Tags

Represents a table of all tags (name and value pairs).

name(): String

Retrieves the name of a tag.

Return type: String

value(): Any

Retrieves the value of a tag. Return type: Any

Trace

Represents the result of the traces function.

count(): Long

Number of traces in the aggregation group.

If it is not combined with a dimension, count represents the total number of traces with respect to FROM clause, SINCE .. UNTIL time range and a filter on traces().

Return type: Long

Example:

Fetch distinct names of traces and number of traces that share each name.

Code Snippet
CopyFETCH traces(){ name, count }

duration(): Duration

Duration of a trace.

Duration is returned in the ISO-8601 format. For example, PT1M3S for one minute and three seconds.

In filter, duration can be provided either in the ISO-8601 format or in the "Jira-like" format.

For example, [ duration > PT10S && duration <= 1m ] for the duration between 10 seconds and 1 minute.

Return type: Duration

Example:

Fetch the number of traces with reported duration between 10 seconds and 1 minute.

Code Snippet
CopyFETCH traces [duration > PT10S && duration <= 1m] { count }

entityIds(): List

List of IDs of entity that reported the trace.

The list contains ID of entity that reported the trace and the IDs of possible parent entities of the reporting entity.

When used in filter, it is always filtered as an array of values.

For example, [ entityIds() >= 'spacefleet:bridge:h29BA24fOs22SPe1KgkU9g' ] (one value) is the same as [ entityIds() >= ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] (array with only one value).

Return type: List

Example:

Fetch name and list of entity IDs for traces that were reported by entity with ID spacefleet:bridge:h29BA24fOs22SPe1KgkU9g or spacefleet:room:23CiUf2FPGSn0ufu1awZvQ:

Code Snippet
CopyFETCH traces()
    [ entityIds()
        IN [ spacefleet:bridge:h29BA24fOs22SPe1KgkU9g, spacefleet:room:23CiUf2FPGSn0ufu1awZvQ]
    ]
    { name, entityIds() }

entityIds(entityType: EntityTypeId): List

List of IDs of entity that reported the trace.

The list contains ID of entity that reported the trace and the IDs of possible parent entities of the reporting entity. The list contains only the IDs of the given entity type.

When used in filter, it is always filtered as an array of values.

For example, [ entityIds(spacefleet:bridge) >= 'spacefleet:bridge:h29BA24fOs22SPe1KgkU9g' ] (one value) is the same as [ entityIds(spacefleet:bridge) >= ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] (array with only one value).

The IDs of different entity types are completely ignored and don't influence the array filter operators.

For example, [ entityIds(spacefleet:bridge) = ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] will pass for a trace with entity IDs [ spacefleet:bridge:h29BA24fOs22SPe1KgkU9g, spacefleet:room:23CiUf2FPGSn0ufu1awZvQ ].

Parameters:

  • entityType - Entity type to filter entity IDs to

Return type: List;

Example:

Fetch name and list of all spacefleet:bridge-type entity IDs for traces that were reported by entity with ID spacefleet:room:h29BA24fOs22SPe1KgkU9g, regardless of any IDs of other entity types:

Code Snippet
CopyFETCH traces()
    [ entityIds(spacefleet:room) = [ spacefleet:room:h29BA24fOs22SPe1KgkU9g ] ]
    { name, entityIds(spacefleet:bridge) }

hasRoot(): Boolean

Checks if the root span reported for the trace.

Return type: Boolean

name(): String

Name of a trace.

Return type: String

numErrors(): Long

Number of span errors of a trace.

For example, number of spans that have statusCode = ERROR.

Return type: Long

Example:

Fetch the duration, number of errors, and name for each trace that were reported with a duration higher than one second.

Code Snippet
CopyFETCH traces
    [numErrors > 0 && duration > PT1s]
    {duration, numErrors, name}

numSpans(): Long

Number of spans of a trace.

Return type: Long

Example:

Fetch the number of traces that have a duration higher than three seconds with a number of spans higher than 10.

Code Snippet
CopyFETCH traces
    [numSpans > 10 && duration > PT3s]
    {count}

originEntityIds(): List

List of IDs of entity from where the trace was originated.

The list contains ID of entity from where the trace was originated and the IDs of possible parent entities of the originating entity.

When used in a filter, it is always filtered as an array of values.

For example, [ originEntityIds() >= 'spacefleet:bridge:h29BA24fOs22SPe1KgkU9g' ] (one value) is the same as [ originEntityIds() >= ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] (array with only one value).

The IDs of different entity types are completely ignored and don't influence the array filter operators.

For example, [ originEntityIds() = ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] will pass for a trace with origin entity IDs [ spacefleet:bridge:h29BA24fOs22SPe1KgkU9g, spacefleet:room:23CiUf2FPGSn0ufu1awZvQ ]

Return type: List

Example:

Fetch name and list of all spacefleet:bridge-type origin entity IDs for traces that were originated by entity with ID spacefleet:room:h29BA24fOs22SPe1KgkU9g, regardless of any IDs of other entity types:

Code Snippet
CopyFETCH traces()
    [ originEntityIds() = [ spacefleet:room:h29BA24fOs22SPe1KgkU9g ] ]
    { name, originEntityIds() }

originEntityIds(entityType: EntityTypeId): List

List of IDs of entity from where the trace was originated and limited to IDs of the given entity type.

The list contains ID of entity from where the trace was originated and the IDs of possible parent entities of the originating entity. The list contains only IDs of the given entity type.

When used in a filter, it is always filtered as an array of values.

For example, [ originEntityIds(spacefleet:bridge) >= 'spacefleet:bridge:h29BA24fOs22SPe1KgkU9g' ] (one value) is the same as [ originEntityIds(spacefleet:bridge) >= ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] (array with only one value).

The IDs of different entity types are completely ignored and don't influence the array filter operators.

For example, [ originEntityIds(spacefleet:bridge) = ['spacefleet:bridge:h29BA24fOs22SPe1KgkU9g'] ] will pass for a trace with origin entity IDs [ spacefleet:bridge:h29BA24fOs22SPe1KgkU9g, spacefleet:room:23CiUf2FPGSn0ufu1awZvQ ].

Parameters:

  • entityType - Entity type to filter entity IDs.

Return type: List

Example:

Fetch name and list of all spacefleet:bridge-type origin entity IDs for traces that were originated by entity with ID spacefleet:room:h29BA24fOs22SPe1KgkU9g, regardless of any IDs of other entity types:

Code Snippet
CopyFETCH traces()
    [ originEntityIds(spacefleet:room) = [ spacefleet:room:h29BA24fOs22SPe1KgkU9g ] ]
    { name, originEntityIds(spacefleet:bridge) }

source(): String

Source of a trace as reported by the agent.

For example, the common values are APM, opentelemetry, infra-agent, and unknown.

Return type: String

Example:

Fetch the number of traces slicing by its source where the source contains the sequence of characters 'open' somewhere.

Code Snippet
CopyFETCH traces [source ~ '*open*'] { count, source }

startedAt(): Timestamp

Timestamp when the trace is started.

startedAt is subject to timestamp formatting options. See OPTIONS clause. Traces don't provide an endedAt timestamp because they effectively end with their last span and it is not known whether some span is still running or not.

Return type: Timestamp

Example:

Fetch the number of traces that were initiated in the time range between '2024-02-15' and '2024-02-16' sliced by its source while having a duration higher than one minute.

Code Snippet
CopyFETCH traces()
  [startedAt >= '2024-02-15' && startedAt <= '2024-02-16' && duration > PT1m]
  {count, source}
FROM entities(spacefleet:warp_drive)

traceId(): String

ID of the trace.

Return type: String

Next