otel-ottl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTelemetry Transformation Language (OTTL)

OpenTelemetry转换语言（OTTL）

Use OTTL to transform, filter, and manipulate telemetry data inside the OpenTelemetry Collector — without changing application code.

使用OTTL在OpenTelemetry Collector内部转换、过滤和操作遥测数据——无需修改应用代码。

Components that use OTTL

支持OTTL的组件

OTTL is not limited to the transform and filter processors. The following Collector components accept OTTL expressions in their configuration.

OTTL不仅限于transform和filter处理器。以下Collector组件的配置中可使用OTTL表达式。

Processors

处理器

Component	Use case
transform	Modify, enrich, or redact telemetry (set attributes, rename fields, truncate values)
filter	Drop telemetry entirely (discard metrics by name, drop spans by status, remove noisy logs)
attributes	Insert, update, delete, or hash resource and record attributes
span	Rename spans and set span status based on attribute values
tailsampling	Sample traces based on OTTL conditions (e.g., keep error traces, drop health checks)
cumulativetodelta	Convert cumulative metrics to delta temporality with OTTL-based metric selection
logdedup	Deduplicate log records using OTTL conditions
lookup	Enrich telemetry by looking up values from external tables using OTTL expressions

组件	使用场景
transform	修改、丰富或脱敏遥测数据（设置属性、重命名字段、截断值）
filter	完全丢弃遥测数据（按名称丢弃指标、按状态丢弃span、移除冗余日志）
attributes	插入、更新、删除或哈希资源与记录属性
span	重命名span并根据属性值设置span状态
tailsampling	基于OTTL条件采样追踪（例如保留错误追踪、丢弃健康检查数据）
cumulativetodelta	基于OTTL的指标选择将累积指标转换为增量时间序列
logdedup	使用OTTL条件对日志记录进行去重
lookup	使用OTTL表达式从外部表查询值来丰富遥测数据

Connectors

连接器

Component	Use case
routing	Route telemetry to different pipelines based on OTTL conditions
count	Count spans, metrics, or logs matching OTTL conditions and emit as metrics
sum	Sum numeric values from telemetry matching OTTL conditions and emit as metrics
signaltometrics	Generate metrics from spans or logs using OTTL expressions for attribute extraction

组件	使用场景
routing	基于OTTL条件将遥测数据路由到不同管道
count	统计匹配OTTL条件的span、指标或日志数量并作为指标输出
sum	对匹配OTTL条件的遥测数据中的数值求和并作为指标输出
signaltometrics	使用OTTL表达式提取属性，从span或日志生成指标

Receivers

接收器

Component	Use case
hostmetrics	Filter host metrics at collection time using OTTL conditions

组件	使用场景
hostmetrics	在采集阶段使用OTTL条件过滤主机指标

OTTL syntax

OTTL语法

Path expressions

路径表达式

Navigate telemetry data using dot notation:

span.name
span.attributes["http.method"]
resource.attributes["service.name"]

Contexts (first path segment) map to OpenTelemetry signal structures:

```
resource
```
- Resource-level attributes
```
scope
```
- Instrumentation scope
```
span
```
- Span data (traces)
```
spanevent
```
- Span events
```
metric
```
- Metric metadata
```
datapoint
```
- Metric data points
```
log
```
- Log records

使用点符号导航遥测数据：

span.name
span.attributes["http.method"]
resource.attributes["service.name"]

上下文（路径的第一个段）对应OpenTelemetry信号结构：

```
resource
```
- 资源级属性
```
scope
```
- 仪器范围
```
span
```
- Span数据（追踪）
```
spanevent
```
- Span事件
```
metric
```
- 元数据指标
```
datapoint
```
- 指标数据点
```
log
```
- 日志记录

Enumerations

枚举

Several fields accept int64 values exposed as global constants:

span.status.code == STATUS_CODE_ERROR
span.kind == SPAN_KIND_SERVER

多个字段接受作为全局常量暴露的int64值：

