Operations & Functions Reference

Complete reference for all transformation operation types and built-in functions. See Introduction for an overview, scope rules, and common recipes.

Operations

Rename attribute

yaml

name: Rename service to service_name
scope: [spans, logs, events]
type: rename_attr
old_key: service
new_key: service_name

Set overwrite: true to overwrite the target attribute if it already exists:

yaml

name: Rename service to service_name
scope: [spans, logs, events]
type: rename_attr
old_key: service
new_key: service_name
overwrite: true

Delete attributes

By key list:

yaml

name: Delete foo and bar
scope: [spans, logs, events, datapoints]
type: delete_attrs
keys:
  - foo
  - bar

By regular expression:

yaml

name: Delete foo and bar
scope: [spans, logs, events, datapoints]
type: delete_attrs
regexp: ^(foo|bar)$

Scoped to a specific metric:

yaml

name: Delete foo and bar from my_metric
scope: [datapoints]
type: delete_attrs
keys:
  - foo
  - bar
if: metricName() == "my_metric_name"

Keep attributes

yaml

name: Keep foo and bar
scope: [spans, logs, events, datapoints]
type: keep_attrs
keys:
  - foo
  - bar

By regular expression:

yaml

name: Keep foo and bar
scope: [spans, logs, events, datapoints]
type: keep_attrs
regexp: ^(foo|bar)$

Drop

yaml

name: Drop hello logs
scope: [logs]
type: drop
if: attr("log_message") contains "hello"

yaml

name: Drop Redis evalsha
scope: [spans]
type: drop
if: spanName() == "evalsha" && spanStatusCode() != "error"

The if condition is required for drop. Execution stops for the matching record — subsequent operations are skipped.

Sample

yaml

name: Sample 50% hello logs
scope: [logs]
type: sample
fraction: 0.5
if: attr("log_message") startsWith "hello"

fraction must be between 0 and 1. For spans, sampling is trace-aware: all spans in a trace are kept or dropped together. The if condition is optional — omitting it applies sampling to all records in scope.

Change attribute type

yaml

name: Convert elapsed_ms to float
scope: [spans]
type: change_attr_type
key: elapsed_ms
type: float

Supported types: string, int, float, bool.

change_attr_type is not supported for datapoints. Use the script operation with type parsing functions instead.

Flatten map

By default, Uptrace does not index attributes that contain nested maps. The flatten_map operation extracts dot-separated paths from a map attribute so they can be queried:

yaml

name: Flatten the object attribute
scope: [spans]
type: flatten_map
maps: ['object']
include_paths: ['object.nested.foo']
include_regexp: '^object.nested\.'
exclude_paths: ['object.nested.hello']
exclude_regexp: 'secret'

Without include_paths or include_regexp, the entire map is indexed up to 32 paths.

IP geo attributes

Enriches IP address attributes with GeoIP data. For each specified key, Uptrace adds {key}_country_code, {key}_country_name, and {key}_city:

yaml

name: Enrich custom IP with geo data
scope: [spans, logs, events]
type: ip_geo_attrs
keys:
  - custom_ip_address

client_address and client_socket_address are automatically processed by Uptrace and should not be added manually.

ip_geo_attrs is not supported for datapoints.

Text index

Builds a full-text index column from selected attribute values, enabling *:value search syntax:

yaml

name: Index request attributes
scope: [spans, logs, events]
type: text_index
include:
  - log_message
  - exception_message
  - http.request.**
exclude:
  - http.request.headers.**

The include field accepts glob patterns:

Pattern	Description
`foo`	Indexes the `foo` attribute directly
`foo.**`	Indexes all nested keys in the `foo` map
`foo.*`	Indexes one level of nested keys
`foo?.bar`	Matches `foo1`, `foo2`, etc.

Search is case-insensitive and token-based (no substring matching). Maximum indexed text per record: 4096 bytes.

Text Index is billed separately based on indexed bytes. See the pricing page for details.

Script

Write arbitrary expressions to modify telemetry. The if condition is required.

Set error status when exception attributes are present:

yaml

name: Set error status when exception attributes are present
scope: [spans]
type: script
if: hasAttr("exception_type") && hasAttr("exception_message")
then:
  - setSpanStatusCode("error")
  - setSpanStatusMessage(attr("exception_message"))
else:
  - setSpanStatusCode("ok")

Parse a string attribute as float:

yaml

name: Parse elapsed_ms
scope: [spans]
type: script
if: hasAttr("elapsed_ms")
then:
  - setAttr("elapsed_ms", parseFloat(attr("elapsed_ms")))

Reduce attribute cardinality:

yaml

name: Normalize http_target
scope: [spans]
type: script
if: metricName() startsWith "http_server_" && hasAttr("http_target")
then:
  - setAttr("http_target", replaceGlob(attr("http_target"), "/user/*/list/*", "/user/{userId}/list/{listId}"))

Replace all numbers using a regular expression:

