otel-ottl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTelemetry Transformation Language (OTTL)

OTTL transforms or selects telemetry inside Collector components. This skill is pinned to collector-contrib v0.158.0. Function, path, default, and feature-gate availability varies by release; when the user's version differs, verify against the matching upstream tag.

OTTL用于在Collector组件内部转换或选择遥测数据。本技能基于collector-contrib v0.158.0版本。函数、路径、默认值和特性开关的可用性因版本而异；如果用户使用的版本不同，请对照对应的上游标签进行验证。

Workflow

工作流程

Choose the component.
```
transform
```
rewrites,
```
filter
```
drops,
```
tail_sampling
```
decides whether to retain traces, and
```
routing
```
sends telemetry to pipelines. A component controls its available contexts and functions.
Choose the lowest usable context. Lower contexts can read their parents (for example, a span can read
```
resource.attributes
```
), but parents cannot read children. Use
```
datapoint
```
for point attributes instead of traversing
```
metric.data_points
```
.
Verify every emitted function, then write the statement. Confirm each function's exact identifier and signature in references/functions.md. If an identifier is absent, treat it as unsupported instead of deriving or substituting a plausible name. An editor such as
```
set
```
or
```
delete_key
```
mutates data and may have a
```
where
```
condition. Converters such as
```
ParseJSON
```
and
```
IsMatch
```
return values; they do not mutate.
Set error behavior deliberately.
```
ignore
```
logs statement errors and continues;
```
silent
```
continues without logging;
```
propagate
```
returns the error and can cause the component to drop the payload. In v0.158, transform and filter default to
```
ignore
```
; routing also defaults to
```
ignore
```
while its beta default-error feature gate is enabled. For routing,
```
ignore
```
sends an errored payload to
```
default_pipelines
```
; configure that fallback or the payload is dropped.
Verify end to end. Validate the exact Collector version, then send known telemetry and inspect file-exporter output. Use the telemetrygen recipe.

ottl

set(span.attributes["env"], "prod") where resource.attributes["env"] == nil

选择组件。
```
transform
```
用于重写数据，
```
filter
```
用于丢弃数据，
```
tail_sampling
```
用于决定是否保留链路追踪数据，
```
routing
```
用于将遥测数据发送到不同流水线。每个组件会管控其可用的上下文和函数。
选择可用的最低层级上下文。低层级上下文可以读取其父级上下文（例如，span可以读取
```
resource.attributes
```
），但父级上下文无法读取子级上下文。对于指标点属性，请使用
```
datapoint
```
上下文，而非遍历
```
metric.data_points
```
。
验证每个要使用的函数，再编写语句。请在references/functions.md中确认每个函数的确切标识符和签名。如果某个标识符不存在，则视为不支持该函数，不要自行推导或替换为看似合理的名称。
```
set
```
或
```
delete_key
```
这类编辑函数会修改数据，并且可搭配
```
where
```
条件使用。
```
ParseJSON
```
和
```
IsMatch
```
这类转换函数仅返回值，不会修改数据。
明确设置错误处理行为。
```
ignore
```
会记录语句错误并继续执行；
```
silent
```
会继续执行但不记录错误；
```
propagate
```
会返回错误，可能导致组件丢弃数据载荷。在v0.158版本中，transform和filter的默认错误处理行为是
```
ignore
```
；当routing的beta版默认错误特性开关启用时，其默认行为也为
```
ignore
```
。对于routing组件，
```
ignore
```
会将处理出错的载荷发送到
```
default_pipelines
```
；请配置该回退机制，否则载荷会被丢弃。
端到端验证。确认Collector的准确版本，然后发送已知的遥测数据并检查file-exporter的输出。可使用telemetrygen 方案。

ottl

set(span.attributes["env"], "prod") where resource.attributes["env"] == nil

Load only what the task needs

仅加载任务所需内容

Contexts — exact paths, hierarchy, enums, and request metadata.
Functions — editor/converter signatures and release availability.
Quick reference — component YAML, recipes, escaping, troubleshooting, and safe skeletons.

For a single path or function, read only the relevant section instead of loading the full catalogs.

上下文 — 精确路径、层级结构、枚举值和请求元数据。
函数 — 编辑/转换函数的签名及版本可用性。
快速参考 — 组件YAML配置、方案、转义规则、故障排查和安全模板。

如果仅需查看单个路径或函数，请只阅读相关章节，无需加载完整目录。

Safety and correctness gates

安全与正确性校验