span.status.code == STATUS_CODE_ERROR
span.kind == SPAN_KIND_SERVER

Operators

运算符

Category	Operators
Assignment	`=`
Comparison	`==` , `!=` , `>` , `<` , `>=` , `<=`
Logical	`and` , `or` , `not`

类别	运算符
赋值	`=`
比较	`==` , `!=` , `>` , `<` , `>=` , `<=`
逻辑	`and` , `or` , `not`

Functions

函数

Converters (uppercase, pure functions that return values):

ToUpperCase(span.attributes["http.request.method"])
Substring(log.body.string, 0, 1024)
Concat(["prefix", span.attributes["request.id"]], "-")
IsMatch(metric.name, "^k8s\\..*$")

Editors (lowercase, functions with side-effects that modify data):

set(span.attributes["region"], "us-east-1")
delete_key(resource.attributes, "internal.key")
limit(log.attributes, 10, [])

转换器（大写，返回值的纯函数）：

ToUpperCase(span.attributes["http.request.method"])
Substring(log.body.string, 0, 1024)
Concat(["prefix", span.attributes["request.id"]], "-")
IsMatch(metric.name, "^k8s\\..*$")

编辑器（小写，有副作用的修改数据函数）：

set(span.attributes["region"], "us-east-1")
delete_key(resource.attributes, "internal.key")
limit(log.attributes, 10, [])

Conditional statements

条件语句

The

where

clause applies transformations conditionally:

span.attributes["db.statement"] = "REDACTED" where resource.attributes["service.name"] == "accounting"

where

子句可条件性地应用转换：

span.attributes["db.statement"] = "REDACTED" where resource.attributes["service.name"] == "accounting"

Nil checks

空值检查

OTTL uses

nil

for absence checking (not

null

resource.attributes["service.name"] != nil

OTTL使用

nil

进行存在性检查（而非

null

）：

resource.attributes["service.name"] != nil

Common patterns

常见模式

Set attributes

设置属性

set(resource.attributes["k8s.cluster.name"], "prod-aws-us-west-2")

set(resource.attributes["k8s.cluster.name"], "prod-aws-us-west-2")

Redact sensitive data

脱敏敏感数据

set(span.attributes["http.request.header.authorization"], "REDACTED") where span.attributes["http.request.header.authorization"] != nil

set(span.attributes["http.request.header.authorization"], "REDACTED") where span.attributes["http.request.header.authorization"] != nil

Drop telemetry by pattern

按模式丢弃遥测数据

In a filter processor, matching expressions cause data to be dropped:

IsMatch(metric.name, "^k8s\\.replicaset\\..*$")

在filter处理器中，匹配表达式会导致数据被丢弃：

IsMatch(metric.name, "^k8s\\.replicaset\\..*$")

Drop stale data

丢弃过期数据

time_unix_nano < UnixNano(Now()) - 21600000000000

time_unix_nano < UnixNano(Now()) - 21600000000000

Backfill missing timestamps

回填缺失的时间戳

yaml

processors:
  transform:
    log_statements:
      - context: log
        statements:
          - set(log.observed_time, Now()) where log.observed_time_unix_nano == 0
          - set(log.time, log.observed_time) where log.time_unix_nano == 0

yaml

processors:
  transform:
    log_statements:
      - context: log
        statements:
          - set(log.observed_time, Now()) where log.observed_time_unix_nano == 0
          - set(log.time, log.observed_time) where log.time_unix_nano == 0

Filter processor example

Filter处理器示例

yaml

processors:
  filter:
    metrics:
      datapoint:
        - 'IsMatch(ConvertCase(String(metric.name), "lower"), "^k8s\\.replicaset\\.")'

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [filter, batch]
      exporters: [debug]

yaml

processors:
  filter:
    metrics:
      datapoint:
        - 'IsMatch(ConvertCase(String(metric.name), "lower"), "^k8s\\.replicaset\\.")'

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [filter, batch]
      exporters: [debug]

Transform processor example

Transform处理器示例

yaml

processors:
  transform:
    trace_statements:
      - context: span
        statements:
          - set(span.status.code, STATUS_CODE_ERROR) where span.attributes["http.response.status_code"] >= 500
          - set(span.attributes["env"], "production") where resource.attributes["deployment.environment"] == "prod"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform, batch]
      exporters: [debug]

