#Alauda Build of OpenTelemetry v2.1.0

Alauda Build of OpenTelemetry v2.1.0 通过 Alauda Build of OpenTelemetry v2 Operator 0.157.0 和上游 OpenTelemetry Collector 0.158.0 交付。它为部署和管理 OpenTelemetry Collector 提供了一个全面的解决方案，并为 Alauda Container Platform 上的云原生应用提供了简化的 workload 自动插桩能力。

#支持的组件

此版本包含以下 OpenTelemetry Collector 组件：

• Receivers (14)：OTLP、Jaeger、Prometheus、Prometheus Remote Write、Zipkin、Kafka、Host Metrics、Kubernetes Objects、Kubelet Stats、Kubernetes Cluster、Kubernetes Events、Filelog、Journald 和 OTLP JSON File。
• Processors (14)：Batch、Memory Limiter、Resource Detection、Attributes、Resource、Span、Kubernetes Attributes、Filter、Cumulative-to-Delta、Group-by-Attributes、Transform、Tail Sampling、Probabilistic Sampling 和 Metric Start Time。
• Exporters (8)：OTLP gRPC、OTLP HTTP、Debug、Prometheus、Prometheus Remote Write、Kafka、Load Balancing 和 File。
• Connectors (4)：Count、Routing、Forward 和 Spanmetrics。
• Extensions (8)：BearerTokenAuth、OAuth2Client、File Storage、OIDC Auth、Jaeger Remote Sampling、Performance Profiler、Health Check 和 zPages。

#自动插桩支持

Alauda Build of OpenTelemetry v2.1.0 支持六种语言和运行时的自动插桩，无需修改代码即可向应用 pod 注入必要的库和配置：Java、Python、Node.js、.NET、Go 和 Apache HTTP Server。

#部署模式

OpenTelemetry Collector 可以使用 OpenTelemetryCollector 自定义资源按以下模式部署：

• Deployment：用于集中式遥测采集的标准部署模式。这是默认模式。
• StatefulSet：适用于需要持久状态管理的 workload 的部署模式。
• DaemonSet：在每个节点上部署一个 Collector 实例，用于集群范围的遥测采集。
• Sidecar：将 Collector 容器注入应用 pod，以进行 pod 级遥测采集。

#升级说明

此版本从上游 Operator 0.147.0 和 Collector 0.147.0 升级到 Operator 0.157.0 和 Collector 0.158.0。以下上游变更可能会影响现有配置的行为。升级前请仔细检查。

#组件类型名称现在使用 snake_case

上游已将大多数组件类型标识符重命名为 snake_case。旧名称仍可作为已弃用的别名使用，因此现有配置仍能正常工作，但 Collector 会在启动时记录弃用警告，并且上游计划在未来版本中移除这些别名。请将你的 OpenTelemetryCollector 资源更新为新名称。

以下组件类型名称未发生变化：otlp (receiver)、jaeger、zipkin、kafka、prometheus、journald、k8s_cluster、k8s_events、debug、file、batch、memory_limiter、attributes、resource、span、filter、transform、groupbyattrs、tail_sampling、probabilistic_sampler、count、routing、forward、bearertokenauth、oauth2client、file_storage、oidc、jaegerremotesampling、pprof、health_check 和 zpages。

#Collector 内部指标不再携带 service identity 标签

暴露在端口 8888 上的每个内部指标数据点都已移除 service identity 标签。现在这些属性仅出现在 target_info 指标中，这是标准的 Prometheus 和 OpenTelemetry 表示方式。

按这些标签对单个指标进行过滤或分组的仪表板和告警规则，必须重写为基于 job 和 instance 标签与 target_info 进行 join。大多数重写都会碰到两个问题：

• join 的右侧必须限制为监控端点，例如 target_info{endpoint="monitoring"}。不加限制的 target_info 还会选择 Collector 自身的 Prometheus exporter 端口为每个上游应用发布的时间序列，这些时间序列共享同一组 job 和 instance，并会导致查询因 many-to-many matching not allowed 而失败。
• Prometheus 3.x 会将这些属性按其原始的带点名称存储——service.name、service.instance.id 和 service.version——因此在 PromQL 中必须加引号。只有 Prometheus 2.x，或配置为对名称进行转义的 3.x 实例，才会将它们存储为 service_name、service_instance_id 和 service_version。

完整查询请参见 Configuring the Collector Metrics。

#基于 OTTL 的组件默认 error_mode 现在为 ignore

Filter processor、Transform processor 和 Routing connector 之前将顶层 error_mode 的默认值设为 propagate，当 OTTL 语句执行失败时会中止 pipeline。现在默认值改为 ignore，因此失败的语句会被静默跳过，数据会继续通过 pipeline 传递。

如果你依赖 OTTL 失败以 pipeline 错误的形式暴露，请在受影响的组件上显式设置 error_mode: propagate。

#Kafka exporter 需要按 signal 配置 topic 和 encoding

Kafka exporter 顶层的 topic 和 encoding 字段已被移除。请将它们移动到相应的 signal 部分下——traces::topic、metrics::topic、logs::topic，以及对应的 encoding 字段。仍然使用顶层字段的配置将无法启动。

