Grafana Tempo 中的 OTTL Resource Context 使用指南基于 OTTL 对 OTLP 资源进行转换与过滤【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本文以仓库 vendored 的 ottlresource/README.md 为核心结合 resource.go 与ctxresource内部实现系统讲解 OTTLOpenTelemetry Transformation Language的 Resource Context 的路径Paths、枚举Enums能力及其在 Tempo 中的接入方式。读完本文你将掌握如何用resource.attributes、resource.cache等路径编写 OTTL 语句理解其底层访问机制并能结合 forwarder 等在 Tempo 中落地资源级数据变换。什么是 OTTL Resource ContextOTTL 是 OpenTelemetry Collector Contrib 提供的一门小型领域专用语言用于以 OpenTelemetry 原生概念处理遥测数据。在 Tempo 中OTTL 被用作分布式追踪后端数据处理的关键手段go.mod 中声明了依赖github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl v0.153.0见 go.mod并通过 vendor 目录 完整带入源码。Resource Context 是 OTTL 众多 ContextSpan、SpanEvent、Metric、DataPoint、Log、Profile 等中专门针对pdata Resource的一种实现。pdata 是 Collector 对 OTLP 数据的内部内存表示而一个 OTLP Resource 描述的是产生遥测数据的实体如一个服务、一个主机、一个容器或一个进程它由一组属性attributes、一个 schema URL 以及被丢弃的属性计数组成。适用场景只需要与 OTLP Resource 交互的转换或过滤逻辑使用约束OTTL 目前不支持跨信号cross-signal交互因此不能在一条语句中同时读写 Resource 与其他 Context 的数据版本约束文档说明内容仅适用于v0.120.0 及之后的版本更早版本的行为以当时文档为准。Resource Context 支持的路径PathsResource Context 的路径设计遵循一个总体原则复用 resource.proto 中的字段名来访问 pdata 数据并在读取/写入时统一类型所有整数以int64返回与设置所有浮点数以float64返回与设置。完整路径表路径访问的字段类型resource.cache当前变换上下文临时缓存的值可在复杂变换期间用作数据的临时占位pcommon.Mapresource.cache[]缓存中某项的值支持多个下标访问嵌套字段string、bool、int64、float64、pcommon.Map、pcommon.Slice、[]byte或nilresource.attributes正在被处理的 Resource 的属性pcommon.Mapresource.attributes[]正在被处理的 Resource 的某个属性值支持多个下标访问嵌套字段string、bool、int64、float64、pcommon.Map、pcommon.Slice、[]byte或nilresource.dropped_attributes_count正在被处理的 Resource 被丢弃的属性数量int64otelcol.*ottlotelcol 上下文暴露的全部路径视具体路径而定路径的底层实现源码佐证路径解析的入口位于 resource.go 的NewParser它委托ctxcommon.NewParser并注入资源专用的pathExpressionParser核心分发逻辑在 internal/ctxresource/resource.go 的PathGetSetter中按路径名attributes、dropped_attributes_count、schema_url分发到对应的 GetSetterresource.attributes的读取直接返回tCtx.GetResource().Attributes()写入则通过ctxutil.SetMap完成见 resource.go#L33-L42resource.attributes[key]支持多级下标通过ctxutil.GetMapValue/ctxutil.SetMapValue在属性 Map 上按 key 链读写见 resource.go#L44-L53resource.dropped_attributes_count读取时返回int64(...)设置时先做int64类型校验再转uint32写回见 resource.go#L55-L69从源码结构看内部实现还额外暴露了resource.schema_url读写 Resource 的 SchemaURLItem见 resource.go#L71-L85可用作资源级 schema URL 的读取与改写。上下文名的解析与 cache 访问路径解析器的通用逻辑在 internal/ctxcommon/parser.go若语句路径不带上下文前缀如直接写attributes[k]会默认归一化到本上下文resourceresource.cache的访问仅允许出现在本上下文中若其他上下文尝试访问会返回错误每个 Context 在contextParsers中注册自己的路径解析器Resource Context 同时注册了resource与otelcol两个解析器见 resource.go#L161-L170。路径上下文名的显式启用ExperimentalTransformContext提供实验性选项EnablePathContextNames启用后语句中的所有路径都必须带有合法的上下文前缀resource或otelcol否则会报错。该选项与常量ContextName resource见 resource.go#L28-L30配合使用均标记为 Experimental未来可能变更或移除。Resource Context 的枚举EnumsResource Context当前不定义任何 Enums。这与源码实现一致parseEnum直接返回错误resource context does not provide Enum support见 resource.go#L153-L155因此在该上下文中无法使用 OTTL 的枚举符号Enum Symbols语法。编写 Resource 级 OTTL 语句OTTL 语句由两部分组成一个对遥测数据进行变换的函数以及一个可选的条件where 子句条件决定函数是否执行。在 Resource Context 中路径以resource.为前缀例如set(resource.attributes[deployment.environment], production) where resource.attributes[deployment.environment] nil这条语句在 Resource 尚不存在deployment.environment属性时为该属性赋值为production。其中set是函数where之后是条件。再比如利用 cache 作为临时占位set(resource.cache[tmp], resource.attributes[service.name]) set(resource.attributes[service.name], resource.cache[tmp]) where resource.attributes[service.name] ! nil可用的 OTTL 函数set、delete_key、keep_keys、merge_maps等由使用方注入的functions map[string]ottl.Factory[*TransformContext]决定见 resource.go#L138-L151。注意OTTL 不支持跨信号交互因此不能写出类似set(resource.attributes[x], span.attributes[y])的语句。在 Tempo 中使用 Resource ContextTempo 将 OTTL 作为供应商级依赖引入v0.153.0见 go.mod具体消费点包括转发器forwardermodules/distributor/forwarder/forwarder.go通过 OTTL 表达式对 trace 数据做条件判断与转发决策其配套测试 ottl_ismatch_test.go 覆盖了 OTTL 匹配逻辑依托 vendored 的完整 OTTL 包vendor/github.com/open-telemetry/opentelemetry-collector-contrib/pkg/ottl其中包含全部 Context 实现contexts 目录以及 OTTL 语言规范 LANGUAGE.md。在基于 OTTL 的组件如 Collector 的 transform processor、filter processor、tail sampling processor、routing connector 等中若配置的上下文包含 Resource即可在语句与条件中使用上文的resource.*路径对 OTLP Resource 做增删改查Tempo 的 forwarder 同样遵循这一模式在资源与 span 级数据上执行 OTTL 判定。调试与排障当 OTTL 语句行为与预期不符时可以将 Collector/Tempo 的日志级别调整为 debug。OTTL 会在执行期打印当前语句、条件是否命中以及完整的 TransformContext 视图包括resource、scope、信号体与cache。例如将日志级别设为service: telemetry: logs: level: debug随后即可在日志中看到类似如下的输出片段debug parser.go initial TransformContext {TransformContext: {resource: {attributes: {}, dropped_attribute_count: 0}, ... cache: {}}} debug parser.go TransformContext after statement execution {statement: set(resource.attributes[\test\], \pass\), condition matched: true, TransformContext: {resource: {attributes: {test: pass}, ...}}}通过对比语句执行前后的 TransformContext可以准确判断resource.attributes是否按预期被修改、条件是否命中。小结Resource Context 专门用于处理 OTLP Resource支持resource.cache、resource.cache[]、resource.attributes、resource.attributes[]、resource.dropped_attributes_count及otelcol.*等路径源码还额外提供resource.schema_url所有整数以int64、浮点数以float64读写cache 与属性均支持多级下标访问嵌套字段该上下文当前不提供任何 Enums文档与实现均针对 OTTL v0.120.0 之后的版本Tempo 当前 vendored 的版本为 v0.153.0结合 debug 日志打印 TransformContext与 forwarder 的 OTTL 用法可以快速定位并验证资源级转换语句的正确性。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