yaml

processors:
  transform:
    trace_statements:
      - context: span
        statements:
          - set(span.status.code, STATUS_CODE_ERROR) where span.attributes["http.response.status_code"] >= 500
          - set(span.attributes["env"], "production") where resource.attributes["deployment.environment"] == "prod"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform, batch]
      exporters: [debug]

Defensive nil checks

防御性空值检查

Always check for

nil

before operating on optional attributes:

resource.attributes["service.namespace"] != nil
and
IsMatch(ConvertCase(String(resource.attributes["service.namespace"]), "lower"), "^platform.*$")

在操作可选属性前始终检查

nil

：

resource.attributes["service.namespace"] != nil
and
IsMatch(ConvertCase(String(resource.attributes["service.namespace"]), "lower"), "^platform.*$")

Error handling

错误处理

Compilation errors

编译错误

Occur during processor initialization and prevent Collector startup:

Invalid syntax (missing quotes)
Unknown functions
Invalid path expressions
Type mismatches

发生在处理器初始化阶段，会阻止Collector启动：

无效语法（缺少引号）
未知函数
无效路径表达式
类型不匹配

Runtime errors

运行时错误

Occur during telemetry processing:

Accessing non-existent attributes
Type conversion failures
Function execution errors

发生在遥测数据处理阶段：

访问不存在的属性
类型转换失败
函数执行错误

Error mode configuration

错误模式配置

Always set

error_mode

explicitly. The default (

propagate

) stops processing the current item on any error, which can silently drop telemetry in production.

Mode	Behavior	When to use
`propagate` (default)	Stops processing current item	Development and strict environments where you want to catch every error
`ignore`	Logs error, continues processing	Production — set this unless you have a specific reason not to
`silent`	Ignores errors without logging	High-volume pipelines with known-safe transforms where error logs are noise

yaml

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(span.attributes["parsed"], ParseJSON(span.attributes["json_body"]))

始终显式设置

error_mode

。默认值（

propagate

）会在发生任何错误时停止处理当前条目，这可能会在生产环境中静默丢弃遥测数据。

模式	行为	使用场景
`propagate` （默认）	停止处理当前条目	开发环境和需要捕获所有错误的严格环境
`ignore`	记录错误，继续处理	生产环境——除非有特定原因，否则设置此模式
`silent`	忽略错误且不记录	高流量管道且转换已知安全，错误日志会产生噪音的场景

yaml

processors:
  transform:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(span.attributes["parsed"], ParseJSON(span.attributes["json_body"]))

Performance

性能

OTTL statements compile once at startup and execute as optimized function chains at runtime. There is no need to optimize for compilation speed — focus on reducing the number of statements that evaluate per telemetry item. Use

where

clauses to skip items early rather than applying unconditional transforms.

OTTL语句在启动时编译一次，运行时作为优化的函数链执行。无需优化编译速度——重点减少每个遥测条目需要评估的语句数量。使用

where

子句提前跳过条目，而非应用无条件转换。

Function reference

函数参考

Editors

编辑器

Editors modify telemetry data in-place. They are lowercase.