#Prometheus exporter 上的 add_metric_suffixes 已弃用

add_metric_suffixes 设置已弃用，转而使用两个 Prometheus exporter 上的 translation_strategy，但在此版本中这两个 exporter 对它的处理方式不同：

• Prometheus exporter (prometheus)：该设置会被忽略。exporter.prometheusexporter.DisableAddMetricSuffixes feature gate 默认启用，并强制使用 translation_strategy 行为。如果你之前设置了 add_metric_suffixes: false，除非将其替换为 translation_strategy: UnderscoreEscapingWithoutSuffixes，否则后缀会重新出现。
• Prometheus Remote Write exporter (prometheus_remote_write)：该设置仍然有效，但如果设置为 false，启动时会记录弃用警告。请迁移到 translation_strategy: UnderscoreEscapingWithoutSuffixes；当两个字段都设置时，它具有优先级。

#Host Metrics receiver 现在按逻辑 CPU 聚合 CPU 指标

system.cpu.time 和 system.cpu.utilization 上的 cpu 属性现在为可选启用，因此默认情况下这两个指标会按逻辑 CPU 聚合。要恢复按单个逻辑 CPU 输出数据点，请显式启用该属性：

receivers:
  host_metrics:
    scrapers:
      cpu:
        metrics:
          system.cpu.time:
            attributes: [cpu, state]
          system.cpu.utilization:
            attributes: [cpu, state]

此外，system.cpu.logical.count 现在默认启用。设置 system.cpu.logical.count.enabled: false 可将其禁用。

#Kubelet Stats receiver 禁用了已弃用的资源属性

aws.volume.id、fs.type、gce.pd.name、glusterfs.endpoints.name、glusterfs.path 和 partition 资源属性已弃用，并且现在默认禁用。上游计划在未来版本中完全移除它们。如果你的下游 pipeline 仍依赖这些属性，请显式启用它们。

#Sidecar 模式不再创建 Services、Ingresses、NetworkPolicies 或 HPAs

由于 Operator 在 sidecar 模式下不控制 pod 生命周期，因此它不再为使用 spec.mode: sidecar 部署的 Collector 创建 Service、Ingress、NetworkPolicy 或 HorizontalPodAutoscaler 资源。当启用指标时，仍会创建 PodMonitor 资源。请改为通过应用自身的 Service 暴露 sidecar Collector。

#自动创建 RBAC 会校验请求用户的权限

当 Operator 自动为 Collector 生成 ClusterRole 和 ClusterRoleBinding 资源时，如果创建 OpenTelemetryCollector 的用户不具备这些权限，它现在会拒绝该 OpenTelemetryCollector 资源。当 Collector 复用现有 ServiceAccount 时，只会检查该账户缺失的权限。请参见 Creating the Required RBAC Resources Automatically。

#新增 OpenTelemetryCollector 和 Instrumentation 字段

• spec.command 用于覆盖 Collector 容器 entrypoint。
• spec.hostAliases 用于向 Collector 和 Target Allocator pod 的 hosts 文件中添加条目。
• spec.podManagementPolicy 用于控制 StatefulSet 模式下 Collector 的 pod 管理策略。
• status.observedGeneration 和 status.conditions 用于报告 OpenTelemetryCollector 资源的 reconciliation 状态。
• Operator 可以为 Collector 创建 Gateway API HTTPRoute 资源。
• Instrumentation.spec.initContainerSecurityContext 和 Instrumentation.spec.go.securityContext 用于设置自动插桩 init container 和 Go sidecar 的 security context。

请参见 Configuration Options 和 Instrumentation Options。

#其他值得查看的上游变更

以下变更只影响更小范围的配置。如果你的 pipeline 使用了相关组件，请查看这些变更：

• Kubernetes Cluster receiver：作为 entity event attributes 发出的 Kubernetes 资源标签现在会按照 OpenTelemetry semantic conventions 加前缀，例如 k8s.pod.label.<key>。
• Kubernetes Attributes processor：deployment_name_from_replicaset 已弃用；deployment name 的提取现在默认使用 ReplicaSet 名称启发式规则。
• Resource Detection processor：k8snode detector 已弃用，改用 k8s_api。切换时也要重命名配置段——在新 detector 名称下保留旧 key 会静默应用默认值。每个 detector 的 fail_on_missing_metadata 选项已弃用，改用顶层选项。
• Spanmetrics connector：现在会向所有发出的指标添加 collector.instance.id 属性，这会增加时间序列基数。
• Kafka receiver：group_rebalance_strategy 已弃用，改用 group_rebalance_strategies。同时设置两者会导致校验失败。
• Memory Limiter processor：其内部指标已重命名并带有 memory_limiter 前缀，例如 otelcol_processor_memory_limiter_*。当强制 garbage collection 无效时，现在会进行退避，可通过 max_gc_interval_when_soft_limited 和 max_gc_interval_when_hard_limited 调整。
• Batch processor and exporter queue：otelcol_processor_batch_batch_send_size_bytes 和 otelcol_exporter_queue_batch_send_size_bytes 的 histogram bucket 边界已更改为从 128 B 到 16 MiB 的 2 的幂次方。硬编码这些 histogram 的 le 值的仪表板需要更新。