OpenTelemetry Collector 组件文档生成实战深入解读 mdatagen 生成的 Sample Receiver 文档【免费下载链接】opentelemetry-collectorOpenTelemetry Collector项目地址: https://gitcode.com/GitHub_Trending/op/opentelemetry-collectormdatagenMetadata Generator是 OpenTelemetry Collector 仓库中负责把组件metadata.yaml元数据转换为标准化文档与 Go 代码的代码生成器。本文以仓库内置的示例组件 Sample Receiver 为例逐段剖析 cmd/mdatagen/internal/samplereceiver/documentation.md 这份由 mdatagen 自动生成的组件文档它覆盖默认/可选指标Metrics、事件Events、资源属性Resource Attributes、内部遥测Internal Telemetry与特性开关Feature Gates五大板块。读完本文你将能熟练阅读任意 Collector 组件的生成文档理解各配置项与稳定性级别的准确含义并掌握如何通过 metadata.yaml 反查文档中每一项声明的源头。一、这份文档是什么mdatagen 输出格式的官方样例OpenTelemetry Collector 的每个组件都应附带组件简介 使用指引文档同时还应包含帮助用户判断组件成熟度的元数据信息例如稳定性级别、包含它的发行版、支持的管线类型、scraping receiver/scraper/connector 会发出的指标等。为了让这些信息完整且格式统一mdatagen定义了 metadata-schema.yaml 来约束元数据描述再依据它生成标准化格式的文档。samplereceiver/documentation.md就是该生成文档的官方参考样例它的文件头也明确标注了Code generated by mdatagen. DO NOT EDIT.——这意味着读者在任何组件目录下见到的documentation.md都是同一套模板渲染出来的产物结构完全可预期。与这份文档配套的是同一目录下的 metadata.yaml其文件头注释说明了它的定位Sample metadata file with all available configurations for a receiver包含 receiver 全部可用配置的样例元数据文件。它被设计为覆盖 mdatagen 所支持的绝大多数配置能力因此这份文档可以看作 mdatagen 文档能力的完整功能清单。从源码结构看文档中的每个小节都可以在 metadata.yaml 中找到对应的源配置段Default Metrics/Optional Metrics←metrics段Default Events/Optional Events←events段Resource Attributes←resource_attributes段Internal Telemetry←telemetry段Feature Gates←feature_gates段二、默认指标Default Metrics开启状态与关闭方式文档的第一大板块是默认指标。默认开启的指标用户可以通过如下配置将其关闭metrics: metric_name: enabled: false每个指标条目都以### 指标名为标题下方依次是描述Description、扩展文档extended_documentation如果有、指标特征表单位/指标类型/值类型/聚合时态/单调性/稳定性/语义约定、弃用说明Deprecation note如果有、属性表Attributes。下面逐一解读样例文档中的 7 个默认指标。2.1 default.metricMonotonic cumulative sum int metric enabled by default. The metric will be become optional soon.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitysSumIntCumulativetrueDeprecated since 1.0.0Deprecation note: This metric will be removed该指标携带 8 个属性覆盖了 mdatagen 支持的全部属性形态NameDescriptionValuesRequirement LevelSemantic Conventionstring_attrAttribute with any string value.Any StrRecommended-stateInteger attribute with overridden name.Any IntRecommended-enum_attrAttribute with a known set of string values.Str:red,green,blueRecommended-slice_attrAttribute with a slice value.Any SliceRecommended-map_attrAttribute with a map value.Any MapRecommended-conditional_int_attrA conditional attribute with an integer valueAny IntConditionally Required-conditional_string_attrA conditional attribute with any string valueAny StrConditionally Required-opt_in_bool_attrAn opt-in attribute with a boolean valueAny BoolOpt-In-在 metadata.yaml 中可以看到该指标的原始定义stability: deprecated、deprecated.since: 1.0.0、deprecated.note: This metric will be removed并声明sum: {value_type: int, monotonic: true, aggregation_temporality: cumulative}。属性表里的state之所以标注为 Integer attribute with overridden name是因为它在 metadata.yaml 中实际由overridden_int_attrname_override: state定义——这是 mdatagen 支持的重命名属性能力。枚举属性enum_attr在生成的 Go 代码中被转成强类型常量见 generated_metrics.go 中的AttributeEnumAttr类型与MapAttributeEnumAttr辅助映射表。2.2 default.metric.to_be_removed[DEPRECATED] Non-monotonic delta sum double metric enabled by default. The metric will be removed soon.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitysSumDoubleDeltafalseDeprecated since 1.0.0Deprecation note: This metric will be removed这是一个待移除指标的例子Monotonic: false表示非单调递增Aggregation Temporality: Delta表示每次上报的数据是自上次上报以来的增量。对应 metadata.yaml 中sum.value_type: double、sum.monotonic: false、sum.aggregation_temporality: delta的声明。2.3 metric.input_typeMonotonic cumulative sum int metric with string input_type enabled by default.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitysSumIntCumulativetrueDevelopment属性string_attr、state、enum_attr、slice_attr、map_attr同 2.1 中的同名属性定义。该指标展示了input_type: string的用法——在 metadata.yaml 中它虽然生成Int值类型的 Sum 指标但声明了input_type: string即接收方从数据源读到的是字符串由生成代码负责转换。稳定性为Development。2.4 reaggregate.metric 与 reaggregate.metric.with_requiredMetric for testing spatial reaggregationUnitMetric TypeValue TypeStability1GaugeDoubleBeta属性string_attr、boolean_attr。Metric for testing spatial reaggregation with required attributesUnitMetric TypeValue TypeStability1GaugeDoubleBeta属性required_string_attrRequired、string_attr、boolean_attr。这两个 Gauge 指标用于测试**空间再聚合spatial reaggregation**能力。mdatagen 允许用户通过丢弃部分指标属性来降低基数再对折叠后的数据点进行聚合用户侧配置为每个指标暴露两个设置项attributes保留的属性子集与aggregation_strategy取sum/avg/min/max。从 metadata.yaml 看reaggregate.metric.with_required声明了required_string_attrrequirement_level: required而生成规则保证required 属性永远被保留、无法被用户移除——这是 reaggation 配置见 internal/metadata/testdata/config.yaml 中的reaggregate_set场景与校验逻辑共同保证的。默认情况下Sum 指标默认sum策略、Gauge 指标默认avg策略。2.5 system.cpu.timeMonotonic cumulative sum int metric enabled by default. The metric will be become optional soon.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitySemantic ConventionsSumIntCumulativetrueBetasystem.cpu.time属性NameDescriptionValuesRequirement LevelSemantic ConventioncpuLogical CPU number starting at 0.Any StrRecommended-该指标演示了语义约定Semantic Convention关联。文档中其语义约定列指向system.cpu.time这来自 metadata.yaml 中的semantic_convention.ref: system/system-metrics.md#metric-systemcputime配合文件头部的sem_conv_version: 1.40.0mdatagen 会按版本号生成对应的引用与常量代码生成的 Go 代码中导入了go.opentelemetry.io/otel/semconv/v1.40.0。2.6 system.memory.usageBytes of memory in use.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilityBySumIntCumulativefalseDevelopment属性NameDescriptionValuesRequirement LevelSemantic ConventionstateBreakdown of memory usage by type.Str:buffered,cached,inactive,free,slab_reclaimable,slab_unreclaimable,usedRecommendedstate注意此处的state与 2.1 中的state是两个不同属性这里它由 metadata.yaml 中的state定义enum枚举 7 种内存状态semantic_convention.ref: system.md#system-memory-state而 2.1 中的state是overridden_int_attr的重命名产物。生成代码中会为枚举创建独立的强类型见 generated_metrics.go 中的AttributeState。单位By字节与语义约定保持了一致。三、可选指标Optional Metrics按需开启默认不发出的指标可以通过如下配置开启metrics: metric_name: enabled: true3.1 optional.metric[DEPRECATED] Gauge double metric disabled by default.UnitMetric TypeValue TypeStability1GaugeDoubleDeprecated since 1.0.0Deprecation note: This metric will be removed属性string_attr、boolean_attr、boolean_attr2、conditional_string_attr。在 metadata.yaml 中它以enabled: false声明。boolean_attr2的存在是为了测试布尔属性两种取值的边界情况源码注释说明测试值基于属性名长度的奇偶性。在生成的MetricsBuilderConfig中可选指标的enabled默认值为false与默认指标形成对称。3.2 optional.metric.empty_unit[DEPRECATED] Gauge double metric disabled by default.UnitMetric TypeValue TypeStabilityGaugeDoubleDeprecated since 1.0.0Deprecation note: This metric will be removed属性string_attr、boolean_attr。该指标用于验证**空单位empty unit**场景对应 metadata.yaml 中的unit: 文档中单位列为空字符串说明 mdatagen 对空单位有正确的空值渲染处理。四、事件Events日志信号的新成员事件板块的开关语法与指标完全对称默认事件关闭方式events: event_name: enabled: false默认关闭事件开启方式events: event_name: enabled: true4.1 default.event默认事件Example event enabled by default.属性NameDescriptionValuesSemantic Conventionstring_attrAttribute with any string value.Any Str-stateInteger attribute with overridden name.Any Int-enum_attrAttribute with a known set of string values.Str:red,green,blue-slice_attrAttribute with a slice value.Any Slice-map_attrAttribute with a map value.Any Map-conditional_int_attrA conditional attribute with an integer valueAny Int-conditional_string_attrA conditional attribute with any string valueAny Str-opt_in_bool_attrAn opt-in attribute with a boolean valueAny Bool-事件的属性表与指标属性表基本相同区别在于没有 Requirement Level 列。在 metadata.yaml 中default.event声明enabled: true并通过warnings.if_enabled_not_set提示该事件很快会改为默认关闭。4.2 default.event.to_be_removed默认事件[DEPRECATED] Example to-be-removed event enabled by default. The event will be removed soon.属性string_attr、state、enum_attr、slice_attr、map_attr。4.3 default.event.to_be_renamed可选事件[DEPRECATED] Example event disabled by default. The event will be renamed soon.属性string_attr、boolean_attr、boolean_attr2、conditional_string_attr。这个事件虽然名字带default.event前缀但实际是默认关闭的enabled: false并提示即将重命名。它出现在 Optional Events 板块说明决定文档归属板块的是enabled默认值而非指标名。五、资源属性Resource Attributes资源属性表是文档中最能体现用户可配置性的部分。每个资源属性都带Enabled列表示该属性默认是否随资源发出NameDescriptionValuesEnabledSemantic ConventionStabilityhost.archThe CPU architecture the host system is running on.Any Strfalsehost.arch-map.resource.attrResource attribute with a map value.Any Maptrue-Developmentoptional.resource.attrExplicitly disabled ResourceAttribute.Any Strfalse-Developmentslice.resource.attrResource attribute with a slice value.Any Slicetrue-Developmentstring.enum.resource.attrResource attribute with a known set of string values.Str:one,twotrue--string.resource.attrResource attribute with any string value.Any Strtrue--string.resource.attr_disable_warningResource attribute with any string value.Any Strtrue--string.resource.attr_remove_warningResource attribute with any string value.Any Strfalse--string.resource.attr_to_be_removedResource attribute with any string value.Any Strtrue--string.resource.disabled_attr_to_be_removedResource attribute with any string value.Any Strfalse--这 10 个资源属性在 metadata.yaml 中有着精细的区分用来覆盖 mdatagen 的各类能力分支值类型string、map、slice、string enum覆盖基本类型与容器类型启用状态enabled: true/false分别对应Enabled: true/false稳定性仅map/slice/optional三个属性声明了stability: development其余不声明文档显示-语义约定host.arch与state见 2.6关联了语义约定引用其余显示-警告warningsattr_disable_warning声明了if_enabled_not_set提示即将默认关闭attr_remove_warning声明了if_configured提示已弃用、即将移除attr_to_be_removed声明了if_enableddisabled_attr_to_be_removed同时为关闭态声明if_enabled警告——mdatagen 会依据用户在配置中是否显式设置enabled来渲染对应的弃用提示。资源属性在生成的 Go 代码中对应ResourceBuilder见 generated_resource.go为每个属性生成SetXxx方法带enabled守卫为枚举值生成独立的SetStringEnumResourceAttrOne/Two方法Emit()时还会应用override_value覆盖值与基于metrics_include/metrics_exclude的过滤器。上述 include/exclude 过滤与 override 的完整用户配置样例可以在 internal/metadata/testdata/config.yaml 的override_set、filter_set_include、filter_set_exclude段中查看。六、内部遥测Internal Telemetry组件自身可观测性内部遥测是**组件自身而非业务数据**上报的指标一般以前缀otelcol_命名。文档声明以下遥测由该组件发出共 5 个6.1 otelcol_batch_size_trigger_sendNumber of times the batch was sent due to a size triggerDeprecated since 1.5.0This metric will be removed in favor of batch_send_trigger_sizeUnitMetric TypeValue TypeMonotonicStability{time}SumInttrueDeprecated since 1.5.0Deprecation note: This metric will be removed in favor of batch_send_trigger_size对应 metadata.yaml 的telemetry.metrics.batch_size_trigger_send同步syncSum 计数器。在 generated_telemetry.go 中它被生成为metric.Int64Counter类型的BatchSizeTriggerSend字段组件代码通过telemetryBuilder.BatchSizeTriggerSend.Add(ctx, 1)直接打点见 factory.go。6.2 otelcol_process_runtime_total_alloc_bytesCumulative bytes allocated for heap objects (see go doc runtime.MemStats.TotalAlloc)UnitMetric TypeValue TypeMonotonicStabilityBySumInttrueStable这是异步async/observableSum指标sum.async: true对应生成代码中的metric.Int64ObservableCounter见 generated_telemetry.go并通过RegisterProcessRuntimeTotalAllocBytesCallback注册回调采集值factory.go 中示范了回调写法恒定上报值 2 用于测试。6.3 otelcol_queue_capacityQueue capacity - sync gauge example.UnitMetric TypeValue TypeStability{item}GaugeIntDevelopment同步 Gauge 示例生成类型为metric.Int64Gauge。6.4 otelcol_queue_lengthThis metric is optional and therefore not initialized in NewTelemetryBuilder. For example this metric only exists if feature A is enabled.UnitMetric TypeValue TypeStability{item}GaugeIntAlpha注意这段 extended_documentation 点明了 mdatagen 的一个重要机制optional: true的遥测指标不会被NewTelemetryBuilder初始化见 metadata.yaml。它对应的QueueLength字段类型为metric.Int64ObservableGauge由RegisterQueueLengthCallback按需注册factory.go 的initOptionalMetric示例。组件只有在特性开关启用等条件下才调用该方法从而避免无条件创建无用仪器。6.5 otelcol_request_durationDuration of requestUnitMetric TypeValue TypeStabilitysHistogramDoubleAlpha直方图Histogram示例生成类型为metric.Float64Histogram其分桶边界在 metadata.yaml 中声明为bucket_boundaries: [1, 10, 100]生成代码中通过metric.WithExplicitBucketBoundaries([]float64{1, 10, 100}...)显式设置见 generated_telemetry.go。七、特性开关Feature Gates文档最后一个板块列出了组件注册的特性开关Feature GateStageDescriptionFrom VersionTo VersionReferencereceiver.sample.featuregate.examplealphaThis is an example feature gate for testing mdatagen code generation.v0.100.0N/ALink该条目直接来自 metadata.yaml 的feature_gates段id、description、stage、from_version、reference_url一一对应。同时mdatagen 还会生成注册代码——generated_feature_gates.go 中通过featuregate.GlobalRegistry().MustRegister(...)将receiver.sample.featuregate.example以StageAlpha级别注册进全局注册表并携带描述、参考 URL 与引入版本。特性开关的详细使用说明见 featuregate/README.md。关于严格校验mdatagen 默认要求每个 gate 的id以status.class.type.前缀命名空间化本例即receiver.sample.且reference_url必须是 GitHub issue 形式。八、从文档反查实现一份 metadata.yaml 的代码生成全景samplereceiver/documentation.md之所以信息密度高是因为它聚合了 metadata.yaml 中几乎全部字段的渲染结果。对照同一目录下的生成产物可以完整还原其代码生成链路文档板块metadata.yaml 源生成代码主要生成产物Default/Optional Metricsmetricsattributesgenerated_metrics.goMetricsBuilder、MetricsInfo、枚举常量、聚合策略常量指标启停配置metrics.*.enabledgenerated_config.goMetricsBuilderConfig及各指标enabled/attributes/aggregation_strategy配置结构Eventseventsgenerated_logs.go事件构建器与配置Resource Attributesresource_attributesgenerated_resource.goResourceBuilder、各SetXxx方法、override/过滤器支持Internal Telemetrytelemetrygenerated_telemetry.goTelemetryBuilder、同步/异步仪器字段、回调注册方法Feature Gatesfeature_gatesgenerated_feature_gates.go特性开关注册调用在运行时组件工厂 factory.go 通过metadata.NewTelemetryBuilder(set.TelemetrySettings)构建遥测构建器、注册异步回调、并在Shutdown中调用telemetryBuilder.Shutdown()注销全部回调——这正是文档中Internal Telemetry一节对应代码的落地方式。组件自身的配置如endpoint、timeout、api_token等则来自 config.schema.json并由 generated_config.go 生成带mapstructure标签的Config结构体与createDefaultConfig()默认值localhost:12345、10s、100。完整配置参考表见同一目录下的 README.md其中还包含组件状态表profiles 已弃用、logs 为 development、traces 为 beta、metrics 为 stable。九、如何生成与使用这类文档如果你在自己的组件中维护metadata.yaml通常按以下步骤接入 mdatagen详见 cmd/mdatagen/README.md在组件包内放置metadata.yaml在doc.go中声明//go:generate mdatagen metadata.yaml运行cd cmd/mdatagen go install .安装工具后执行mdatagen metadata.yaml或直接运行make generate为所有组件批量生成文档与代码修改生成器本身时需同步更新 metadata-schema.yaml 与 metadata.yaml并运行make mdatagen-test保证生成测试如 generated_metrics_test.go全部通过。生成出的documentation.md就是组件面向用户的指标/事件/资源属性/遥测/特性开关权威说明书。用户在部署 Collector 时只需对照该文档在组件的配置节下按metrics、events、resource_attributes键控制每一项的启用状态、属性保留集合与聚合策略即可在默认行为、降基数、兼容性控制之间自由取舍。【免费下载链接】opentelemetry-collectorOpenTelemetry Collector项目地址: https://gitcode.com/GitHub_Trending/op/opentelemetry-collector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/16 14:33:52 · 阅读 1.2k OpenTelemetry Collector 组件文档生成实战：深入解读 mdatagen 生成的 Sample Receiver 文档
OpenTelemetry Collector 组件文档生成实战深入解读 mdatagen 生成的 Sample Receiver 文档【免费下载链接】opentelemetry-collectorOpenTelemetry Collector项目地址: https://gitcode.com/GitHub_Trending/op/opentelemetry-collectormdatagenMetadata Generator是 OpenTelemetry Collector 仓库中负责把组件metadata.yaml元数据转换为标准化文档与 Go 代码的代码生成器。本文以仓库内置的示例组件 Sample Receiver 为例逐段剖析 cmd/mdatagen/internal/samplereceiver/documentation.md 这份由 mdatagen 自动生成的组件文档它覆盖默认/可选指标Metrics、事件Events、资源属性Resource Attributes、内部遥测Internal Telemetry与特性开关Feature Gates五大板块。读完本文你将能熟练阅读任意 Collector 组件的生成文档理解各配置项与稳定性级别的准确含义并掌握如何通过 metadata.yaml 反查文档中每一项声明的源头。一、这份文档是什么mdatagen 输出格式的官方样例OpenTelemetry Collector 的每个组件都应附带组件简介 使用指引文档同时还应包含帮助用户判断组件成熟度的元数据信息例如稳定性级别、包含它的发行版、支持的管线类型、scraping receiver/scraper/connector 会发出的指标等。为了让这些信息完整且格式统一mdatagen定义了 metadata-schema.yaml 来约束元数据描述再依据它生成标准化格式的文档。samplereceiver/documentation.md就是该生成文档的官方参考样例它的文件头也明确标注了Code generated by mdatagen. DO NOT EDIT.——这意味着读者在任何组件目录下见到的documentation.md都是同一套模板渲染出来的产物结构完全可预期。与这份文档配套的是同一目录下的 metadata.yaml其文件头注释说明了它的定位Sample metadata file with all available configurations for a receiver包含 receiver 全部可用配置的样例元数据文件。它被设计为覆盖 mdatagen 所支持的绝大多数配置能力因此这份文档可以看作 mdatagen 文档能力的完整功能清单。从源码结构看文档中的每个小节都可以在 metadata.yaml 中找到对应的源配置段Default Metrics/Optional Metrics←metrics段Default Events/Optional Events←events段Resource Attributes←resource_attributes段Internal Telemetry←telemetry段Feature Gates←feature_gates段二、默认指标Default Metrics开启状态与关闭方式文档的第一大板块是默认指标。默认开启的指标用户可以通过如下配置将其关闭metrics: metric_name: enabled: false每个指标条目都以### 指标名为标题下方依次是描述Description、扩展文档extended_documentation如果有、指标特征表单位/指标类型/值类型/聚合时态/单调性/稳定性/语义约定、弃用说明Deprecation note如果有、属性表Attributes。下面逐一解读样例文档中的 7 个默认指标。2.1 default.metricMonotonic cumulative sum int metric enabled by default. The metric will be become optional soon.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitysSumIntCumulativetrueDeprecated since 1.0.0Deprecation note: This metric will be removed该指标携带 8 个属性覆盖了 mdatagen 支持的全部属性形态NameDescriptionValuesRequirement LevelSemantic Conventionstring_attrAttribute with any string value.Any StrRecommended-stateInteger attribute with overridden name.Any IntRecommended-enum_attrAttribute with a known set of string values.Str:red,green,blueRecommended-slice_attrAttribute with a slice value.Any SliceRecommended-map_attrAttribute with a map value.Any MapRecommended-conditional_int_attrA conditional attribute with an integer valueAny IntConditionally Required-conditional_string_attrA conditional attribute with any string valueAny StrConditionally Required-opt_in_bool_attrAn opt-in attribute with a boolean valueAny BoolOpt-In-在 metadata.yaml 中可以看到该指标的原始定义stability: deprecated、deprecated.since: 1.0.0、deprecated.note: This metric will be removed并声明sum: {value_type: int, monotonic: true, aggregation_temporality: cumulative}。属性表里的state之所以标注为 Integer attribute with overridden name是因为它在 metadata.yaml 中实际由overridden_int_attrname_override: state定义——这是 mdatagen 支持的重命名属性能力。枚举属性enum_attr在生成的 Go 代码中被转成强类型常量见 generated_metrics.go 中的AttributeEnumAttr类型与MapAttributeEnumAttr辅助映射表。2.2 default.metric.to_be_removed[DEPRECATED] Non-monotonic delta sum double metric enabled by default. The metric will be removed soon.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitysSumDoubleDeltafalseDeprecated since 1.0.0Deprecation note: This metric will be removed这是一个待移除指标的例子Monotonic: false表示非单调递增Aggregation Temporality: Delta表示每次上报的数据是自上次上报以来的增量。对应 metadata.yaml 中sum.value_type: double、sum.monotonic: false、sum.aggregation_temporality: delta的声明。2.3 metric.input_typeMonotonic cumulative sum int metric with string input_type enabled by default.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitysSumIntCumulativetrueDevelopment属性string_attr、state、enum_attr、slice_attr、map_attr同 2.1 中的同名属性定义。该指标展示了input_type: string的用法——在 metadata.yaml 中它虽然生成Int值类型的 Sum 指标但声明了input_type: string即接收方从数据源读到的是字符串由生成代码负责转换。稳定性为Development。2.4 reaggregate.metric 与 reaggregate.metric.with_requiredMetric for testing spatial reaggregationUnitMetric TypeValue TypeStability1GaugeDoubleBeta属性string_attr、boolean_attr。Metric for testing spatial reaggregation with required attributesUnitMetric TypeValue TypeStability1GaugeDoubleBeta属性required_string_attrRequired、string_attr、boolean_attr。这两个 Gauge 指标用于测试**空间再聚合spatial reaggregation**能力。mdatagen 允许用户通过丢弃部分指标属性来降低基数再对折叠后的数据点进行聚合用户侧配置为每个指标暴露两个设置项attributes保留的属性子集与aggregation_strategy取sum/avg/min/max。从 metadata.yaml 看reaggregate.metric.with_required声明了required_string_attrrequirement_level: required而生成规则保证required 属性永远被保留、无法被用户移除——这是 reaggation 配置见 internal/metadata/testdata/config.yaml 中的reaggregate_set场景与校验逻辑共同保证的。默认情况下Sum 指标默认sum策略、Gauge 指标默认avg策略。2.5 system.cpu.timeMonotonic cumulative sum int metric enabled by default. The metric will be become optional soon.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilitySemantic ConventionsSumIntCumulativetrueBetasystem.cpu.time属性NameDescriptionValuesRequirement LevelSemantic ConventioncpuLogical CPU number starting at 0.Any StrRecommended-该指标演示了语义约定Semantic Convention关联。文档中其语义约定列指向system.cpu.time这来自 metadata.yaml 中的semantic_convention.ref: system/system-metrics.md#metric-systemcputime配合文件头部的sem_conv_version: 1.40.0mdatagen 会按版本号生成对应的引用与常量代码生成的 Go 代码中导入了go.opentelemetry.io/otel/semconv/v1.40.0。2.6 system.memory.usageBytes of memory in use.UnitMetric TypeValue TypeAggregation TemporalityMonotonicStabilityBySumIntCumulativefalseDevelopment属性NameDescriptionValuesRequirement LevelSemantic ConventionstateBreakdown of memory usage by type.Str:buffered,cached,inactive,free,slab_reclaimable,slab_unreclaimable,usedRecommendedstate注意此处的state与 2.1 中的state是两个不同属性这里它由 metadata.yaml 中的state定义enum枚举 7 种内存状态semantic_convention.ref: system.md#system-memory-state而 2.1 中的state是overridden_int_attr的重命名产物。生成代码中会为枚举创建独立的强类型见 generated_metrics.go 中的AttributeState。单位By字节与语义约定保持了一致。三、可选指标Optional Metrics按需开启默认不发出的指标可以通过如下配置开启metrics: metric_name: enabled: true3.1 optional.metric[DEPRECATED] Gauge double metric disabled by default.UnitMetric TypeValue TypeStability1GaugeDoubleDeprecated since 1.0.0Deprecation note: This metric will be removed属性string_attr、boolean_attr、boolean_attr2、conditional_string_attr。在 metadata.yaml 中它以enabled: false声明。boolean_attr2的存在是为了测试布尔属性两种取值的边界情况源码注释说明测试值基于属性名长度的奇偶性。在生成的MetricsBuilderConfig中可选指标的enabled默认值为false与默认指标形成对称。3.2 optional.metric.empty_unit[DEPRECATED] Gauge double metric disabled by default.UnitMetric TypeValue TypeStabilityGaugeDoubleDeprecated since 1.0.0Deprecation note: This metric will be removed属性string_attr、boolean_attr。该指标用于验证**空单位empty unit**场景对应 metadata.yaml 中的unit: 文档中单位列为空字符串说明 mdatagen 对空单位有正确的空值渲染处理。四、事件Events日志信号的新成员事件板块的开关语法与指标完全对称默认事件关闭方式events: event_name: enabled: false默认关闭事件开启方式events: event_name: enabled: true4.1 default.event默认事件Example event enabled by default.属性NameDescriptionValuesSemantic Conventionstring_attrAttribute with any string value.Any Str-stateInteger attribute with overridden name.Any Int-enum_attrAttribute with a known set of string values.Str:red,green,blue-slice_attrAttribute with a slice value.Any Slice-map_attrAttribute with a map value.Any Map-conditional_int_attrA conditional attribute with an integer valueAny Int-conditional_string_attrA conditional attribute with any string valueAny Str-opt_in_bool_attrAn opt-in attribute with a boolean valueAny Bool-事件的属性表与指标属性表基本相同区别在于没有 Requirement Level 列。在 metadata.yaml 中default.event声明enabled: true并通过warnings.if_enabled_not_set提示该事件很快会改为默认关闭。4.2 default.event.to_be_removed默认事件[DEPRECATED] Example to-be-removed event enabled by default. The event will be removed soon.属性string_attr、state、enum_attr、slice_attr、map_attr。4.3 default.event.to_be_renamed可选事件[DEPRECATED] Example event disabled by default. The event will be renamed soon.属性string_attr、boolean_attr、boolean_attr2、conditional_string_attr。这个事件虽然名字带default.event前缀但实际是默认关闭的enabled: false并提示即将重命名。它出现在 Optional Events 板块说明决定文档归属板块的是enabled默认值而非指标名。五、资源属性Resource Attributes资源属性表是文档中最能体现用户可配置性的部分。每个资源属性都带Enabled列表示该属性默认是否随资源发出NameDescriptionValuesEnabledSemantic ConventionStabilityhost.archThe CPU architecture the host system is running on.Any Strfalsehost.arch-map.resource.attrResource attribute with a map value.Any Maptrue-Developmentoptional.resource.attrExplicitly disabled ResourceAttribute.Any Strfalse-Developmentslice.resource.attrResource attribute with a slice value.Any Slicetrue-Developmentstring.enum.resource.attrResource attribute with a known set of string values.Str:one,twotrue--string.resource.attrResource attribute with any string value.Any Strtrue--string.resource.attr_disable_warningResource attribute with any string value.Any Strtrue--string.resource.attr_remove_warningResource attribute with any string value.Any Strfalse--string.resource.attr_to_be_removedResource attribute with any string value.Any Strtrue--string.resource.disabled_attr_to_be_removedResource attribute with any string value.Any Strfalse--这 10 个资源属性在 metadata.yaml 中有着精细的区分用来覆盖 mdatagen 的各类能力分支值类型string、map、slice、string enum覆盖基本类型与容器类型启用状态enabled: true/false分别对应Enabled: true/false稳定性仅map/slice/optional三个属性声明了stability: development其余不声明文档显示-语义约定host.arch与state见 2.6关联了语义约定引用其余显示-警告warningsattr_disable_warning声明了if_enabled_not_set提示即将默认关闭attr_remove_warning声明了if_configured提示已弃用、即将移除attr_to_be_removed声明了if_enableddisabled_attr_to_be_removed同时为关闭态声明if_enabled警告——mdatagen 会依据用户在配置中是否显式设置enabled来渲染对应的弃用提示。资源属性在生成的 Go 代码中对应ResourceBuilder见 generated_resource.go为每个属性生成SetXxx方法带enabled守卫为枚举值生成独立的SetStringEnumResourceAttrOne/Two方法Emit()时还会应用override_value覆盖值与基于metrics_include/metrics_exclude的过滤器。上述 include/exclude 过滤与 override 的完整用户配置样例可以在 internal/metadata/testdata/config.yaml 的override_set、filter_set_include、filter_set_exclude段中查看。六、内部遥测Internal Telemetry组件自身可观测性内部遥测是**组件自身而非业务数据**上报的指标一般以前缀otelcol_命名。文档声明以下遥测由该组件发出共 5 个6.1 otelcol_batch_size_trigger_sendNumber of times the batch was sent due to a size triggerDeprecated since 1.5.0This metric will be removed in favor of batch_send_trigger_sizeUnitMetric TypeValue TypeMonotonicStability{time}SumInttrueDeprecated since 1.5.0Deprecation note: This metric will be removed in favor of batch_send_trigger_size对应 metadata.yaml 的telemetry.metrics.batch_size_trigger_send同步syncSum 计数器。在 generated_telemetry.go 中它被生成为metric.Int64Counter类型的BatchSizeTriggerSend字段组件代码通过telemetryBuilder.BatchSizeTriggerSend.Add(ctx, 1)直接打点见 factory.go。6.2 otelcol_process_runtime_total_alloc_bytesCumulative bytes allocated for heap objects (see go doc runtime.MemStats.TotalAlloc)UnitMetric TypeValue TypeMonotonicStabilityBySumInttrueStable这是异步async/observableSum指标sum.async: true对应生成代码中的metric.Int64ObservableCounter见 generated_telemetry.go并通过RegisterProcessRuntimeTotalAllocBytesCallback注册回调采集值factory.go 中示范了回调写法恒定上报值 2 用于测试。6.3 otelcol_queue_capacityQueue capacity - sync gauge example.UnitMetric TypeValue TypeStability{item}GaugeIntDevelopment同步 Gauge 示例生成类型为metric.Int64Gauge。6.4 otelcol_queue_lengthThis metric is optional and therefore not initialized in NewTelemetryBuilder. For example this metric only exists if feature A is enabled.UnitMetric TypeValue TypeStability{item}GaugeIntAlpha注意这段 extended_documentation 点明了 mdatagen 的一个重要机制optional: true的遥测指标不会被NewTelemetryBuilder初始化见 metadata.yaml。它对应的QueueLength字段类型为metric.Int64ObservableGauge由RegisterQueueLengthCallback按需注册factory.go 的initOptionalMetric示例。组件只有在特性开关启用等条件下才调用该方法从而避免无条件创建无用仪器。6.5 otelcol_request_durationDuration of requestUnitMetric TypeValue TypeStabilitysHistogramDoubleAlpha直方图Histogram示例生成类型为metric.Float64Histogram其分桶边界在 metadata.yaml 中声明为bucket_boundaries: [1, 10, 100]生成代码中通过metric.WithExplicitBucketBoundaries([]float64{1, 10, 100}...)显式设置见 generated_telemetry.go。七、特性开关Feature Gates文档最后一个板块列出了组件注册的特性开关Feature GateStageDescriptionFrom VersionTo VersionReferencereceiver.sample.featuregate.examplealphaThis is an example feature gate for testing mdatagen code generation.v0.100.0N/ALink该条目直接来自 metadata.yaml 的feature_gates段id、description、stage、from_version、reference_url一一对应。同时mdatagen 还会生成注册代码——generated_feature_gates.go 中通过featuregate.GlobalRegistry().MustRegister(...)将receiver.sample.featuregate.example以StageAlpha级别注册进全局注册表并携带描述、参考 URL 与引入版本。特性开关的详细使用说明见 featuregate/README.md。关于严格校验mdatagen 默认要求每个 gate 的id以status.class.type.前缀命名空间化本例即receiver.sample.且reference_url必须是 GitHub issue 形式。八、从文档反查实现一份 metadata.yaml 的代码生成全景samplereceiver/documentation.md之所以信息密度高是因为它聚合了 metadata.yaml 中几乎全部字段的渲染结果。对照同一目录下的生成产物可以完整还原其代码生成链路文档板块metadata.yaml 源生成代码主要生成产物Default/Optional Metricsmetricsattributesgenerated_metrics.goMetricsBuilder、MetricsInfo、枚举常量、聚合策略常量指标启停配置metrics.*.enabledgenerated_config.goMetricsBuilderConfig及各指标enabled/attributes/aggregation_strategy配置结构Eventseventsgenerated_logs.go事件构建器与配置Resource Attributesresource_attributesgenerated_resource.goResourceBuilder、各SetXxx方法、override/过滤器支持Internal Telemetrytelemetrygenerated_telemetry.goTelemetryBuilder、同步/异步仪器字段、回调注册方法Feature Gatesfeature_gatesgenerated_feature_gates.go特性开关注册调用在运行时组件工厂 factory.go 通过metadata.NewTelemetryBuilder(set.TelemetrySettings)构建遥测构建器、注册异步回调、并在Shutdown中调用telemetryBuilder.Shutdown()注销全部回调——这正是文档中Internal Telemetry一节对应代码的落地方式。组件自身的配置如endpoint、timeout、api_token等则来自 config.schema.json并由 generated_config.go 生成带mapstructure标签的Config结构体与createDefaultConfig()默认值localhost:12345、10s、100。完整配置参考表见同一目录下的 README.md其中还包含组件状态表profiles 已弃用、logs 为 development、traces 为 beta、metrics 为 stable。九、如何生成与使用这类文档如果你在自己的组件中维护metadata.yaml通常按以下步骤接入 mdatagen详见 cmd/mdatagen/README.md在组件包内放置metadata.yaml在doc.go中声明//go:generate mdatagen metadata.yaml运行cd cmd/mdatagen go install .安装工具后执行mdatagen metadata.yaml或直接运行make generate为所有组件批量生成文档与代码修改生成器本身时需同步更新 metadata-schema.yaml 与 metadata.yaml并运行make mdatagen-test保证生成测试如 generated_metrics_test.go全部通过。生成出的documentation.md就是组件面向用户的指标/事件/资源属性/遥测/特性开关权威说明书。用户在部署 Collector 时只需对照该文档在组件的配置节下按metrics、events、resource_attributes键控制每一项的启用状态、属性保留集合与聚合策略即可在默认行为、降基数、兼容性控制之间自由取舍。【免费下载链接】opentelemetry-collectorOpenTelemetry Collector项目地址: https://gitcode.com/GitHub_Trending/op/opentelemetry-collector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考