Function	Signature	Description
`append`	`append(target, Optional[value], Optional[values])`	Appends single or multiple values to a target field, converting scalars to arrays if needed
`delete_key`	`delete_key(target, key)`	Removes a key from a map
`delete_matching_keys`	`delete_matching_keys(target, pattern)`	Removes all keys matching a regex pattern
`flatten`	`flatten(target, Optional[prefix], Optional[depth])`	Flattens nested maps to the root level
`keep_keys`	`keep_keys(target, keys[])`	Removes all keys NOT in the supplied list
`keep_matching_keys`	`keep_matching_keys(target, pattern)`	Keeps only keys matching a regex pattern
`limit`	`limit(target, limit, priority_keys[])`	Reduces map size to not exceed limit, preserving priority keys
`merge_maps`	`merge_maps(target, source, strategy)`	Merges source into target (strategy: `insert` , `update` , `upsert` )
`replace_all_matches`	`replace_all_matches(target, pattern, replacement)`	Replaces matching string values using glob patterns
`replace_all_patterns`	`replace_all_patterns(target, mode, regex, replacement)`	Replaces segments matching regex (mode: `key` or `value` )
`replace_match`	`replace_match(target, pattern, replacement)`	Replaces entire string if it matches a glob pattern
`replace_pattern`	`replace_pattern(target, regex, replacement)`	Replaces string sections matching a regex
`set`	`set(target, value)`	Sets a telemetry field to a value
`truncate_all`	`truncate_all(target, limit)`	Truncates all string values in a map to a max length

编辑器会就地修改遥测数据，采用小写命名。

函数	签名	描述
`append`	`append(target, Optional[value], Optional[values])`	向目标字段追加单个或多个值，必要时将标量转换为数组
`delete_key`	`delete_key(target, key)`	从映射中移除指定键
`delete_matching_keys`	`delete_matching_keys(target, pattern)`	移除所有匹配正则模式的键
`flatten`	`flatten(target, Optional[prefix], Optional[depth])`	将嵌套映射展平到根级别
`keep_keys`	`keep_keys(target, keys[])`	移除所有不在提供列表中的键
`keep_matching_keys`	`keep_matching_keys(target, pattern)`	仅保留匹配正则模式的键
`limit`	`limit(target, limit, priority_keys[])`	将映射大小减少到不超过限制，保留优先级键
`merge_maps`	`merge_maps(target, source, strategy)`	将源映射合并到目标映射（策略： `insert` 、 `update` 、 `upsert` ）
`replace_all_matches`	`replace_all_matches(target, pattern, replacement)`	使用通配符模式替换匹配的字符串值
`replace_all_patterns`	`replace_all_patterns(target, mode, regex, replacement)`	替换匹配正则的片段（模式： `key` 或 `value` ）
`replace_match`	`replace_match(target, pattern, replacement)`	如果字符串完全匹配通配符模式则替换整个字符串
`replace_pattern`	`replace_pattern(target, regex, replacement)`	替换匹配正则的字符串部分
`set`	`set(target, value)`	将遥测字段设置为指定值
`truncate_all`	`truncate_all(target, limit)`	将映射中的所有字符串值截断到最大长度

Converters: type checking

转换器：类型检查

Function	Signature	Description
`IsBool`	`IsBool(value)`	Returns true if value is boolean
`IsDouble`	`IsDouble(value)`	Returns true if value is float64
`IsInt`	`IsInt(value)`	Returns true if value is int64
`IsMap`	`IsMap(value)`	Returns true if value is a map
`IsList`	`IsList(value)`	Returns true if value is a list
`IsMatch`	`IsMatch(target, pattern)`	Returns true if target matches regex pattern
`IsRootSpan`	`IsRootSpan()`	Returns true if span has no parent
`IsString`	`IsString(value)`	Returns true if value is a string

函数	签名	描述
`IsBool`	`IsBool(value)`	如果值是布尔类型则返回true
`IsDouble`	`IsDouble(value)`	如果值是float64类型则返回true
`IsInt`	`IsInt(value)`	如果值是int64类型则返回true
`IsMap`	`IsMap(value)`	如果值是映射类型则返回true
`IsList`	`IsList(value)`	如果值是列表类型则返回true
`IsMatch`	`IsMatch(target, pattern)`	如果目标匹配正则模式则返回true
`IsRootSpan`	`IsRootSpan()`	如果span没有父级则返回true
`IsString`	`IsString(value)`	如果值是字符串类型则返回true