yaml

name: Replace numbers in foo
scope: [spans]
type: script
if: hasAttr("foo")
then:
  - setAttr("foo", replaceAllRegexp(attr("foo"), "(\\d+)", "<number>"))

Convert a log into a span:

yaml

name: Convert logs with elapsed_ms to spans
scope: [logs]
type: script
if: hasAttr("elapsed_ms")
then:
  - setSpanName("operation-name")
  - setLogName("")
  - setSpanDuration(parseFloat(attr("elapsed_ms")) * 1e6)
  - setSpanStatusCode("ok")

Function	Scope	Description
`spanName()`	spans, logs, events	Returns the span name or an empty string.
`eventName()`	events	Returns the event name or an empty string.
`logName()`	logs	Returns the log name (alias for `eventName`).
`spanKind()`	spans	Returns the span kind (`internal`, `server`, `client`, `producer`, `consumer`).
`spanDuration()`	spans	Returns the span duration as a `time.Duration` (nanosecond precision).
`spanStatusCode()`	spans, logs, events	Returns the span status code (`unset`, `ok`, `error`).
`spanStatusMessage()`	spans, logs, events	Returns the span status message.

Setters

Function	Scope	Description
`setSpanName(string)`	spans	Sets the span name.
`setEventName(string)`	events	Sets the event name.
`setLogName(string)`	logs	Sets the log name.
`setSpanKind(string)`	spans	Sets the span kind. Must be one of: `internal`, `server`, `client`, `producer`, `consumer`.
`setSpanDuration(nanoseconds)`	spans	Sets the span duration in nanoseconds. Accepts `int`, `int64`, or `time.Duration`.
`setSpanStatusCode(string)`	spans	Sets the span status code (`unset`, `ok`, `error`).
`setSpanStatusMessage(string)`	spans	Sets the span status message.

Attribute functions

Function	Scope	Description
`attr(key)`	spans, logs, events	Returns the attribute value by key.
`attrType(key)`	spans, logs, events	Returns the type: `nil`, `string`, `int`, `float`, `bool`, `array`, or `map`.
`hasAttr(key)`	spans, logs, events	Returns `true` if the attribute exists.
`setAttr(key, value)`	spans, logs, events	Sets the attribute value.
`deleteAttr(key)`	spans, logs, events	Deletes the attribute.
`renameAttr(oldKey, newKey)`	spans, logs, events	Renames the attribute.
`renameAttr(oldKey, newKey, overwrite)`	spans, logs, events	Renames the attribute, optionally overwriting if the target exists.

Type parsing functions

Function	Scope	Description
`parseInt(value)`	spans, logs, events	Parses the value as `int64`.
`parseUint(value)`	spans, logs, events	Parses the value as `uint64`.
`parseFloat(value)`	spans, logs, events	Parses the value as `float64`.
`parseBool(value)`	spans, logs, events	Parses as `bool`. Accepts `"true"`, `"false"`, `"1"`, `"0"`.

Datapoint functions

Getters

Function	Description
`metricName()`	Returns the metric name.
`metricUnit()`	Returns the metric unit.
`metricInstrument()`	Returns the metric instrument type.
`libraryName()`	Returns the instrumentation library name.
`libraryVersion()`	Returns the instrumentation library version.

Setters

Function	Description
`setMetricName(string)`	Sets the metric name.
`setMetricUnit(string)`	Sets the metric unit.
`setMetricInstrument(string)`	Sets the metric instrument type.

Attribute functions

Function	Description
`attr(key)`	Returns the attribute value as a string.
`hasAttr(key)`	Returns `true` if the attribute exists.
`setAttr(key, value)`	Sets the attribute value.
`deleteAttr(key)`	Deletes the attribute.
`renameAttr(oldKey, newKey)`	Renames the attribute.
`renameAttr(oldKey, newKey, overwrite)`	Renames the attribute, optionally overwriting.

Common functions

Function	Description
`replaceGlob(src, pattern, repl)`	Returns `repl` if `src` matches glob `pattern`, otherwise returns `src`.
`replaceAllRegexp(src, pattern, repl)`	Replaces all regexp matches in `src` with `repl`.
`extractAllRegexp(src, pattern, repl)`	Extracts and transforms all regexp matches from `src` using `repl` template.
`parseDuration(string)`	Parses a duration string (e.g. `"1h30m"`, `"500ms"`) as `time.Duration`.
`parseByteSize(string)`	Parses a byte size string (e.g. `"1GB"`, `"512MB"`) as `int64` bytes.

Expr language definition
Introduction — overview, scope rules, and common recipes

Operations & Functions Reference

Operations

Rename attribute

Delete attributes

Keep attributes

Drop

Sample

Change attribute type

Flatten map

IP geo attributes

Text index

Script

Functions reference

Span, log, and event functions

Getters

Setters

Attribute functions

Type parsing functions

Datapoint functions

Getters

Setters

Attribute functions

Common functions