Guard optional or polymorphic input before conversion:
```
where x != nil
```
,
```
IsString(x)
```
, or the appropriate type check.
For JSON-object-only work, guard both the type and shape before calling
```
ParseJSON
```
, for example
```
IsString(log.body) and IsMatch(log.body.string, "(?s)^\\s*\\{.*\\}\\s*$")
```
. The RE2
```
(?s)
```
flag admits pretty-printed objects containing newlines. Checking
```
IsMap
```
after parsing does not prevent arrays or scalar JSON from being parsed.
On a version-pinned request, confirm every chosen path and function against that release tag; do not assume a function listed for this skill's v0.158 anchor exists in an older release. For v0.156 JSON-object parsing,
```
ParseJSON
```
,
```
IsString
```
, and
```
IsMatch
```
are available without the v0.157 alpha lambda feature gate.
Request metadata is read-only and may contain credentials. Copy only explicitly allowlisted, non-sensitive keys. OTLP metadata routing requires
```
include_metadata: true
```
on the receiver. HTTP/client header spelling may retain its form (
```
otelcol.client.metadata["X-Tenant"][0]
```
); gRPC metadata keys are lowercase (
```
otelcol.grpc.metadata["x-tenant"][0]
```
).
The routing
```
request
```
context is deprecated as of v0.156; use
```
otelcol.client.metadata
```
or
```
otelcol.grpc.metadata
```
.
Log-record-specific rewrites of shared resource or scope data require
```
flatten_data: true
```
and the alpha
```
transform.flatten.logs
```
gate. This copies and regroups data; do not enable it accidentally.
Hashing an identifier does not necessarily anonymize it. Apply the organization's data-handling policy before retaining deterministic hashes of personal data.

在转换前对可选或多态输入进行校验：使用
```
where x != nil
```
、
```
IsString(x)
```
或相应的类型检查。
仅处理JSON对象时，调用
```
ParseJSON
```
前需同时校验类型和格式，例如
```
IsString(log.body) and IsMatch(log.body.string, "(?s)^\\s*\\{.*\\}\\s*$")
```
。RE2的
```
(?s)
```
标志允许包含换行符的格式化JSON对象。解析后检查
```
IsMap
```
无法阻止数组或标量JSON被解析。
如果请求指定了版本，请对照该版本标签确认所选的每个路径和函数；不要假设本技能基于v0.158版本列出的函数在旧版本中也存在。对于v0.156版本的JSON对象解析，
```
ParseJSON
```
、
```
IsString
```
和
```
IsMatch
```
无需启用v0.157的alpha lambda特性开关即可使用。
请求元数据为只读状态，可能包含凭证信息。仅复制明确允许的非敏感键。OTLP元数据路由要求接收器设置
```
include_metadata: true
```
。HTTP/客户端请求头的拼写会保留原有格式（如
```
otelcol.client.metadata["X-Tenant"][0]
```
）；gRPC元数据键为小写（如
```
otelcol.grpc.metadata["x-tenant"][0]
```
）。
从v0.156版本开始，routing的
```
request
```
上下文已被弃用；请使用
```
otelcol.client.metadata
```
或
```
otelcol.grpc.metadata
```
。
针对日志记录重写共享资源或范围数据时，需要设置
```
flatten_data: true
```
并启用alpha版
```
transform.flatten.logs
```
特性开关。此操作会复制并重新分组数据，请勿意外启用。
对标识符进行哈希处理并不一定能实现匿名化。在保留个人数据的确定性哈希值前，请遵循组织的数据处理政策。

Frequent syntax traps

常见语法陷阱

In Collector YAML, write an OTTL replacement backreference
```
${1}
```
as
```
$${1}
```
. A replacement such as
```
$1REDACTED
```
is literal and silently fails to substitute the capture.
Go RE2 rejects large counted repetitions such as
```
(.{1024}).*
```
; use
```
Substring
```
with a nil/type guard and
```
Len
```
, or
```
truncate_all
```
for a map.
Current span-event paths use
```
spanevent.*
```
, not
```
span_event.*
```
. Cache paths are context-qualified, such as
```
span.cache["parsed"]
```
.
Use
```
Decode(value, "base64")
```
;
```
Base64Decode
```
is deprecated.
Regex escapes inside OTTL strings are doubled (
```
\\d
```
,
```
\\s
```
,
```
\\.
```
).

在Collector的YAML配置中，OTTL替换的反向引用
```
${1}
```
需要写为
```
$${1}
```
。像
```
$1REDACTED
```
这样的替换会被视为字面量，无法静默替换捕获的内容。
Go RE2不支持大数量的重复匹配，如
```
(.{1024}).*
```
；请结合空值/类型校验和
```
Len
```
函数使用
```
Substring
```
，或对映射使用
```
truncate_all
```
。
当前的span事件路径使用
```
spanevent.*
```
，而非
```
span_event.*
```
。缓存路径需要带上上下文限定，例如
```
span.cache["parsed"]
```
。
请使用
```
Decode(value, "base64")
```
；
```
Base64Decode
```
已被弃用。
OTTL字符串中的正则表达式转义符需要写两次（如
```
\\d
```
、
```
\\s
```
、
```
\\.
```
）。

otel-ottl

Original

Translation

OpenTelemetry Transformation Language (OTTL)

OpenTelemetry Transformation Language (OTTL)

Workflow

工作流程

Load only what the task needs

仅加载任务所需内容

Safety and correctness gates

安全与正确性校验

Frequent syntax traps

常见语法陷阱

Upstream sources

上游资源