Converters: type conversion

转换器：类型转换

Function	Signature	Description
`Bool`	`Bool(value)`	Converts value to boolean
`Double`	`Double(value)`	Converts value to float64
`Int`	`Int(value)`	Converts value to int64
`String`	`String(value)`	Converts value to string

函数	签名	描述
`Bool`	`Bool(value)`	将值转换为布尔类型
`Double`	`Double(value)`	将值转换为float64类型
`Int`	`Int(value)`	将值转换为int64类型
`String`	`String(value)`	将值转换为字符串类型

Converters: string manipulation

转换器：字符串操作

Function	Signature	Description
`Concat`	`Concat(values[], delimiter)`	Concatenates values with a delimiter
`ConvertCase`	`ConvertCase(target, toCase)`	Converts to `lower` , `upper` , `snake` , or `camel`
`HasPrefix`	`HasPrefix(value, prefix)`	Returns true if value starts with prefix
`HasSuffix`	`HasSuffix(value, suffix)`	Returns true if value ends with suffix
`Index`	`Index(target, value)`	Returns first index of value in target, or -1
`Split`	`Split(target, delimiter)`	Splits string into array by delimiter
`Substring`	`Substring(target, start, length)`	Extracts substring from start position
`ToCamelCase`	`ToCamelCase(target)`	Converts to CamelCase
`ToLowerCase`	`ToLowerCase(target)`	Converts to lowercase
`ToSnakeCase`	`ToSnakeCase(target)`	Converts to snake_case
`ToUpperCase`	`ToUpperCase(target)`	Converts to UPPERCASE
`Trim`	`Trim(target, Optional[char])`	Removes leading/trailing characters
`TrimPrefix`	`TrimPrefix(value, prefix)`	Removes leading prefix
`TrimSuffix`	`TrimSuffix(value, suffix)`	Removes trailing suffix

函数	签名	描述
`Concat`	`Concat(values[], delimiter)`	使用分隔符连接多个值
`ConvertCase`	`ConvertCase(target, toCase)`	转换为 `lower` 、 `upper` 、 `snake` 或 `camel` 格式
`HasPrefix`	`HasPrefix(value, prefix)`	如果值以指定前缀开头则返回true
`HasSuffix`	`HasSuffix(value, suffix)`	如果值以指定后缀结尾则返回true
`Index`	`Index(target, value)`	返回值在目标中的第一个索引，不存在则返回-1
`Split`	`Split(target, delimiter)`	按分隔符将字符串拆分为数组
`Substring`	`Substring(target, start, length)`	从起始位置提取子字符串
`ToCamelCase`	`ToCamelCase(target)`	转换为驼峰式命名
`ToLowerCase`	`ToLowerCase(target)`	转换为小写
`ToSnakeCase`	`ToSnakeCase(target)`	转换为蛇形命名
`ToUpperCase`	`ToUpperCase(target)`	转换为大写
`Trim`	`Trim(target, Optional[char])`	移除首尾指定字符
`TrimPrefix`	`TrimPrefix(value, prefix)`	移除指定前缀
`TrimSuffix`	`TrimSuffix(value, suffix)`	移除指定后缀

Converters: Hashing

转换器：哈希

Function	Signature	Description
`FNV`	`FNV(value)`	Returns FNV hash as int64
`MD5`	`MD5(value)`	Returns MD5 hash as hex string
`Murmur3Hash`	`Murmur3Hash(target)`	Returns 32-bit Murmur3 hash as hex string
`Murmur3Hash128`	`Murmur3Hash128(target)`	Returns 128-bit Murmur3 hash as hex string
`SHA1`	`SHA1(value)`	Returns SHA1 hash as hex string
`SHA256`	`SHA256(value)`	Returns SHA256 hash as hex string
`SHA512`	`SHA512(value)`	Returns SHA512 hash as hex string

函数	签名	描述
`FNV`	`FNV(value)`	返回FNV哈希值（int64类型）
`MD5`	`MD5(value)`	返回MD5哈希值（十六进制字符串）
`Murmur3Hash`	`Murmur3Hash(target)`	返回32位Murmur3哈希值（十六进制字符串）
`Murmur3Hash128`	`Murmur3Hash128(target)`	返回128位Murmur3哈希值（十六进制字符串）
`SHA1`	`SHA1(value)`	返回SHA1哈希值（十六进制字符串）
`SHA256`	`SHA256(value)`	返回SHA256哈希值（十六进制字符串）
`SHA512`	`SHA512(value)`	返回SHA512哈希值（十六进制字符串）

Converters: encoding and decoding

转换器：编码与解码

Function	Signature	Description
`Decode`	`Decode(value, encoding)`	Decodes string (base64, base64-raw, base64-url, IANA encodings)
`Hex`	`Hex(value)`	Returns hexadecimal representation

函数	签名	描述
`Decode`	`Decode(value, encoding)`	解码字符串（支持base64、base64-raw、base64-url、IANA编码）
`Hex`	`Hex(value)`	返回十六进制表示

Converters: Parsing

转换器：解析

Function	Signature	Description
`ExtractPatterns`	`ExtractPatterns(target, pattern)`	Extracts named regex capture groups into a map
`ExtractGrokPatterns`	`ExtractGrokPatterns(target, pattern, Optional[namedOnly], Optional[defs])`	Parses unstructured data using grok patterns
`ParseCSV`	`ParseCSV(target, headers, Optional[delimiter], Optional[headerDelimiter], Optional[mode])`	Parses CSV string to map
`ParseInt`	`ParseInt(target, base)`	Parses string as integer in given base (2-36)
`ParseJSON`	`ParseJSON(target)`	Parses JSON string to map or slice
`ParseKeyValue`	`ParseKeyValue(target, Optional[delimiter], Optional[pair_delimiter])`	Parses key-value string to map
`ParseSeverity`	`ParseSeverity(target, severityMapping)`	Maps log level value to severity string
`ParseSimplifiedXML`	`ParseSimplifiedXML(target)`	Parses XML string to map (ignores attributes)
`ParseXML`	`ParseXML(target)`	Parses XML string to map (preserves structure)

函数	签名	描述
`ExtractPatterns`	`ExtractPatterns(target, pattern)`	将正则捕获组提取为映射
`ExtractGrokPatterns`	`ExtractGrokPatterns(target, pattern, Optional[namedOnly], Optional[defs])`	使用grok模式解析非结构化数据
`ParseCSV`	`ParseCSV(target, headers, Optional[delimiter], Optional[headerDelimiter], Optional[mode])`	将CSV字符串解析为映射
`ParseInt`	`ParseInt(target, base)`	将字符串解析为指定进制（2-36）的整数
`ParseJSON`	`ParseJSON(target)`	将JSON字符串解析为映射或切片
`ParseKeyValue`	`ParseKeyValue(target, Optional[delimiter], Optional[pair_delimiter])`	将键值对字符串解析为映射
`ParseSeverity`	`ParseSeverity(target, severityMapping)`	将日志级别值映射为严重程度字符串
`ParseSimplifiedXML`	`ParseSimplifiedXML(target)`	将XML字符串解析为映射（忽略属性）
`ParseXML`	`ParseXML(target)`	将XML字符串解析为映射（保留结构）

Converters: Time and Date

转换器：时间与日期

Function	Signature	Description
`Day`	`Day(value)`	Returns day component from time
`Duration`	`Duration(duration)`	Parses duration string (e.g. `"3s"` , `"333ms"` )
`FormatTime`	`FormatTime(time, format)`	Formats time to string using Go layout
`Hour`	`Hour(value)`	Returns hour component from time
`Hours`	`Hours(value)`	Returns duration as floating-point hours
`Minute`	`Minute(value)`	Returns minute component from time
`Minutes`	`Minutes(value)`	Returns duration as floating-point minutes
`Month`	`Month(value)`	Returns month component from time
`Nanosecond`	`Nanosecond(value)`	Returns nanosecond component from time
`Nanoseconds`	`Nanoseconds(value)`	Returns duration as nanosecond count
`Now`	`Now()`	Returns current time
`Second`	`Second(value)`	Returns second component from time
`Seconds`	`Seconds(value)`	Returns duration as floating-point seconds
`Time`	`Time(target, format, Optional[location], Optional[locale])`	Parses string to time
`TruncateTime`	`TruncateTime(time, duration)`	Truncates time to multiple of duration
`Unix`	`Unix(seconds, Optional[nanoseconds])`	Creates time from Unix epoch
`UnixMicro`	`UnixMicro(value)`	Returns time as microseconds since epoch
`UnixMilli`	`UnixMilli(value)`	Returns time as milliseconds since epoch
`UnixNano`	`UnixNano(value)`	Returns time as nanoseconds since epoch
`UnixSeconds`	`UnixSeconds(value)`	Returns time as seconds since epoch
`Weekday`	`Weekday(value)`	Returns day of week from time
`Year`	`Year(value)`	Returns year component from time

函数	签名	描述
`Day`	`Day(value)`	从时间中提取日分量
`Duration`	`Duration(duration)`	解析时长字符串（例如 `"3s"` 、 `"333ms"` ）
`FormatTime`	`FormatTime(time, format)`	使用Go语言布局将时间格式化为字符串
`Hour`	`Hour(value)`	从时间中提取小时分量
`Hours`	`Hours(value)`	将时长转换为浮点型小时数
`Minute`	`Minute(value)`	从时间中提取分钟分量
`Minutes`	`Minutes(value)`	将时长转换为浮点型分钟数
`Month`	`Month(value)`	从时间中提取月份分量
`Nanosecond`	`Nanosecond(value)`	从时间中提取纳秒分量
`Nanoseconds`	`Nanoseconds(value)`	将时长转换为纳秒数
`Now`	`Now()`	返回当前时间
`Second`	`Second(value)`	从时间中提取秒分量
`Seconds`	`Seconds(value)`	将时长转换为浮点型秒数
`Time`	`Time(target, format, Optional[location], Optional[locale])`	将字符串解析为时间
`TruncateTime`	`TruncateTime(time, duration)`	将时间截断为指定时长的倍数
`Unix`	`Unix(seconds, Optional[nanoseconds])`	从Unix纪元创建时间
`UnixMicro`	`UnixMicro(value)`	返回自纪元以来的微秒数
`UnixMilli`	`UnixMilli(value)`	返回自纪元以来的毫秒数
`UnixNano`	`UnixNano(value)`	返回自纪元以来的纳秒数
`UnixSeconds`	`UnixSeconds(value)`	返回自纪元以来的秒数
`Weekday`	`Weekday(value)`	从时间中提取星期几
`Year`	`Year(value)`	从时间中提取年份分量

Converters: Collections

转换器：集合

Function	Signature	Description
`ContainsValue`	`ContainsValue(target, item)`	Returns true if item exists in slice
`Format`	`Format(formatString, args[])`	Formats string using `fmt.Sprintf` syntax
`Keys`	`Keys(target)`	Returns all keys from a map
`Len`	`Len(target)`	Returns length of string, slice, or map
`SliceToMap`	`SliceToMap(target, Optional[keyPath], Optional[valuePath])`	Converts slice of objects to map
`Sort`	`Sort(target, Optional[order])`	Sorts array ( `asc` or `desc` )
`ToKeyValueString`	`ToKeyValueString(target, Optional[delim], Optional[pairDelim], Optional[sort])`	Converts map to key-value string
`Values`	`Values(target)`	Returns all values from a map

函数	签名	描述
`ContainsValue`	`ContainsValue(target, item)`	如果切片中存在指定项则返回true
`Format`	`Format(formatString, args[])`	使用 `fmt.Sprintf` 语法格式化字符串
`Keys`	`Keys(target)`	返回映射中的所有键
`Len`	`Len(target)`	返回字符串、切片或映射的长度
`SliceToMap`	`SliceToMap(target, Optional[keyPath], Optional[valuePath])`	将对象切片转换为映射
`Sort`	`Sort(target, Optional[order])`	对数组进行排序（ `asc` 或 `desc` ）
`ToKeyValueString`	`ToKeyValueString(target, Optional[delim], Optional[pairDelim], Optional[sort])`	将映射转换为键值对字符串
`Values`	`Values(target)`	返回映射中的所有值

Converters: IDs and Encoding

转换器：ID与编码

Function	Signature	Description
`ProfileID`	`ProfileID(bytes\|string)`	Creates ProfileID from 16 bytes or 32 hex chars
`SpanID`	`SpanID(bytes\|string)`	Creates SpanID from 8 bytes or 16 hex chars
`TraceID`	`TraceID(bytes\|string)`	Creates TraceID from 16 bytes or 32 hex chars
`UUID`	`UUID()`	Generates a new UUID
`UUIDv7`	`UUIDv7()`	Generates a new UUIDv7

函数	签名	描述
`ProfileID`	`ProfileID(bytes\|string)`	从16字节或32位十六进制字符创建ProfileID
`SpanID`	`SpanID(bytes\|string)`	从8字节或16位十六进制字符创建SpanID
`TraceID`	`TraceID(bytes\|string)`	从16字节或32位十六进制字符创建TraceID
`UUID`	`UUID()`	生成新的UUID
`UUIDv7`	`UUIDv7()`	生成新的UUIDv7

Converters: XML

转换器：XML

Function	Signature	Description
`ConvertAttributesToElementsXML`	`ConvertAttributesToElementsXML(target, Optional[xpath])`	Converts XML attributes to child elements
`ConvertTextToElementsXML`	`ConvertTextToElementsXML(target, Optional[xpath], Optional[name])`	Wraps XML text content in elements
`GetXML`	`GetXML(target, xpath)`	Returns XML elements matching XPath
`InsertXML`	`InsertXML(target, xpath, value)`	Inserts XML at XPath locations
`RemoveXML`	`RemoveXML(target, xpath)`	Removes XML elements matching XPath

函数	签名	描述
`ConvertAttributesToElementsXML`	`ConvertAttributesToElementsXML(target, Optional[xpath])`	将XML属性转换为子元素
`ConvertTextToElementsXML`	`ConvertTextToElementsXML(target, Optional[xpath], Optional[name])`	将XML文本内容包装为元素
`GetXML`	`GetXML(target, xpath)`	返回匹配XPath的XML元素
`InsertXML`	`InsertXML(target, xpath, value)`	在XPath指定位置插入XML
`RemoveXML`	`RemoveXML(target, xpath)`	移除匹配XPath的XML元素

Converters: Miscellaneous

转换器：其他

Function	Signature	Description
`CommunityID`	`CommunityID(srcIP, srcPort, dstIP, dstPort, Optional[proto], Optional[seed])`	Generates network flow hash
`IsValidLuhn`	`IsValidLuhn(value)`	Returns true if value passes Luhn check
`Log`	`Log(value)`	Returns natural logarithm as float64
`URL`	`URL(url_string)`	Parses URL into components (scheme, host, path, etc.)
`UserAgent`	`UserAgent(value)`	Parses user-agent string into map (name, version, OS)

函数	签名	描述
`CommunityID`	`CommunityID(srcIP, srcPort, dstIP, dstPort, Optional[proto], Optional[seed])`	生成网络流哈希
`IsValidLuhn`	`IsValidLuhn(value)`	如果值通过Luhn校验则返回true
`Log`	`Log(value)`	返回自然对数（float64类型）
`URL`	`URL(url_string)`	将URL解析为组件（协议、主机、路径等）
`UserAgent`	`UserAgent(value)`	将用户代理字符串解析为映射（名称、版本、操作系统）