diff --git a/README.md b/README.md index 9358684..f32cf85 100644 --- a/README.md +++ b/README.md @@ -21,34 +21,82 @@ $ yarn install ## OTel 版本更新 -当 Alauda Build of OpenTelemetry 发布新版本时，使用 `hack/update-otel-version.sh` 批量更新 `./docs/en/` 下所有 `.mdx` 文档中出现的旧版本号。 +### OTel 版本号更新 -### 用法 +当 Alauda Build of OpenTelemetry 发布新版本时，使用 `hack/update-otel-version.sh` 批量更新 `./docs/en/` 下所有 `.mdx` 文档中出现的旧版本号。脚本同时适用于 Operator 版本与 Collector 版本。 + +#### 用法 ```bash -./hack/update-otel-version.sh <旧版本> <新版本> +./hack/update-otel-version.sh [选项] <旧版本> <新版本> ``` -版本号格式为 `X.Y.Z-rN`，例如 `0.146.0-r0`。 +选项： + +| 选项 | 说明 | +| ----------------- | -------------------------------------------------- | +| `-n`, `--dry-run` | 只列出将要发生的替换（含文件名与行号），不写入文件 | +| `-h`, `--help` | 显示帮助 | + +版本号格式为 `X.Y.Z`，可带后缀，例如 `0.158.0`、`0.147.0-r0`、`0.156.0-rc.2`。 + +脚本按完整版本号做边界匹配，因此 Operator 版本与 Collector 版本可以独立更新，互不干扰：用 `0.158.0` 替换时不会命中 `0.158.0-r1`，用 `0.156.0` 替换时也不会命中 `0.156.0-rc.2`。 + +#### 操作步骤 + +1. 确认新的 Operator 版本（例如 `0.156.0-rc.2`）与 Collector 版本（例如 `0.158.0`）。 +2. 在仓库根目录先预览要改哪些地方： -### 操作步骤 + ```bash + ./hack/update-otel-version.sh --dry-run 0.147.0-r0 0.156.0-rc.2 + ``` -1. 确认新版本号（例如 `0.147.0-r0`）。 -2. 在仓库根目录执行脚本： +3. 确认无误后分别执行 Operator 与 Collector 版本的替换： ```bash - ./hack/update-otel-version.sh 0.146.0-r0 0.147.0-r0 + # Operator 版本 + ./hack/update-otel-version.sh 0.147.0-r0 0.156.0-rc.2 + # Collector 版本 + ./hack/update-otel-version.sh 0.147.0 0.158.0 ``` 脚本会自动查找 `./docs/en/` 下所有包含旧版本号的 `.mdx` 文件，并将其中的旧版本号全部替换为新版本号；运行结束后会输出被修改的文件列表。 -3. 使用 `git diff` 检查改动是否符合预期： +4. 使用 `git diff` 检查改动是否符合预期： ```bash git diff docs/en/ ``` -4. 本地运行 `yarn dev` 预览相关页面，确认渲染无异常。 -5. 确认无误后提交改动并发起 PR。 +5. 本地运行 `yarn dev` 预览相关页面，确认渲染无异常。 +6. 确认无误后提交改动并发起 PR。 > 提示：若想新增其它需要随版本一起更新的文件类型或目录，可直接编辑 `hack/update-otel-version.sh` 中的 `grep -r --include='*.mdx'` 与 `DOCS_DIR` 配置。 + +### Java 自动插桩镜像版本更新 + +使用 `hack/update-java-autoinstrumentation-version.sh` 批量更新 `./docs/en/` 下所有 `.mdx` 文档中的 `autoinstrumentation-java` 镜像版本。脚本支持官方 GHCR 镜像以及自建或镜像仓库地址。 + +```bash +./hack/update-java-autoinstrumentation-version.sh <旧版本> <新版本> +``` + +例如，将镜像版本从 `2.26.1` 更新为 `2.29.0`： + +```bash +./hack/update-java-autoinstrumentation-version.sh 2.26.1 2.29.0 +``` + +### OTel 新版本内容同步更新 + +让 AI 读取当前版本到新版本更新的内容： + +- https://github.com/open-telemetry/opentelemetry-operator/releases +- https://github.com/open-telemetry/opentelemetry-collector/releases +- https://github.com/open-telemetry/opentelemetry-collector-contrib/releases + +然后分析当前文档是否有需要同步更新的部分，review 后执行更新。 + +### sites.yaml 更新 + +更新 [sites.yaml](./sites.yaml) 中的最新外链站点。 diff --git a/docs/en/about/lifecycle-policy/alauda-build-of-opentelemetry.mdx b/docs/en/about/lifecycle-policy/alauda-build-of-opentelemetry.mdx index 20326cc..f0936b8 100644 --- a/docs/en/about/lifecycle-policy/alauda-build-of-opentelemetry.mdx +++ b/docs/en/about/lifecycle-policy/alauda-build-of-opentelemetry.mdx @@ -11,6 +11,7 @@ Below is the life cycle schedule for released versions of the `Alauda Build of O | Version | Release Date | End of Support | | -------- | ------------- | --------------- | | v2.0.z | 2026-04-21 | 2027-10-21 | +| v2.1.z | 2026-08-21 | 2028-02-21 | ## Release Policy diff --git a/docs/en/about/release-notes/v2-0-0.mdx b/docs/en/about/release-notes/v2-0-0.mdx deleted file mode 100644 index e52eab9..0000000 --- a/docs/en/about/release-notes/v2-0-0.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -weight: 10000 ---- - -# Alauda Build of OpenTelemetry v2.0.0 - -Alauda Build of OpenTelemetry v2.0.0 is the first independently released version of the Alauda Build of OpenTelemetry v2 documentation site. This release is delivered through Alauda Build of OpenTelemetry v2 Operator 0.147.0, aligning with the upstream OpenTelemetry Collector release 0.147.0. It provides a comprehensive solution for deploying and managing the OpenTelemetry Collector, along with streamlined workload instrumentation for cloud-native applications on Alauda Container Platform. - -:::note -Only the features documented on this site are supported. Undocumented features are currently unsupported. If you need assistance with a specific feature, contact Alauda support. -::: - -## Supported Components - -This release includes the following OpenTelemetry Collector components: - -- **[Receivers](../../configuration/collector/receivers.mdx)** (14): OTLP, Jaeger, Prometheus, Prometheus Remote Write, Zipkin, Kafka, Host Metrics, Kubernetes Objects, Kubelet Stats, Kubernetes Cluster, Kubernetes Events, Filelog, Journald, and OTLP JSON File. -- **[Processors](../../configuration/collector/processors.mdx)** (14): Batch, Memory Limiter, Resource Detection, Attributes, Resource, Span, Kubernetes Attributes, Filter, Cumulative-to-Delta, Group-by-Attributes, Transform, Tail Sampling, Probabilistic Sampling, and Metric Start Time. -- **[Exporters](../../configuration/collector/exporters.mdx)** (8): OTLP gRPC, OTLP HTTP, Debug, Prometheus, Prometheus Remote Write, Kafka, Load Balancing, and File. -- **[Connectors](../../configuration/collector/connectors.mdx)** (4): Count, Routing, Forward, and Spanmetrics. -- **[Extensions](../../configuration/collector/extensions.mdx)** (8): BearerTokenAuth, OAuth2Client, File Storage, OIDC Auth, Jaeger Remote Sampling, Performance Profiler, Health Check, and zPages. - -## Auto-instrumentation Support - -Alauda Build of OpenTelemetry v2.0.0 supports [automatic instrumentation](../../configuration/instrumentation/auto-instrumentation.mdx) for six languages and runtimes, injecting the necessary libraries and configuration into application pods without requiring code changes: [Java](../../configuration/instrumentation/java-instrumentation.mdx), [Python](../../configuration/instrumentation/python-instrumentation.mdx), [Node.js](../../configuration/instrumentation/nodejs-instrumentation.mdx), [.NET](../../configuration/instrumentation/dotnet-instrumentation.mdx), [Go](../../configuration/instrumentation/go-instrumentation.mdx), and [Apache HTTP Server](../../configuration/instrumentation/apache-httpd-instrumentation.mdx). - -## Deployment Modes - -The OpenTelemetry Collector can be deployed in the following modes using the `OpenTelemetryCollector` custom resource: - -- **Deployment**: Standard deployment mode for centralized telemetry collection. This is the default mode. -- **StatefulSet**: Deployment mode for workloads that require persistent state management. -- **DaemonSet**: Deploys a Collector instance on every node for cluster-wide telemetry collection. -- **Sidecar**: Injects a Collector container into application pods for pod-level telemetry collection. diff --git a/docs/en/about/release-notes/v2-1-0.mdx b/docs/en/about/release-notes/v2-1-0.mdx new file mode 100644 index 0000000..213ccae --- /dev/null +++ b/docs/en/about/release-notes/v2-1-0.mdx @@ -0,0 +1,147 @@ +--- +weight: 10000 +--- + +# Alauda Build of OpenTelemetry v2.1.0 + +Alauda Build of OpenTelemetry v2.1.0 is delivered through Alauda Build of OpenTelemetry v2 Operator 0.157.0 and the upstream OpenTelemetry Collector 0.158.0. It provides a comprehensive solution for deploying and managing the OpenTelemetry Collector, along with streamlined workload instrumentation for cloud-native applications on Alauda Container Platform. + +:::note +Only the features documented on this site are supported. Undocumented features are currently unsupported. If you need assistance with a specific feature, contact Alauda support. +::: + +## Supported Components + +This release includes the following OpenTelemetry Collector components: + +- **[Receivers](../../configuration/collector/receivers.mdx)** (14): OTLP, Jaeger, Prometheus, Prometheus Remote Write, Zipkin, Kafka, Host Metrics, Kubernetes Objects, Kubelet Stats, Kubernetes Cluster, Kubernetes Events, Filelog, Journald, and OTLP JSON File. +- **[Processors](../../configuration/collector/processors.mdx)** (14): Batch, Memory Limiter, Resource Detection, Attributes, Resource, Span, Kubernetes Attributes, Filter, Cumulative-to-Delta, Group-by-Attributes, Transform, Tail Sampling, Probabilistic Sampling, and Metric Start Time. +- **[Exporters](../../configuration/collector/exporters.mdx)** (8): OTLP gRPC, OTLP HTTP, Debug, Prometheus, Prometheus Remote Write, Kafka, Load Balancing, and File. +- **[Connectors](../../configuration/collector/connectors.mdx)** (4): Count, Routing, Forward, and Spanmetrics. +- **[Extensions](../../configuration/collector/extensions.mdx)** (8): BearerTokenAuth, OAuth2Client, File Storage, OIDC Auth, Jaeger Remote Sampling, Performance Profiler, Health Check, and zPages. + +## Auto-instrumentation Support + +Alauda Build of OpenTelemetry v2.1.0 supports [automatic instrumentation](../../configuration/instrumentation/auto-instrumentation.mdx) for six languages and runtimes, injecting the necessary libraries and configuration into application pods without requiring code changes: [Java](../../configuration/instrumentation/java-instrumentation.mdx), [Python](../../configuration/instrumentation/python-instrumentation.mdx), [Node.js](../../configuration/instrumentation/nodejs-instrumentation.mdx), [.NET](../../configuration/instrumentation/dotnet-instrumentation.mdx), [Go](../../configuration/instrumentation/go-instrumentation.mdx), and [Apache HTTP Server](../../configuration/instrumentation/apache-httpd-instrumentation.mdx). + +## Deployment Modes + +The OpenTelemetry Collector can be deployed in the following modes using the `OpenTelemetryCollector` custom resource: + +- **Deployment**: Standard deployment mode for centralized telemetry collection. This is the default mode. +- **StatefulSet**: Deployment mode for workloads that require persistent state management. +- **DaemonSet**: Deploys a Collector instance on every node for cluster-wide telemetry collection. +- **Sidecar**: Injects a Collector container into application pods for pod-level telemetry collection. + +## Upgrade Notes + +This release moves from upstream Operator 0.147.0 and Collector 0.147.0 to Operator 0.157.0 and Collector 0.158.0. The following upstream changes can alter the behavior of an existing configuration. Review them before upgrading. + +### Component type names now use snake_case \{#snake-case-names} + +Upstream renamed most component type identifiers to snake_case. The previous names remain available as deprecated aliases, so existing configurations continue to work, but the Collector logs a deprecation warning on startup and upstream intends to remove the aliases in a future release. Update your `OpenTelemetryCollector` resources to the new names. + +| Component | Previous type name | Current type name | +| :-------- | :----------------- | :---------------- | +| Kubernetes Attributes processor | `k8sattributes` | `k8s_attributes` | +| Resource Detection processor | `resourcedetection` | `resource_detection` | +| Cumulative-to-Delta processor | `cumulativetodelta` | `cumulative_to_delta` | +| Metric Start Time processor | `metricstarttime` | `metric_start_time` | +| Host Metrics receiver | `hostmetrics` | `host_metrics` | +| Filelog receiver | `filelog` | `file_log` | +| Kubernetes Objects receiver | `k8sobjects` | `k8s_objects` | +| Kubelet Stats receiver | `kubeletstats` | `kubelet_stats` | +| OTLP JSON File receiver | `otlpjsonfile` | `otlp_json_file` | +| Prometheus Remote Write receiver | `prometheusremotewrite` | `prometheus_remote_write` | +| OTLP gRPC exporter | `otlp` | `otlp_grpc` | +| OTLP HTTP exporter | `otlphttp` | `otlp_http` | +| Prometheus Remote Write exporter | `prometheusremotewrite` | `prometheus_remote_write` | +| Load Balancing exporter | `loadbalancing` | `load_balancing` | +| Spanmetrics connector | `spanmetrics` | `span_metrics` | + +:::note The two OTLP exporters are renamed, the OTLP receiver is not +`otlp` remains the correct type name for the **receiver**, which already matched the convention. Only the **exporters** are renamed, so that the transport each one uses is explicit in its name. A configuration that keeps `otlp` under `receivers` and uses `otlp_grpc` under `exporters` is correct and produces no warning. +::: + +The following component type names are unchanged: `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`, and `zpages`. + +### Collector internal metrics no longer carry service identity labels + +The service identity labels have been removed from every internal metric data point exposed on port `8888`. These attributes are now present only in the `target_info` metric, which is the conventional Prometheus and OpenTelemetry representation. + +Dashboards and alerting rules that filter or group by these labels on individual metrics must be rewritten to join against `target_info` on the `job` and `instance` labels. Two points catch out most rewrites: + +- The right-hand side of the join must be restricted to the monitoring endpoint, as in `target_info{endpoint="monitoring"}`. An unrestricted `target_info` also selects the series that the Collector's own Prometheus exporter port publishes for each upstream application, which share a single `job` and `instance` pair and make the query fail with `many-to-many matching not allowed`. +- Prometheus 3.x stores the attributes under their original dotted names — `service.name`, `service.instance.id`, and `service.version` — which must be quoted in PromQL. Only Prometheus 2.x, or a 3.x instance configured to escape names, stores them as `service_name`, `service_instance_id`, and `service_version`. + +For the full queries, see [Configuring the Collector Metrics](../../configuration/collector-metrics/index.mdx#identifying-the-collector). + +### The default `error_mode` for OTTL-based components is now `ignore` + +The Filter processor, the Transform processor, and the Routing connector previously defaulted their top-level `error_mode` to `propagate`, which aborted the pipeline when an OTTL statement failed. The default is now `ignore`, so failing statements are skipped silently and the data continues through the pipeline. + +If you rely on OTTL failures surfacing as pipeline errors, set `error_mode: propagate` explicitly on the affected components. + +### The Kafka exporter requires per-signal `topic` and `encoding` + +The top-level `topic` and `encoding` fields have been removed from the Kafka exporter. Move them under the corresponding signal section — `traces::topic`, `metrics::topic`, `logs::topic`, and the matching `encoding` fields. A configuration that still uses the top-level fields fails to start. + +### `add_metric_suffixes` is deprecated on the Prometheus exporters + +The `add_metric_suffixes` setting is deprecated in favor of `translation_strategy` on both Prometheus exporters, but the two exporters treat it differently in this release: + +- **Prometheus exporter** (`prometheus`): the setting is ignored. The `exporter.prometheusexporter.DisableAddMetricSuffixes` feature gate is enabled by default and forces the `translation_strategy` behavior. If you previously set `add_metric_suffixes: false`, the suffixes reappear unless you replace it with `translation_strategy: UnderscoreEscapingWithoutSuffixes`. +- **Prometheus Remote Write exporter** (`prometheus_remote_write`): the setting is still honored, but setting it to `false` logs a deprecation warning on startup. Migrate to `translation_strategy: UnderscoreEscapingWithoutSuffixes`, which takes precedence when both fields are set. + +### The Host Metrics receiver aggregates CPU metrics across logical CPUs + +The `cpu` attribute on `system.cpu.time` and `system.cpu.utilization` is now opt-in, so both metrics are aggregated across logical CPUs by default. To restore per-logical-CPU data points, enable the attribute explicitly: + +```yaml +receivers: + host_metrics: + scrapers: + cpu: + metrics: + system.cpu.time: + attributes: [cpu, state] + system.cpu.utilization: + attributes: [cpu, state] +``` + +In addition, `system.cpu.logical.count` is now enabled by default. Set `system.cpu.logical.count.enabled: false` to disable it. + +### The Kubelet Stats receiver disables deprecated resource attributes + +The `aws.volume.id`, `fs.type`, `gce.pd.name`, `glusterfs.endpoints.name`, `glusterfs.path`, and `partition` resource attributes are deprecated and are now disabled by default. Upstream plans to remove them entirely in a future release. Enable them explicitly if your downstream pipelines still depend on them. + +### Sidecar mode no longer provisions Services, Ingresses, NetworkPolicies, or HPAs + +Because the Operator does not control the pod lifecycle in sidecar mode, it no longer creates `Service`, `Ingress`, `NetworkPolicy`, or `HorizontalPodAutoscaler` resources for Collectors deployed with `spec.mode: sidecar`. `PodMonitor` resources are still created when metrics are enabled. Expose the sidecar Collector through the application's own `Service` instead. + +### Automatic RBAC creation validates the requesting user's permissions + +When the Operator generates `ClusterRole` and `ClusterRoleBinding` resources for a Collector automatically, it now rejects the `OpenTelemetryCollector` resource if the user creating it does not hold those permissions. When the Collector reuses an existing `ServiceAccount`, only the permissions missing from that account are checked. See [Creating the Required RBAC Resources Automatically](../../installing/rbac-resources.mdx). + +### New `OpenTelemetryCollector` and `Instrumentation` fields + +- `spec.command` overrides the Collector container entrypoint. +- `spec.hostAliases` adds entries to the pod `hosts` file for Collector and Target Allocator pods. +- `spec.podManagementPolicy` controls the pod management policy of StatefulSet-mode Collectors. +- `status.observedGeneration` and `status.conditions` report reconciliation state on `OpenTelemetryCollector` resources. +- The Operator can create Gateway API `HTTPRoute` resources for a Collector. +- `Instrumentation.spec.initContainerSecurityContext` and `Instrumentation.spec.go.securityContext` set the security context of the auto-instrumentation init containers and the Go sidecar. + +See [Configuration Options](../../configuration/collector/configuration-options.mdx) and [Instrumentation Options](../../configuration/instrumentation/instrumentation-options.mdx). + +### Other upstream changes worth reviewing + +The following changes affect narrower configurations. Review them if your pipelines use the components involved: + +- **Kubernetes Cluster receiver**: labels on Kubernetes resources emitted as entity event attributes are now prefixed per OpenTelemetry semantic conventions, for example `k8s.pod.label.`. +- **Kubernetes Attributes processor**: `deployment_name_from_replicaset` is deprecated; deployment name extraction now defaults to the ReplicaSet name heuristic. +- **Resource Detection processor**: the `k8snode` detector is deprecated in favor of `k8s_api`. When switching, rename the configuration section as well — keeping the old key under the new detector name silently applies defaults. The per-detector `fail_on_missing_metadata` option is deprecated in favor of the top-level one. +- **Spanmetrics connector**: a `collector.instance.id` attribute is now added to all emitted metrics, which increases series cardinality. +- **Kafka receiver**: `group_rebalance_strategy` is deprecated in favor of `group_rebalance_strategies`. Setting both fails validation. +- **Memory Limiter processor**: its internal metrics were renamed to carry a `memory_limiter` prefix, for example `otelcol_processor_memory_limiter_*`. Forced garbage collection now backs off when ineffective, tunable through `max_gc_interval_when_soft_limited` and `max_gc_interval_when_hard_limited`. +- **Batch processor and exporter queue**: the histogram bucket boundaries of `otelcol_processor_batch_batch_send_size_bytes` and `otelcol_exporter_queue_batch_send_size_bytes` changed to powers of two spanning 128 B to 16 MiB. Dashboards that hard-code `le` values for these histograms need updating. diff --git a/docs/en/configuration/collector-metrics/index.mdx b/docs/en/configuration/collector-metrics/index.mdx index 30447e7..d6a77cb 100644 --- a/docs/en/configuration/collector-metrics/index.mdx +++ b/docs/en/configuration/collector-metrics/index.mdx @@ -49,9 +49,6 @@ spec: prometheus: host: 0.0.0.0 port: 8888 - without_scope_info: true - without_type_suffix: true - without_units: true ``` @@ -69,3 +66,77 @@ You can use the Prometheus web console to verify successful configuration: 2. Navigate to **Status** → **Targets**. 3. Check that the `ServiceMonitors` or `PodMonitors` in the `-collector` format have the **Up** status. + +## Identifying the Collector that produced a metric \{#identifying-the-collector} + +The Collector no longer stamps `service_name`, `service_instance_id`, and `service_version` onto every internal metric series. These attributes are exposed only through the `target_info` metric, which is the conventional Prometheus and OpenTelemetry representation of resource identity. + +To attribute a metric to a specific Collector, join the metric against `target_info` on the shared `job` and `instance` labels: + +```text +otelcol_receiver_accepted_spans + * on (job, instance) group_left ("service.name", "service.version") + target_info{endpoint="monitoring"} +``` + +Two details of this query are not optional. Omitting either one produces a broken result, so both are explained below. + +### Always restrict `target_info` to the monitoring endpoint \{#scope-target-info} + +:::warning +Writing `target_info` on the right-hand side without a label selector makes the query fail with `many-to-many matching not allowed`. +::: + +`target_info` is not specific to the Collector's internal telemetry. Every scrape target that carries OpenTelemetry resource attributes publishes a metric of that name, and the Collector's own Prometheus exporter port (`8889` in the [Configuration Example](../collector/configuration-options.mdx#configuration-example)) publishes **one `target_info` series per upstream application** it receives data from. All of those series come from a single scrape target, so they share one `job` and `instance` pair: + +```text +found duplicate series for the match group {instance="10.3.6.73:8889", job="my-collector"} +on the right hand-side of the operation: [...]; +many-to-many matching not allowed: matching labels must be unique on one side +``` + +Prometheus checks that the `group_left` right-hand side is unique **before** it matches anything against the left-hand side. The `otelcol_*` metrics exist only on port `8888` and never collide with these series, but the query still fails, because the duplicates are present in the right-hand side vector at all. + +Restricting the selector to the monitoring endpoint removes them. The Operator names the internal telemetry port `monitoring`, which Prometheus Operator copies into the `endpoint` label, so `target_info{endpoint="monitoring"}` selects exactly one series per Collector. If your Prometheus does not set an `endpoint` label, match on the job name of the monitoring service instead, which the Operator derives from the Collector name: + +```text +target_info{job=~".*-collector-monitoring"} +``` + +### Confirm how your Prometheus spells the attribute names \{#target-info-label-names} + +The Collector exposes the resource attributes under their original OpenTelemetry names — `service.name`, `service.instance.id`, and `service.version`. Whether the dots survive into storage depends on the Prometheus version: + +| Prometheus | Stored label names | PromQL | +| :--------- | :----------------- | :----- | +| 3.x (UTF-8 names negotiated during the scrape) | `service.name`, `service.instance.id`, `service.version` | Must be quoted: `group_left ("service.name")` | +| 2.x, or 3.x configured to escape names | `service_name`, `service_instance_id`, `service_version` | Written bare: `group_left (service_name)` | + +:::warning +A `group_left` list that names labels which do not exist is **not** an error. The query returns results, and the identity attributes are silently absent from every series. If a join appears to succeed but adds no `service.name`, check the spelling before looking anywhere else. +::: + +Query `target_info{endpoint="monitoring"}` on its own and read the label names off the result before writing the join. The examples on this page use the dotted names, which is what Alauda Container Platform stores. + +## Reusing the join across dashboards + +If rewriting every query is not practical, define a recording rule that performs the join once and query the recorded series instead: + +```yaml +groups: + - name: otelcol-internal-metrics + rules: + - record: otelcol:receiver_accepted_spans:with_identity + expr: | + otelcol_receiver_accepted_spans + * on (job, instance) group_left ("service.name", "service.version") + target_info{endpoint="monitoring"} +``` + +:::note +The identity attributes cannot be restored on the scrape side with `metric_relabel_configs`. Relabeling rules are evaluated per sample against the labels that sample already carries, so they cannot copy `service.name` from the `target_info` series onto the `otelcol_*` series. The join must happen at query time or in a recording rule. +::: + +:::warning +If you are upgrading from an earlier release, any dashboard or alerting rule that filters or groups by `service_name`, `service_instance_id`, or `service_version` directly on an `otelcol_*` metric silently stops matching. Rewrite those queries to join against `target_info` as shown above. +::: diff --git a/docs/en/configuration/collector/configuration-options.mdx b/docs/en/configuration/collector/configuration-options.mdx index ebd60c6..20d1870 100644 --- a/docs/en/configuration/collector/configuration-options.mdx +++ b/docs/en/configuration/collector/configuration-options.mdx @@ -20,7 +20,7 @@ You can define multiple instances of each component type within a custom resourc As a best practice, only enable the components you actually need. This reduces resource consumption and simplifies troubleshooting. ::: -## Configuration Example +## Configuration Example \{#configuration-example} The following example demonstrates a basic OpenTelemetry Collector configuration with OTLP receivers and multiple exporters: @@ -44,7 +44,7 @@ spec: http: {} processors: {} exporters: - otlp: + otlp_grpc: # [!code callout] endpoint: otel-collector-headless.tracing-system.svc:4317 tls: ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/service-ca.crt" @@ -57,7 +57,7 @@ spec: traces: receivers: [otlp] processors: [] - exporters: [otlp] + exporters: [otlp_grpc] metrics: receivers: [otlp] processors: [] @@ -65,9 +65,28 @@ spec: ``` -1. Components defined in the configuration but not referenced in the `service.pipelines` section remain inactive. A component must be added to at least one pipeline to function. +1. The OTLP **exporter** is named `otlp_grpc`, while the OTLP **receiver** above keeps the name `otlp`. See [Component type names](#component-type-names). +2. Components defined in the configuration but not referenced in the `service.pipelines` section remain inactive. A component must be added to at least one pipeline to function. +## Component type names \{#component-type-names} + +Upstream renamed most component type identifiers to snake_case, and renamed the two OTLP exporters so that the transport is explicit in the name: + +| Component | Deprecated type name | Current type name | +| :-------- | :------------------- | :---------------- | +| OTLP gRPC exporter | `otlp` | `otlp_grpc` | +| OTLP HTTP exporter | `otlphttp` | `otlp_http` | + +The deprecated names still work, so existing configurations keep running, but the Collector logs a warning for each affected component instance and upstream intends to remove the aliases in a future release: + +```text +warn builders/builders.go:40 "otlp" alias is deprecated; use "otlp_grpc" instead + {"otelcol.component.id": "otlp/traces", "otelcol.component.kind": "exporter", "otelcol.signal": "traces"} +``` + +For the full list of renamed components, see the [v2.1.0 Release Notes](../../about/release-notes/v2-1-0.mdx#snake-case-names). + ## Configuration Parameters The following table describes the main configuration parameters used by the Operator to define the OpenTelemetry Collector: @@ -75,12 +94,14 @@ The following table describes the main configuration parameters used by the Oper | Parameter | Description | Values | Default | |-----------|-------------|-------------------|---------| | `receivers` | Defines how data enters the Collector. At least one receiver must be enabled in a pipeline for valid configuration. | otlp, jaeger, prometheus, zipkin, kafka | None | -| `processors` | Defines data transformation operations applied between receiving and exporting. Processors are optional. | batch, memory_limiter, resourcedetection, attributes, span, k8sattributes, filter, routing | None | -| `exporters` | Defines destinations for processed data. At least one exporter must be enabled in a pipeline for valid configuration. | otlp, otlphttp, debug, prometheus, kafka | None | -| `connectors` | Defines components that join pipeline pairs by consuming data as exporters and emitting data as receivers. | spanmetrics, count, routing, forward | None | -| `extensions` | Defines optional components for auxiliary tasks that don't involve telemetry data processing. | bearertokenauth, oauth2client, pprof, health_check, memory_ballast, zpages | None | +| `processors` | Defines data transformation operations applied between receiving and exporting. Processors are optional. | batch, memory_limiter, resource_detection, attributes, span, k8s_attributes, filter | None | +| `exporters` | Defines destinations for processed data. At least one exporter must be enabled in a pipeline for valid configuration. | otlp_grpc, otlp_http, debug, prometheus, kafka | None | +| `connectors` | Defines components that join pipeline pairs by consuming data as exporters and emitting data as receivers. | span_metrics, count, routing, forward | None | +| `extensions` | Defines optional components for auxiliary tasks that don't involve telemetry data processing. | bearertokenauth, oauth2client, pprof, health_check, zpages | None | | `service.pipelines` | Enables components by adding them to pipelines. Components must be listed here to become active. | N/A | None | +The **Values** column lists representative components only. For the full set of supported components and their current type names, see [Receivers](./receivers.mdx), [Processors](./processors.mdx), [Exporters](./exporters.mdx), [Connectors](./connectors.mdx), and [Extensions](./extensions.mdx). + ## Pipeline Configuration Pipelines are defined under `service.pipelines` and specify the flow of telemetry data through the Collector. Each pipeline type (traces, metrics, logs) can have its own set of receivers, processors, and exporters. @@ -93,7 +114,7 @@ service: traces: receivers: [otlp, jaeger] processors: [batch, memory_limiter] - exporters: [otlp, debug] + exporters: [otlp_grpc, debug] metrics: receivers: [otlp, prometheus] processors: [batch] @@ -101,7 +122,95 @@ service: logs: receivers: [otlp] processors: [batch] - exporters: [otlp] + exporters: [otlp_grpc] ``` Each pipeline independently processes its telemetry type, allowing you to configure different processing logic for traces, metrics, and logs based on your observability requirements. + +## Collector Resource Options + +The fields above live under `spec.config` and configure the Collector process itself. The `OpenTelemetryCollector` custom resource also exposes fields that control how the Operator deploys the Collector workload. + +| Field | Description | +| :---- | :---------- | +| `spec.command` | Overrides the entrypoint of the Collector container, with the same semantics as `Pod.spec.containers[].command`. Accepts a string array. When omitted, the image `ENTRYPOINT` is used. | +| `spec.hostAliases` | Adds entries to the pod `hosts` file, mirroring `Pod.spec.hostAliases`. Useful when a Collector must resolve a backend hostname that cluster DNS does not serve. | +| `spec.podManagementPolicy` | Sets the pod creation and termination order of the underlying StatefulSet. Applies only when `spec.mode` is `statefulset`. Defaults to `Parallel`. | +| `spec.sessionAffinity` | Sets the session affinity of every Service the Operator creates for the Collector, mirroring `Service.spec.sessionAffinity`. Accepts `ClientIP`, which routes all requests from the same client IP to the same Collector replica, or `None`. Defaults to `None`. Has no effect in `sidecar` mode, which creates no Service. | +| `spec.sessionAffinityConfig.clientIP.timeoutSeconds` | Sets how long a `ClientIP` affinity entry is retained, mirroring `Service.spec.sessionAffinityConfig`. Defaults to `10800` (3 hours). Only read when `spec.sessionAffinity` is `ClientIP`. | +| `spec.observability.metrics.enableMetrics` | Instructs the Operator to create `ServiceMonitor` or `PodMonitor` resources for the Collector. See [Configuring the Collector Metrics](../collector-metrics/index.mdx). | +| `spec.observability.metrics.disablePrometheusAnnotations` | Prevents the Operator from stamping the default `prometheus.io/scrape`, `prometheus.io/port`, and `prometheus.io/path` annotations onto the pod template. Setting this to `true` on an existing Collector also removes annotations the Operator previously added, while leaving annotations you set yourself untouched. | + +**Example:** + +```yaml +apiVersion: opentelemetry.io/v1beta1 +kind: OpenTelemetryCollector +metadata: + name: otel +spec: + mode: statefulset + replicas: 2 + podManagementPolicy: Parallel # [!code callout] + hostAliases: # [!code callout] + - ip: "10.0.0.10" + hostnames: + - "backend.internal" + sessionAffinity: ClientIP # [!code callout] + sessionAffinityConfig: + clientIP: + timeoutSeconds: 10800 + config: + receivers: + otlp: + protocols: + grpc: {} + exporters: + debug: {} + service: + pipelines: + traces: + receivers: [otlp] + exporters: [debug] +``` + + +1. Only meaningful in `statefulset` mode. Leave it unset for `deployment`, `daemonset`, and `sidecar` mode. +2. Each entry maps one IP address to one or more hostnames inside the Collector pod. +3. Pins each client IP to one Collector replica. `sessionAffinityConfig` is optional; omit it to keep the default 3-hour timeout. + + +### Ingress and Gateway API + +The Operator can expose the Collector's receiver ports through either an `Ingress` resource or a Gateway API `HTTPRoute` resource. Both are available in `deployment`, `daemonset`, and `statefulset` mode only. + +- `spec.ingress` creates an `Ingress` resource. Configure the hostname, annotations, and TLS settings under this field. +- `spec.httpRoute` creates a Gateway API `HTTPRoute` resource. Choose this when your cluster routes north-south traffic through a Gateway API implementation rather than an Ingress controller. + +The following example attaches the Collector to an existing `Gateway`: + +```yaml +spec: + httpRoute: + enabled: true # [!code callout] + gateway: my-gateway # [!code callout] + gatewayNamespace: gateway-system # [!code callout] + hostnames: # [!code callout] + - otel.example.com +``` + + +1. Required. Enables the `HTTPRoute` configuration. +2. Required. The name of the `Gateway` resource to attach the route to. +3. The namespace of the `Gateway` resource. Defaults to the Collector's own namespace. +4. Hostnames matched by the route. When empty, the route matches any hostname. + + +### Collector Status + +The `OpenTelemetryCollector` resource reports reconciliation state through `status.observedGeneration` and `status.conditions`. Automation that waits for a Collector to converge should compare `status.observedGeneration` against `metadata.generation` before reading conditions, so that it does not act on a status produced for an earlier revision of the resource. + +```bash +kubectl get opentelemetrycollector -n \ + -o jsonpath='{.metadata.generation} {.status.observedGeneration}{"\n"}' +``` diff --git a/docs/en/configuration/collector/connectors.mdx b/docs/en/configuration/collector/connectors.mdx index 09072e5..0e005aa 100644 --- a/docs/en/configuration/collector/connectors.mdx +++ b/docs/en/configuration/collector/connectors.mdx @@ -16,6 +16,10 @@ The Count Connector produces count-based metrics by tallying trace spans, span e The Routing Connector directs logs, metrics, and traces to designated pipelines based on resource attribute values and routing rules expressed as OpenTelemetry Transformation Language (OTTL) statements. +:::warning +The connector's `error_mode` defaults to `ignore`. When a routing condition fails to evaluate, the error is swallowed and the data falls through to the default pipeline instead of the failure being propagated. Set `error_mode: propagate` explicitly if routing errors must surface as pipeline errors. +::: + **Reference**: [Routing Connector Documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/connector/routingconnector/README.md) ## Forward Connector diff --git a/docs/en/configuration/collector/deployment-modes.mdx b/docs/en/configuration/collector/deployment-modes.mdx index 0ebd6e4..279e56a 100644 --- a/docs/en/configuration/collector/deployment-modes.mdx +++ b/docs/en/configuration/collector/deployment-modes.mdx @@ -26,6 +26,10 @@ The Sidecar deployment mode injects the Collector directly into application pods 2. **Localhost telemetry forwarding**: When applications send telemetry data via `localhost`, the sidecar Collector can receive this data and forward it to external services through encrypted and authenticated connections. +:::note +In sidecar mode the Operator does not own the pod lifecycle, so it does **not** create `Service`, `Ingress`, `NetworkPolicy`, or `HorizontalPodAutoscaler` resources for the Collector. Expose the sidecar through the application's own `Service` when its ports need to be reachable from outside the pod. `PodMonitor` resources are still created when `spec.observability.metrics.enableMetrics` is enabled. +::: + ### Sidecar Injection Configuration :::note diff --git a/docs/en/configuration/collector/exporters.mdx b/docs/en/configuration/collector/exporters.mdx index 357c288..74d262f 100644 --- a/docs/en/configuration/collector/exporters.mdx +++ b/docs/en/configuration/collector/exporters.mdx @@ -8,13 +8,17 @@ Exporters deliver telemetry data to one or more backend destinations. They can o ## OTLP gRPC Exporter -The OTLP gRPC Exporter sends traces and metrics over the OpenTelemetry Protocol (OTLP) using gRPC transport. +The OTLP gRPC Exporter sends traces and metrics over the OpenTelemetry Protocol (OTLP) using gRPC transport. Its type name is `otlp_grpc`. The former name `otlp` still works as a deprecated alias, but it is reported at startup and will be removed upstream. -**Reference**: [OTLP Exporter Documentation](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README.md) +**Reference**: [OTLP gRPC Exporter Documentation](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlpexporter/README.md) + +:::note +The rename affects the exporter only. Under `receivers`, the OTLP receiver keeps the type name `otlp`. See [Component type names](./configuration-options.mdx#component-type-names). +::: ## OTLP HTTP Exporter -The OTLP HTTP Exporter sends traces and metrics over the OpenTelemetry Protocol (OTLP) using HTTP transport. +The OTLP HTTP Exporter sends traces and metrics over the OpenTelemetry Protocol (OTLP) using HTTP transport. Its type name is `otlp_http`. The former name `otlphttp` still works as a deprecated alias. **Reference**: [OTLP HTTP Exporter Documentation](https://github.com/open-telemetry/opentelemetry-collector/blob/main/exporter/otlphttpexporter/README.md) diff --git a/docs/en/configuration/collector/processors.mdx b/docs/en/configuration/collector/processors.mdx index 33cf7cd..045efe9 100644 --- a/docs/en/configuration/collector/processors.mdx +++ b/docs/en/configuration/collector/processors.mdx @@ -6,6 +6,10 @@ weight: 60 Processors operate on telemetry data after it is received and before it is exported. They are optional and disabled by default. Each processor must be explicitly enabled per data source, and not every processor supports every signal type. Multiple processors can be chained for a given data source, and the order in which they execute is significant. +:::warning +Components that evaluate the OpenTelemetry Transformation Language (OTTL) — the Filter processor and the Transform processor — default their top-level `error_mode` to `ignore`. A statement that fails at runtime is skipped and the data continues through the pipeline instead of the batch being dropped. Set `error_mode: propagate` explicitly if you need OTTL failures to surface as pipeline errors. +::: + ## Batch Processor The Batch Processor groups traces and metrics into batches, reducing the number of outbound connections required to transmit telemetry data. diff --git a/docs/en/configuration/forwarding-telemetry-data/forwarding-traces-to-jaeger.mdx b/docs/en/configuration/forwarding-telemetry-data/forwarding-traces-to-jaeger.mdx index ac565ed..80189f3 100644 --- a/docs/en/configuration/forwarding-telemetry-data/forwarding-traces-to-jaeger.mdx +++ b/docs/en/configuration/forwarding-telemetry-data/forwarding-traces-to-jaeger.mdx @@ -44,13 +44,13 @@ To send traces to a Jaeger instance, deploy an OpenTelemetry Collector in `deplo zipkin: {} processors: batch: {} - k8sattributes: {} + k8s_attributes: {} memory_limiter: check_interval: 1s limit_percentage: 80 spike_limit_percentage: 20 exporters: - otlp/traces: + otlp_grpc/traces: # [!code callout] endpoint: "jaeger-collector.jaeger-system.svc.cluster.local:4317" # [!code callout] tls: insecure: true @@ -58,15 +58,16 @@ To send traces to a Jaeger instance, deploy an OpenTelemetry Collector in `deplo pipelines: traces: receivers: [jaeger, otlp, zipkin] # [!code callout] - processors: [memory_limiter, k8sattributes, batch] - exporters: [otlp/traces] + processors: [memory_limiter, k8s_attributes, batch] + exporters: [otlp_grpc/traces] EOF ``` 1. The namespace determines where the Collector resources are created. - 2. The exporter endpoint must point to the Jaeger collector service. Replace `jaeger-collector.jaeger-system.svc.cluster.local:4317` with the actual service of your Jaeger deployment. - 3. This trace pipeline accepts Jaeger, OTLP, and Zipkin traffic. Configure your instrumented applications to send traces by using one of these receiver protocols. + 2. The OTLP gRPC exporter is named `otlp_grpc`. The former name `otlp` still works but is deprecated. Note that the OTLP **receiver** keeps the name `otlp`; see [Component type names](../collector/configuration-options.mdx#component-type-names). + 3. The exporter endpoint must point to the Jaeger collector service. Replace `jaeger-collector.jaeger-system.svc.cluster.local:4317` with the actual service of your Jaeger deployment. + 4. This trace pipeline accepts Jaeger, OTLP, and Zipkin traffic. Configure your instrumented applications to send traces by using one of these receiver protocols. After the Collector is running, instrumented applications can send trace data to the Collector service endpoint, and the Collector forwards the traces to Jaeger. diff --git a/docs/en/configuration/instrumentation/instrumentation-options.mdx b/docs/en/configuration/instrumentation/instrumentation-options.mdx index 73c77e9..0a05a74 100644 --- a/docs/en/configuration/instrumentation/instrumentation-options.mdx +++ b/docs/en/configuration/instrumentation/instrumentation-options.mdx @@ -66,6 +66,7 @@ The following table describes the parameters that can be configured in the `Inst | `propagators` | Inter-process context propagation configuration. | `tracecontext`, `baggage`, `b3`, `b3multi`, `jaeger`, `ottrace`, `none` | | `resource` | Resource attributes configuration for telemetry identification. | | | `sampler` | Sampling configuration to control telemetry data volume. | | +| `initContainerSecurityContext` | Security context applied to the auto-instrumentation init containers. | | | `apacheHttpd` | Apache HTTP Server instrumentation settings. | | | `dotnet` | .NET instrumentation settings. | | | `go` | Go instrumentation settings. | | @@ -167,6 +168,47 @@ spec: memory: 64Mi ``` +## Security Context Configuration + +By default, the auto-instrumentation init containers inherit the security context of the first application container being instrumented, and the Go sidecar keeps the settings that eBPF requires (`privileged: true` and `runAsUser: 0`). In clusters that enforce restricted Pod Security Admission, inheriting a context is not always sufficient — you may need to declare capabilities explicitly. + +Use `spec.initContainerSecurityContext` to set the security context of the init containers injected for Java, Node.js, Python, .NET, Apache HTTP Server, and Nginx: + +```yaml +spec: + initContainerSecurityContext: # [!code callout] + allowPrivilegeEscalation: false + runAsNonRoot: true + runAsUser: 1000 + capabilities: + drop: + - ALL + seccompProfile: + type: RuntimeDefault +``` + + +1. Applies to every language init container. When unset, each init container inherits the security context of the application container it instruments. + + +Use `spec.go.securityContext` to override the defaults of the Go instrumentation sidecar: + +```yaml +spec: + go: + securityContext: # [!code callout] + privileged: true + runAsUser: 0 +``` + + +1. Overrides the Go sidecar defaults. The Go auto-instrumentation relies on eBPF, so removing the elevated privileges shown here generally prevents it from attaching to the application process. + + +:::warning +Only override `spec.go.securityContext` if you know the resulting context still satisfies the eBPF requirements of the Go instrumentation. Leaving the field unset keeps the defaults that the Go sidecar needs to attach to the application process. +::: + ## Environment Variable Injection The Instrumentation CR allows you to inject additional environment variables into instrumented containers: diff --git a/docs/en/configuration/instrumentation/java-instrumentation.mdx b/docs/en/configuration/instrumentation/java-instrumentation.mdx index 9276887..fe3004e 100644 --- a/docs/en/configuration/instrumentation/java-instrumentation.mdx +++ b/docs/en/configuration/instrumentation/java-instrumentation.mdx @@ -155,7 +155,7 @@ metadata: namespace: java-development spec: java: - image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1 # [!code callout] + image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.30.0 # [!code callout] env: - name: OTEL_JAVAAGENT_DEBUG value: "false" diff --git a/docs/en/configuration/monitoring-stack-metrics/index.mdx b/docs/en/configuration/monitoring-stack-metrics/index.mdx index a6f0501..b6d1cd6 100644 --- a/docs/en/configuration/monitoring-stack-metrics/index.mdx +++ b/docs/en/configuration/monitoring-stack-metrics/index.mdx @@ -46,9 +46,6 @@ spec: prometheus: host: 0.0.0.0 port: 8888 - without_scope_info: true - without_type_suffix: true - without_units: true pipelines: metrics: exporters: [prometheus] @@ -66,6 +63,10 @@ Turning on `enableMetrics` results in two separate `ServiceMonitor` resources be - A `ServiceMonitor` targeting the `-collector` service, which collects metrics published by any Prometheus exporter configured in the pipeline. ::: +:::warning +The Collector's internal metrics no longer carry `service_name`, `service_instance_id`, or `service_version` labels; that identity is published through the `target_info` metric instead. Queries that group or filter on those labels must join against `target_info`. See [Identifying the Collector that produced a metric](../collector-metrics/index.mdx#identifying-the-collector). +::: + ### Using a Custom PodMonitor For scenarios that require more granular control over metric collection — such as filtering out duplicate labels introduced during Prometheus scraping — you can create a `PodMonitor` resource manually instead of relying on the automatic `ServiceMonitor` provisioning. diff --git a/docs/en/configuration/send-telemetry-data/runme-test_without-sidecar.sh b/docs/en/configuration/send-telemetry-data/runme-test_without-sidecar.sh new file mode 100755 index 0000000..d6de197 --- /dev/null +++ b/docs/en/configuration/send-telemetry-data/runme-test_without-sidecar.sh @@ -0,0 +1,207 @@ +#!/usr/bin/env bash +# 「不使用 Sidecar 注入发送遥测数据」文档测试脚本 +# 对应文档: docs/en/configuration/send-telemetry-data/without-sidecar.mdx +# 覆盖范围:「Procedure」章节步骤 1（no-sidecar:deploy-collector）—— +# 以 deployment 模式部署带 k8s_attributes 处理器的 OpenTelemetry Collector， +# 用于验证 Operator「自动创建集群级 RBAC」在 k8s_attributes 场景下确实生效。 +# +# 说明: +# - 文档步骤 2（示例应用 my-app）使用 myapp:latest 占位镜像不可运行，不在测试范围内， +# 故该代码块不加 {name=} 标注； +# - 文档未包含 observability 命名空间的创建与清理步骤，由本脚本负责（命名空间由本脚本 +# 创建时会打上标签，cleanup 仅删除带该标签的命名空间，避免误删环境上同名命名空间）； +# - exporter endpoint "-collector:4317" 为占位值，不影响 Collector +# 的部署与启动（无遥测数据流入时不会触发导出），保持原样不做替换。 +# +# 前置: +# 1. 已执行 rbac-resources 测试（授予 Operator 管理集群级 RBAC 的权限）； +# 2. 已安装 Alauda Build of OpenTelemetry v2 Operator。 + +set -e + +: "${FRAMEWORK_ROOT:?该脚本需经 docs-runme-tests/run.sh 运行}" + +# 加载框架函数库 +source "$FRAMEWORK_ROOT/framework/common.sh" +source "$FRAMEWORK_ROOT/framework/verify.sh" + +# ── 常量 ────────────────────────────────────────────────────────────────────── +# Collector 命名空间与实例名（与文档代码块中的 CR 保持一致） +NO_SIDECAR_NS="observability" +NO_SIDECAR_COLLECTOR="otel" +# Collector 相关资源的标签选择器（Operator 为其管理的所有对象统一打的标签） +NO_SIDECAR_POD_SELECTOR="app.kubernetes.io/managed-by=opentelemetry-operator" +# Operator 为该 Collector 自动生成的集群级 RBAC 的选择器（对应 opentelemetry-operator +# internal/manifests/manifestutils.SelectorLabels），cleanup 用于兜底清理 +NO_SIDECAR_RBAC_SELECTOR="app.kubernetes.io/managed-by=opentelemetry-operator,app.kubernetes.io/instance=${NO_SIDECAR_NS}.${NO_SIDECAR_COLLECTOR},app.kubernetes.io/component=opentelemetry-collector" +# 标记命名空间由本测试创建，cleanup 据此判断是否可以删除命名空间 +NO_SIDECAR_NS_LABEL="runme-test/created-by=without-sidecar" +# 部署成功后观察 Collector 日志的时长（秒），期间日志中不得出现 error 关键词 +NO_SIDECAR_LOG_WATCH_SECONDS="${NO_SIDECAR_LOG_WATCH_SECONDS:-30}" + +# 失败时输出诊断信息，便于定位 RBAC / 配置问题 +_no_sidecar_dump_diagnostics() { + log_warn "--- Pod 状态 ---" + kubectl get pods -n "$NO_SIDECAR_NS" -o wide 2>&1 || true + log_warn "--- OpenTelemetryCollector 状态 ---" + kubectl get opentelemetrycollector "$NO_SIDECAR_COLLECTOR" -n "$NO_SIDECAR_NS" \ + -o jsonpath='{.status}' 2>&1 || true + echo "" + log_warn "--- Collector 日志（最后 50 行）---" + kubectl logs -n "$NO_SIDECAR_NS" -l "$NO_SIDECAR_POD_SELECTOR" \ + --all-containers --tail=50 --prefix 2>&1 || true +} + +# 测试函数：部署 deployment 模式 Collector 并验证 k8s_attributes 无 RBAC 报错 +test_without_sidecar() { + log_info "==========================================" + log_info "开始 不使用 Sidecar 注入发送遥测数据 测试" + log_info "==========================================" + + # 步骤 1: 创建 observability 命名空间（文档未包含该步骤，由测试脚本负责） + log_info "步骤 1: 创建命名空间 $NO_SIDECAR_NS" + if kubectl get namespace "$NO_SIDECAR_NS" >/dev/null 2>&1; then + log_info "命名空间 $NO_SIDECAR_NS 已存在，复用" + else + kubectl create namespace "$NO_SIDECAR_NS" || { + log_error "创建命名空间 $NO_SIDECAR_NS 失败" + return 1 + } + # 打标签标明由本测试创建，供 cleanup 判断是否可删除 + kubectl label namespace "$NO_SIDECAR_NS" "$NO_SIDECAR_NS_LABEL" --overwrite || { + log_error "标记命名空间 $NO_SIDECAR_NS 失败" + return 1 + } + fi + + # 步骤 2: 以 deployment 模式部署 Collector（processors 含 k8s_attributes） + # 注意: 文档该代码块的语言标记是 yaml，runme run 对 yaml 块只回显内容不执行（且返回 0）， + # 因此改用 runme print 取出命令内容后 eval 执行。 + log_info "步骤 2: 部署 OpenTelemetryCollector（deployment 模式，含 k8s_attributes 处理器）" + local deploy_cmd + deploy_cmd=$(runme print no-sidecar:deploy-collector) || { + log_error "获取代码块内容失败: no-sidecar:deploy-collector" + return 1 + } + if [ -z "$deploy_cmd" ]; then + log_error "代码块内容为空: no-sidecar:deploy-collector" + return 1 + fi + + local deploy_output + deploy_output=$(eval "$deploy_cmd" 2>&1) || { + log_error "部署 OpenTelemetryCollector 失败" + log_error "若为 admission webhook 拒绝，请确认已按 installing/rbac-resources.mdx 授予" + log_error "Operator 管理集群级 RBAC 的权限，且提交资源的用户本身持有对应权限" + log_error "输出: $deploy_output" + return 1 + } + log_info "输出: $deploy_output" + + # 步骤 3: 等待 Collector 就绪 + log_info "步骤 3: 等待 OpenTelemetryCollector status.scale.statusReplicas=1/1" + kubectl wait "opentelemetrycollector/$NO_SIDECAR_COLLECTOR" \ + -n "$NO_SIDECAR_NS" \ + --for=jsonpath='{.status.scale.statusReplicas}'=1/1 \ + --timeout=180s || { + log_error "等待 OpenTelemetryCollector status.scale.statusReplicas=1/1 失败" + _no_sidecar_dump_diagnostics + return 1 + } + + log_info "等待 Collector Pod Ready" + kubectl wait --for=condition=Ready pod -l "$NO_SIDECAR_POD_SELECTOR" \ + -n "$NO_SIDECAR_NS" --timeout=3m || { + log_error "等待 Collector Pod Ready 失败" + _no_sidecar_dump_diagnostics + return 1 + } + log_success "Collector 部署成功" + + # 步骤 4: 观察日志，确认无 error 关键词 + # k8s_attributes 处理器缺少集群级 RBAC 时，Collector 会在启动后持续输出 list/watch + # 被拒绝（forbidden）的错误日志，此处以此作为核心断言。 + log_info "步骤 4: 观察 Collector 日志 ${NO_SIDECAR_LOG_WATCH_SECONDS}s，确认无 error 关键词" + sleep "$NO_SIDECAR_LOG_WATCH_SECONDS" + + local logs + logs=$(kubectl logs -n "$NO_SIDECAR_NS" -l "$NO_SIDECAR_POD_SELECTOR" \ + --all-containers --tail=-1 --prefix 2>&1) || { + log_error "获取 Collector 日志失败" + log_error "输出: $logs" + return 1 + } + if [ -z "$logs" ]; then + log_error "Collector 日志为空，无法完成观察（正常启动的 Collector 至少会输出启动日志）" + _no_sidecar_dump_diagnostics + return 1 + fi + + # 观察窗口内不得发生容器重启：重启会重置日志，可能掩盖启动期的错误 + local restart_total + restart_total=$(kubectl get pods -n "$NO_SIDECAR_NS" -l "$NO_SIDECAR_POD_SELECTOR" \ + -o jsonpath='{.items[*].status.containerStatuses[*].restartCount}' 2>/dev/null \ + | awk '{s=0; for (i=1; i<=NF; i++) s+=$i; print s+0}') + if [ "${restart_total:-0}" -ne 0 ]; then + log_error "观察期内 Collector 容器发生了 ${restart_total} 次重启" + _no_sidecar_dump_diagnostics + return 1 + fi + + # error 关键词不区分大小写：统一转小写后断言不包含 + local logs_lower + logs_lower=$(printf '%s' "$logs" | tr '[:upper:]' '[:lower:]') + if ! __cmp_not_contains "$logs_lower" "error"; then + log_error "Collector 日志中检测到 error 关键词（k8s_attributes 处理器缺少集群级 RBAC 时的典型现象）" + log_error "匹配行（最多 20 行）:" + printf '%s\n' "$logs" | grep -i "error" | head -n 20 >&2 + return 1 + fi + log_success "Collector 日志 ${NO_SIDECAR_LOG_WATCH_SECONDS}s 内无 error 关键词" + + log_success "==========================================" + log_success "不使用 Sidecar 注入发送遥测数据 测试完成，所有验证通过！" + log_success "==========================================" + return 0 +} + +# 清理函数：删除 Collector 与 observability 命名空间 +# 注意: 启用自动 RBAC 后 Operator 会给 Collector 加 finalizer，并在删除时回收自动生成的 +# 集群级 RBAC，因此本清理必须在卸载 Operator、回收 rbac-resources 授权之前执行。 +cleanup_without_sidecar() { + log_info "==========================================" + log_info "清理 不使用 Sidecar 注入发送遥测数据 测试资源" + log_info "==========================================" + + # 步骤 1: 删除 OpenTelemetryCollector + log_info "步骤 1: 删除 OpenTelemetryCollector $NO_SIDECAR_COLLECTOR" + kubectl delete opentelemetrycollector "$NO_SIDECAR_COLLECTOR" -n "$NO_SIDECAR_NS" \ + --ignore-not-found=true --timeout=120s || { + log_error "删除 OpenTelemetryCollector 失败（Operator 异常时 finalizer 可能未被摘除）" + return 1 + } + + # 步骤 2: 兜底清理 Operator 为该 Collector 自动生成的集群级 RBAC + # 正常情况下 Operator 的 finalizer 已回收，此处按其选择器标签补删，防止残留集群级资源。 + log_info "步骤 2: 兜底清理 Operator 自动生成的集群级 RBAC" + kubectl delete clusterrole,clusterrolebinding -l "$NO_SIDECAR_RBAC_SELECTOR" \ + --ignore-not-found=true || { + log_error "清理自动生成的集群级 RBAC 失败" + return 1 + } + + # 步骤 3: 删除命名空间（仅删除由本测试创建的命名空间） + log_info "步骤 3: 删除命名空间 $NO_SIDECAR_NS" + if kubectl get namespace -l "$NO_SIDECAR_NS_LABEL" -o name 2>/dev/null \ + | grep -qx "namespace/$NO_SIDECAR_NS"; then + kubectl delete namespace "$NO_SIDECAR_NS" --ignore-not-found=true --timeout=180s || { + log_error "删除命名空间 $NO_SIDECAR_NS 失败" + return 1 + } + else + log_warn "命名空间 $NO_SIDECAR_NS 不存在或非本测试创建（无 $NO_SIDECAR_NS_LABEL 标签），保留不删除" + fi + + log_success "测试资源清理完成" + return 0 +} diff --git a/docs/en/configuration/send-telemetry-data/sidecar-injection.mdx b/docs/en/configuration/send-telemetry-data/sidecar-injection.mdx index edaaae8..b274804 100644 --- a/docs/en/configuration/send-telemetry-data/sidecar-injection.mdx +++ b/docs/en/configuration/send-telemetry-data/sidecar-injection.mdx @@ -6,6 +6,10 @@ weight: 10 You can configure the Alauda build of OpenTelemetry v2 to inject the OpenTelemetry Collector as a sidecar container into your application pods. The sidecar Collector runs in the same pod as your application, enabling applications to send telemetry data to the Collector via `localhost` without complex network configuration. +:::note +The Operator does not create `Service`, `Ingress`, `NetworkPolicy`, or `HorizontalPodAutoscaler` resources for a Collector in sidecar mode, because it does not own the pod lifecycle in that mode. Applications reach the sidecar over `localhost`; if its ports must be reachable from outside the pod, expose them through the application's own `Service`. +::: + ## Prerequisites - Alauda build of OpenTelemetry v2 Operator is installed. @@ -41,7 +45,7 @@ You can configure the Alauda build of OpenTelemetry v2 to inject the OpenTelemet limit_percentage: 80 spike_limit_percentage: 20 exporters: - otlp: + otlp_grpc: # [!code callout] endpoint: "jaeger--collector:4317" # [!code callout] tls: insecure: true @@ -50,13 +54,14 @@ You can configure the Alauda build of OpenTelemetry v2 to inject the OpenTelemet traces: receivers: [otlp] processors: [memory_limiter, batch] - exporters: [otlp] + exporters: [otlp_grpc] EOF ``` 1. Replace `/asm/opentelemetry-collector:` with the actual image registry and tag for the sidecar Collector. - 2. Replace `jaeger--collector` with the actual service name of your Alauda Build of Jaeger v2 collector. The format is typically `-collector`. + 2. The OTLP gRPC exporter is named `otlp_grpc`. The former name `otlp` still works but is deprecated. Note that the OTLP **receiver** keeps the name `otlp`; see [Component type names](../collector/configuration-options.mdx#component-type-names). + 3. Replace `jaeger--collector` with the actual service name of your Alauda Build of Jaeger v2 collector. The format is typically `-collector`. 2. Create a deployment that uses the sidecar injection by adding the annotation `sidecar.opentelemetry.io/inject: "true"` and using the created ServiceAccount: diff --git a/docs/en/configuration/send-telemetry-data/without-sidecar.mdx b/docs/en/configuration/send-telemetry-data/without-sidecar.mdx index 7b4b25f..0d86ef0 100644 --- a/docs/en/configuration/send-telemetry-data/without-sidecar.mdx +++ b/docs/en/configuration/send-telemetry-data/without-sidecar.mdx @@ -17,7 +17,7 @@ Instead of injecting a sidecar, you can deploy the OpenTelemetry Collector as a 1. Deploy the OpenTelemetry Collector instance with the `deployment` mode by running the following command: - ```yaml + ```yaml {name=no-sidecar:deploy-collector} kubectl apply -f - <-collector:4317" # [!code callout] tls: insecure: true @@ -58,19 +58,20 @@ Instead of injecting a sidecar, you can deploy the OpenTelemetry Collector as a pipelines: traces: receivers: [jaeger, otlp, zipkin] - processors: [memory_limiter, k8sattributes, batch] - exporters: [otlp/traces] + processors: [memory_limiter, k8s_attributes, batch] + exporters: [otlp_grpc/traces] EOF ``` 1. The namespace determines where the Collector resources are created. - 2. The exporter endpoint must point to the Jaeger collector service. Replace `-collector:4317` with the actual service name of your Jaeger deployment. + 2. The OTLP gRPC exporter is named `otlp_grpc`. The former name `otlp` still works but is deprecated. Note that the OTLP **receiver** keeps the name `otlp`; see [Component type names](../collector/configuration-options.mdx#component-type-names). + 3. The exporter endpoint must point to the Jaeger collector service. Replace `-collector:4317` with the actual service name of your Jaeger deployment. 2. Set the environment variables in the container with your instrumented application to send telemetry data to the Collector: - ```bash + ```yaml kubectl apply -f - <&1) || { + log_error "创建 ClusterRole 失败" + log_error "输出: $cr_output" + return 1 + } + log_info "输出: $cr_output" + + # 步骤 2: 创建 ClusterRoleBinding + log_info "步骤 2: 创建 ClusterRoleBinding generate-processors-rbac" + local crb_output + crb_output=$(runme run rbac:create-clusterrolebinding 2>&1) || { + log_error "创建 ClusterRoleBinding 失败" + log_error "输出: $crb_output" + return 1 + } + log_info "输出: $crb_output" + + # 步骤 3:（可选）重启 Operator 使新 RBAC 权限生效 + # 文档 tip: 仅当 Operator 已在运行时才需要执行；在安装 Operator 之前创建 RBAC 时可跳过。 + # 编排中本测试先于 install-opentelemetry 执行，此时 Operator 通常尚未安装， + # 命名空间不存在导致该命令报错时按「空操作」处理。 + log_info "步骤 3: 重启 Operator 使 RBAC 权限生效（文档标注为可选步骤）" + local restart_output + if restart_output=$(runme run rbac:restart-operator 2>&1); then + log_info "输出: $restart_output" + else + if kubectl get namespace "$RBAC_OPERATOR_NS" >/dev/null 2>&1; then + log_error "重启 Operator 失败" + log_error "输出: $restart_output" + return 1 + fi + log_info "命名空间 $RBAC_OPERATOR_NS 不存在（Operator 尚未安装），该可选步骤为空操作" + fi + + # Operator 已安装时等待其重新就绪，避免后续测试踩到尚未恢复的 admission webhook + local operator_deploys + operator_deploys=$(kubectl -n "$RBAC_OPERATOR_NS" get deployment -o name 2>/dev/null || true) + if [ -n "$operator_deploys" ]; then + log_info "等待 Operator Deployment 重新可用: $(echo "$operator_deploys" | tr '\n' ' ')" + kubectl -n "$RBAC_OPERATOR_NS" wait --for=condition=Available deployment --all --timeout=3m || { + log_error "等待 Operator 重新就绪失败" + return 1 + } + fi + + log_success "==========================================" + log_success "自动创建 RBAC 资源 测试完成，所有验证通过！" + log_success "==========================================" + return 0 +} + +# 清理函数：回收授予 Operator 的集群级 RBAC 管理权限 +# 注意: 必须在依赖自动 RBAC 的 OpenTelemetryCollector 全部删除之后执行， +# 否则 Operator 无法回收其为这些 Collector 生成的集群级 RBAC（见文档 warning）。 +cleanup_rbac_resources() { + log_info "==========================================" + log_info "清理 自动创建 RBAC 资源 测试资源" + log_info "==========================================" + + runme run rbac:cleanup || { + log_error "清理 RBAC 资源失败" + return 1 + } + + log_success "测试资源清理完成" + return 0 +} diff --git a/docs/en/migrating/migrating-to-v2.mdx b/docs/en/migrating/migrating-to-v2.mdx index 7bb8ff4..6e75db8 100644 --- a/docs/en/migrating/migrating-to-v2.mdx +++ b/docs/en/migrating/migrating-to-v2.mdx @@ -4,7 +4,7 @@ weight: 10 # Migrating from Alauda Build of OpenTelemetry to Alauda Build of OpenTelemetry v2 -This document describes how to migrate an existing `Alauda Build of OpenTelemetry` (built on upstream OpenTelemetry Operator/Collector `0.108.0`) deployment to `Alauda Build of OpenTelemetry v2` (built on upstream `0.147.0`). +This document describes how to migrate an existing `Alauda Build of OpenTelemetry` (built on upstream OpenTelemetry Operator/Collector `0.108.0`) deployment to `Alauda Build of OpenTelemetry v2` (built on upstream Operator `0.157.0` and Collector `0.158.0`). The two distributions are delivered through different OLM packages — `opentelemetry-operator` and `opentelemetry-operator2` — but they own the same Custom Resource Definitions (`OpenTelemetryCollector` and `Instrumentation`). OLM does not allow two Operators to own the same CRDs simultaneously, therefore the migration must be performed as **uninstall v1 → install v2**, not as a side-by-side upgrade. @@ -14,7 +14,8 @@ The two distributions are delivered through different OLM packages — `opentele | Item | v1 | v2 | | :--- | :--- | :--- | -| OpenTelemetry Operator/Collector version | 0.108.0 | 0.147.0 | +| Upstream OpenTelemetry Operator version | 0.108.0 | 0.157.0 | +| Upstream OpenTelemetry Collector version | 0.108.0 | 0.158.0 | | OLM package / Subscription name | `opentelemetry-operator` | `opentelemetry-operator2` | | Recommended Operator namespace | `opentelemetry-operator` | `opentelemetry-operator2` | | Default subscription channel | `alpha` | `stable` | @@ -123,8 +124,8 @@ In v1, Alauda ships a customized Java auto-instrumentation image with the Operat | Option | When to use | Example | | :--- | :--- | :--- | -| Upstream community image | Cluster has access to public registries | `ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1` | -| Self-built or mirrored image | Air-gapped clusters, or environments with image supply-chain compliance requirements | `registry.example.com/otel/autoinstrumentation-java:2.26.1` | +| Upstream community image | Cluster has access to public registries | `ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.30.0` | +| Self-built or mirrored image | Air-gapped clusters, or environments with image supply-chain compliance requirements | `registry.example.com/otel/autoinstrumentation-java:2.30.0` | :::note The OpenTelemetry Java agent has moved from the `1.x` series to the `2.x` series. Some auto-generated metric names and attributes are different from what v1 produced. If your dashboards or alerts depend on specific metric names, review the changes in the upstream Java agent release notes and update them accordingly. @@ -132,10 +133,11 @@ The OpenTelemetry Java agent has moved from the `1.x` series to the `2.x` series ### Check Collector configuration compatibility -Alauda Build of OpenTelemetry v2 supports the components listed in the [v2.0.0 Release Notes](../about/release-notes/v2-0-0.mdx). Review every `receiver`, `processor`, `exporter`, `connector`, and `extension` referenced in your existing `OpenTelemetryCollector` resources and confirm that: +Alauda Build of OpenTelemetry v2 supports the components listed in the [v2.1.0 Release Notes](../about/release-notes/v2-1-0.mdx). Review every `receiver`, `processor`, `exporter`, `connector`, and `extension` referenced in your existing `OpenTelemetryCollector` resources and confirm that: - Each component is included in the v2 supported component lists. -- The configuration syntax matches the upstream `0.147.0` schema. Some fields have changed across the upstream release range. For example, the `spec.config.service.telemetry.metrics` configuration shape differs between the two versions. +- The component type names match the current upstream spelling. Most component types were renamed to snake_case across the upstream release range — for example `k8sattributes` became `k8s_attributes`. The previous names still work as deprecated aliases, but the [v2.1.0 Release Notes](../about/release-notes/v2-1-0.mdx) list the current spelling for each component. +- The configuration syntax matches the upstream Collector `0.158.0` schema. Some fields have changed across the upstream release range. For example, the `spec.config.service.telemetry.metrics` configuration shape differs between the two versions, and the Kafka exporter no longer accepts top-level `topic` and `encoding` fields. If you have a staging environment, applying your v1 configuration to a freshly installed v2 Operator there is a good way to surface incompatibilities before the production migration. @@ -248,7 +250,7 @@ Follow [Installing the Alauda Build of OpenTelemetry v2 Operator](../installing/ name: opentelemetry-operator2 source: platform sourceNamespace: cpaas-system - # startingCSV example: opentelemetry-operator2.v0.147.0-r0 + # startingCSV example: opentelemetry-operator2.v0.157.0-rc.2 startingCSV: {step-1-operator-csv-version} EOF ``` @@ -304,7 +306,7 @@ When you rebuild the `OpenTelemetryCollector` manifests from your v1 backup, the - **Server-managed metadata**. Fields written by the API server (`metadata.creationTimestamp`, `metadata.resourceVersion`, `metadata.uid`, `metadata.generation`, `metadata.managedFields`, `metadata.finalizers`, the `kubectl.kubernetes.io/last-applied-configuration` annotation, and `status`) cannot be reused on create and must be stripped from the backup. -- **Operator-managed RBAC and Prometheus scraping**. The v2 Operator automatically creates the `ServiceAccount` and `ClusterRoleBinding` resources required by the Collector. Drop the v1 `spec.serviceAccount` field from the backup so the Operator can provision a fresh ServiceAccount with the correct permissions; you generally do not have to recreate the v1 RBAC resources by hand. To have the Operator also create a `ServiceMonitor` for the internal Prometheus endpoint, set `spec.observability.metrics.enableMetrics: true` and add a discovery label (such as `prometheus: kube-prometheus`) to `metadata.labels` so that your Prometheus Operator instance picks the resource up. If a Collector component requires additional cluster-level RBAC (for example, the `k8sattributes` processor or the `k8sobjects` receiver), follow [Creating the Required RBAC Resources Automatically](../installing/rbac-resources.mdx). +- **Operator-managed RBAC and Prometheus scraping**. The v2 Operator automatically creates the `ServiceAccount` and `ClusterRoleBinding` resources required by the Collector. Drop the v1 `spec.serviceAccount` field from the backup so the Operator can provision a fresh ServiceAccount with the correct permissions; you generally do not have to recreate the v1 RBAC resources by hand. To have the Operator also create a `ServiceMonitor` for the internal Prometheus endpoint, set `spec.observability.metrics.enableMetrics: true` and add a discovery label (such as `prometheus: kube-prometheus`) to `metadata.labels` so that your Prometheus Operator instance picks the resource up. If a Collector component requires additional cluster-level RBAC (for example, the `k8s_attributes` processor or the `k8s_objects` receiver), follow [Creating the Required RBAC Resources Automatically](../installing/rbac-resources.mdx). Note that the v2 Operator also verifies that the user creating the `OpenTelemetryCollector` holds the permissions being generated, so perform the migration as a user with sufficient privileges. #### Migration procedure \{#collector-migration-procedure} @@ -346,10 +348,7 @@ When you rebuild the `OpenTelemetryCollector` manifests from your v1 backup, the exporter: { prometheus: { host: "0.0.0.0", - port: 8888, - without_scope_info: true, - without_type_suffix: true, - without_units: true + port: 8888 } } } @@ -381,7 +380,7 @@ Use the same working directory created in the previous step. The following examp ```bash {name=migrate:create-v2-instrumentation-from-backup} RESTORE_DIR=./otel-v2-restore -JAVA_AUTO_INSTRUMENTATION_IMAGE="ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.26.1" +JAVA_AUTO_INSTRUMENTATION_IMAGE="ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:2.30.0" mkdir -p "$RESTORE_DIR" cp ./otel-v1-backup/instrumentations.yaml "$RESTORE_DIR/instrumentations.yaml" @@ -548,7 +547,7 @@ Restart the workloads with `kubectl rollout restart` so that the v1 mutating web | Symptom | Likely cause | Resolution | | :--- | :--- | :--- | | OLM rejects the v2 Operator installation with a CRD owner conflict | A v1 `ClusterServiceVersion` still exists in the cluster | Wait for `kubectl get csv -A \| grep '^opentelemetry-operator '` to be empty; manually delete any remaining v1 CSVs | -| The v2 Collector pod is stuck in `CrashLoopBackOff` | The Collector configuration uses a component that v2 does not support, or a field whose schema changed in `0.147.0` | Inspect the Collector pod logs; cross-check every component against the [v2.0.0 Release Notes](../about/release-notes/v2-0-0.mdx) and update or remove unsupported items | +| The v2 Collector pod is stuck in `CrashLoopBackOff` | The Collector configuration uses a component that v2 does not support, or a field whose schema changed in Collector `0.158.0` | Inspect the Collector pod logs; cross-check every component against the [v2.1.0 Release Notes](../about/release-notes/v2-1-0.mdx) and update or remove unsupported items | | Application pods restart but no init container is injected | The mutating webhook is not ready, the `Instrumentation` resource is missing, or the pod annotation references the wrong `Instrumentation` | Check `kubectl get mutatingwebhookconfigurations`, confirm the `Instrumentation` exists in the expected namespace, and verify the value of `instrumentation.opentelemetry.io/inject-java` | | Application pods start but no traces are produced | The `OTEL_EXPORTER_OTLP_ENDPOINT` is wrong, the Collector is not ready, or network policies block ports `4317` / `4318` | Test connectivity from inside the pod (for example, `nc -vz 4318`); review NetworkPolicy resources; check the Collector pod logs | diff --git a/docs/en/troubleshooting/collector-logs.mdx b/docs/en/troubleshooting/collector-logs.mdx index 9a2b20e..7aff8c1 100644 --- a/docs/en/troubleshooting/collector-logs.mdx +++ b/docs/en/troubleshooting/collector-logs.mdx @@ -44,3 +44,24 @@ If the Collector runs in Deployment mode, you can view logs from all replicas: ```bash kubectl logs -l app.kubernetes.io/name=otel-collector -n opentelemetry-collector ``` + +## Common startup warnings + +### Deprecated component type alias \{#deprecated-alias-warning} + +```text +warn builders/builders.go:40 "otlp" alias is deprecated; use "otlp_grpc" instead + {"otelcol.component.id": "otlp/traces", "otelcol.component.kind": "exporter", "otelcol.signal": "traces"} +``` + +The component is configured under a type name that upstream has renamed. The old name still resolves to the same implementation, so the Collector runs normally and no data is lost, but the alias will be removed in a future release. + +Read `otelcol.component.kind` before editing the configuration — it tells you which section to change. In the example above the warning is about an **exporter**, so only the `exporters` section needs the new name; the OTLP receiver in the same configuration keeps the name `otlp`. Rename the component under `spec.config`, keeping any `/name` suffix: + +```yaml +exporters: + otlp_grpc/traces: # was otlp/traces + endpoint: jaeger-collector:4317 +``` + +The warning is logged once per component instance at startup, so it reappears on every restart until the configuration is updated. For the full list of renamed components, see [Component type names](../configuration/collector/configuration-options.mdx#component-type-names). diff --git a/docs/en/troubleshooting/debug-exporter.mdx b/docs/en/troubleshooting/debug-exporter.mdx index a4c8938..a713242 100644 --- a/docs/en/troubleshooting/debug-exporter.mdx +++ b/docs/en/troubleshooting/debug-exporter.mdx @@ -68,7 +68,7 @@ config: exporters: debug: verbosity: detailed - otlp: + otlp_grpc: endpoint: jaeger-collector:4317 tls: insecure: true @@ -77,7 +77,7 @@ config: traces: receivers: [otlp] processors: [batch] - exporters: [debug, otlp] + exporters: [debug, otlp_grpc] ``` In this configuration, traces data is sent to both the Debug Exporter and the OTLP exporter. diff --git a/docs/en/troubleshooting/exposing-metrics.mdx b/docs/en/troubleshooting/exposing-metrics.mdx index 605757a..7c1a6c5 100644 --- a/docs/en/troubleshooting/exposing-metrics.mdx +++ b/docs/en/troubleshooting/exposing-metrics.mdx @@ -31,6 +31,10 @@ The Collector exposes the following metrics related to data processing volume: - `otelcol_exporter_sent_metrics`: Number of metric data points sent by exporters - `otelcol_exporter_enqueue_failed_metrics`: Number of metric data points that failed to enqueue in exporters +:::note +These metrics do not carry `service_name`, `service_instance_id`, or `service_version` labels. To identify which Collector produced a series, join against `target_info`. See [Identifying the Collector that produced a metric](../configuration/collector-metrics/index.mdx#identifying-the-collector). +::: + ## Configuring metrics exposure ### Configuring the Prometheus metrics endpoint @@ -53,9 +57,6 @@ spec: prometheus: host: "0.0.0.0" port: 8888 - without_scope_info: true - without_type_suffix: true - without_units: true ``` ### Enabling metrics scraping diff --git a/docs/en/uninstalling/uninstalling-opentelemetry.mdx b/docs/en/uninstalling/uninstalling-opentelemetry.mdx index dbe0bb6..7fd251a 100644 --- a/docs/en/uninstalling/uninstalling-opentelemetry.mdx +++ b/docs/en/uninstalling/uninstalling-opentelemetry.mdx @@ -107,7 +107,7 @@ The Alauda Build of OpenTelemetry v2 Operator can be uninstalled using the Alaud ```shell {name=uninstall-otel:get-collector-output} NAMESPACE NAME MODE VERSION READY AGE IMAGE MANAGEMENT - deployment 0.146.0 1/1 3h38m managed + deployment 0.158.0 1/1 3h38m managed ``` 2. Use the namespace and name from the previous command's output to replace `` and ``, and then run the following to remove each resource: diff --git a/hack/update-java-autoinstrumentation-version.sh b/hack/update-java-autoinstrumentation-version.sh new file mode 100755 index 0000000..0e5d50b --- /dev/null +++ b/hack/update-java-autoinstrumentation-version.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +# +# 更新 ./docs/en/ 下所有 .mdx 文档中的 OpenTelemetry Java 自动插桩镜像版本。 +# +# 兼容 macOS（BSD sed/grep、bash 3.2）和 Linux（GNU sed/grep）。 +# +# 用法： +# ./hack/update-java-autoinstrumentation-version.sh <旧版本> <新版本> +# +# 示例： +# ./hack/update-java-autoinstrumentation-version.sh 2.26.1 2.29.0 + +set -euo pipefail + +if [[ $# -ne 2 ]]; then + echo "用法：$0 <旧版本> <新版本>" >&2 + echo "示例：$0 2.26.1 2.29.0" >&2 + exit 1 +fi + +OLD_VERSION="$1" +NEW_VERSION="$2" + +VERSION_RE='^[0-9]+\.[0-9]+\.[0-9]+$' +if ! [[ "$OLD_VERSION" =~ $VERSION_RE ]]; then + echo "错误：旧版本 '$OLD_VERSION' 不符合 X.Y.Z 格式" >&2 + exit 1 +fi +if ! [[ "$NEW_VERSION" =~ $VERSION_RE ]]; then + echo "错误：新版本 '$NEW_VERSION' 不符合 X.Y.Z 格式" >&2 + exit 1 +fi + +if [[ "$OLD_VERSION" == "$NEW_VERSION" ]]; then + echo "新旧版本相同，无需更新。" + exit 0 +fi + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +DOCS_DIR="$REPO_ROOT/docs/en" + +if [[ ! -d "$DOCS_DIR" ]]; then + echo "错误：文档目录不存在：$DOCS_DIR" >&2 + exit 1 +fi + +IMAGE_NAME='autoinstrumentation-java' +OLD_IMAGE_TAG="${IMAGE_NAME}:${OLD_VERSION}" +NEW_IMAGE_TAG="${IMAGE_NAME}:${NEW_VERSION}" + +# 版本号仅包含数字和点，因此只需转义点号即可用于正则表达式。 +OLD_VERSION_RE="${OLD_VERSION//./\\.}" +TARGET_RE="${IMAGE_NAME}:${OLD_VERSION_RE}([^[:alnum:]_.-]|$)" + +# 收集包含目标镜像的文件（兼容 bash 3.2，不使用 mapfile）。 +FILES=() +while IFS= read -r line; do + [[ -n "$line" ]] && FILES+=("$line") +done < <(grep -rlE --include='*.mdx' "$TARGET_RE" "$DOCS_DIR" || true) + +if [[ ${#FILES[@]} -eq 0 ]]; then + echo "docs/en/ 下没有 .mdx 文件包含 '$OLD_IMAGE_TAG'，无需更新。" + exit 0 +fi + +echo "正在更新 ${#FILES[@]} 个文件：$OLD_IMAGE_TAG -> $NEW_IMAGE_TAG" +for file in "${FILES[@]}"; do + # sed -i.bak 是 BSD sed 和 GNU sed 都支持的原地编辑形式。 + sed -i.bak \ + -e "s|${IMAGE_NAME}:${OLD_VERSION_RE}\\([^[:alnum:]_.-]\\)|${NEW_IMAGE_TAG}\\1|g" \ + -e "s|${IMAGE_NAME}:${OLD_VERSION_RE}$|${NEW_IMAGE_TAG}|g" \ + "$file" + rm -f "${file}.bak" + echo " 已更新：${file#${REPO_ROOT}/}" +done + +echo "更新完成。" diff --git a/hack/update-otel-version.sh b/hack/update-otel-version.sh index 718b33c..ab82439 100755 --- a/hack/update-otel-version.sh +++ b/hack/update-otel-version.sh @@ -1,39 +1,80 @@ #!/usr/bin/env bash # -# Update the Alauda Build of OpenTelemetry version in all .mdx files -# under ./docs/en/. +# 批量更新 ./docs/en/ 下所有 .mdx 文档中出现的版本号。 # -# Compatible with both macOS (BSD sed/grep, bash 3.2) and Linux (GNU sed/grep). +# 同时适用于 Operator 版本（形如 0.156.0-rc.2、0.147.0-r0）与 +# Collector 版本（形如 0.158.0）。 # -# Usage: -# ./hack/update-otel-version.sh +# 兼容 macOS（BSD sed/grep、bash 3.2）和 Linux（GNU sed/grep）。 # -# Example: -# ./hack/update-otel-version.sh 0.146.0-r0 0.147.0-r0 +# 用法： +# ./hack/update-otel-version.sh [选项] <旧版本> <新版本> +# +# 选项： +# -n, --dry-run 只列出将要发生的替换，不写入文件 +# -h, --help 显示帮助 +# +# 示例： +# # 更新 Operator 版本 +# ./hack/update-otel-version.sh 0.147.0-r0 0.156.0-rc.2 +# # 更新 Collector 版本 +# ./hack/update-otel-version.sh 0.147.0 0.158.0 +# # 先预览再执行 +# ./hack/update-otel-version.sh --dry-run 0.147.0 0.158.0 set -euo pipefail -if [[ $# -ne 2 ]]; then - echo "Usage: $0 " >&2 - echo "Example: $0 0.146.0-r0 0.147.0-r0" >&2 +usage() { + cat >&2 <<'EOF' +用法：update-otel-version.sh [选项] <旧版本> <新版本> + +选项： + -n, --dry-run 只列出将要发生的替换，不写入文件 + -h, --help 显示本帮助 + +版本号格式：X.Y.Z，可带后缀，例如 0.158.0、0.147.0-r0、0.156.0-rc.2。 + +示例： + # 更新 Operator 版本 + update-otel-version.sh 0.147.0-r0 0.156.0-rc.2 + # 更新 Collector 版本 + update-otel-version.sh 0.147.0 0.158.0 +EOF +} + +DRY_RUN=false +POSITIONAL=() +while [[ $# -gt 0 ]]; do + case "$1" in + -n|--dry-run) DRY_RUN=true; shift ;; + -h|--help) usage; exit 0 ;; + --) shift; while [[ $# -gt 0 ]]; do POSITIONAL+=("$1"); shift; done ;; + -*) echo "错误：未知选项 '$1'" >&2; usage; exit 1 ;; + *) POSITIONAL+=("$1"); shift ;; + esac +done + +if [[ ${#POSITIONAL[@]} -ne 2 ]]; then + usage exit 1 fi -OLD_VERSION="$1" -NEW_VERSION="$2" +OLD_VERSION="${POSITIONAL[0]}" +NEW_VERSION="${POSITIONAL[1]}" -VERSION_RE='^[0-9]+\.[0-9]+\.[0-9]+-r[0-9]+$' +# 允许裸 X.Y.Z（Collector 版本）以及带后缀的形式（如 -r0、-rc.2）。 +VERSION_RE='^[0-9]+\.[0-9]+\.[0-9]+([.+-][0-9A-Za-z.+-]+)?$' if ! [[ "$OLD_VERSION" =~ $VERSION_RE ]]; then - echo "Error: old version '$OLD_VERSION' does not match format X.Y.Z-rN" >&2 + echo "错误：旧版本 '${OLD_VERSION}' 不符合 X.Y.Z[-后缀] 格式" >&2 exit 1 fi if ! [[ "$NEW_VERSION" =~ $VERSION_RE ]]; then - echo "Error: new version '$NEW_VERSION' does not match format X.Y.Z-rN" >&2 + echo "错误：新版本 '${NEW_VERSION}' 不符合 X.Y.Z[-后缀] 格式" >&2 exit 1 fi if [[ "$OLD_VERSION" == "$NEW_VERSION" ]]; then - echo "Old and new versions are identical; nothing to do." + echo "新旧版本相同，无需更新。" exit 0 fi @@ -42,32 +83,67 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" DOCS_DIR="$REPO_ROOT/docs/en" if [[ ! -d "$DOCS_DIR" ]]; then - echo "Error: docs directory not found: $DOCS_DIR" >&2 + echo "错误：文档目录不存在：${DOCS_DIR}" >&2 exit 1 fi -# Escape regex metacharacters in the old version for the sed pattern. -ESCAPED_OLD="$(printf '%s' "$OLD_VERSION" | sed 's/[.[\*^$/]/\\&/g')" -# Escape replacement-side specials (& and \) in the new version. -ESCAPED_NEW="$(printf '%s' "$NEW_VERSION" | sed 's/[&\\/]/\\&/g')" +# 版本号只含数字、字母、点、加号和连字符，作为 ERE 时只需转义点号和加号。 +OLD_RE="$(printf '%s' "$OLD_VERSION" | sed -e 's/[.+]/\\&/g')" +# 替换侧需要转义 & 与反斜杠。 +NEW_ESCAPED="$(printf '%s' "$NEW_VERSION" | sed -e 's/[&\\]/\\&/g')" + +# 边界约束，避免把短版本号误当成长版本号的前缀： +# - 左侧不能紧跟数字或点，否则 10.147.0 会被误匹配；字母不排除， +# 因为 CSV 名称形如 opentelemetry-operator2.v0.156.0-rc.2。 +# - 右侧不能紧跟版本号可能包含的字符，否则用 0.147.0 会命中 0.147.0-r0。 +LEFT='(^|[^0-9.])' +RIGHT='([^0-9A-Za-z_.+-])' +MATCH_RE="${LEFT}${OLD_RE}(${RIGHT}|$)" -# Collect matching files (bash 3.2 compatible: no mapfile). +# 收集包含目标版本号的文件（兼容 bash 3.2，不使用 mapfile）。 FILES=() while IFS= read -r line; do [[ -n "$line" ]] && FILES+=("$line") -done < <(grep -rl --include='*.mdx' -F "$OLD_VERSION" "$DOCS_DIR" || true) +done < <(grep -rlE --include='*.mdx' "$MATCH_RE" "$DOCS_DIR" || true) if [[ ${#FILES[@]} -eq 0 ]]; then - echo "No .mdx files under docs/en/ contain '$OLD_VERSION'. Nothing to update." + echo "docs/en/ 下没有 .mdx 文件包含版本号 '${OLD_VERSION}'，无需更新。" + exit 0 +fi + +if [[ "$DRY_RUN" == true ]]; then + # 变量一律加花括号：macOS 的 BSD libc 在 UTF-8 locale 下会把中文标点的首字节 + # 当成字母，裸写 $VAR 时 bash 会把它并入变量名，配合 set -u 直接报 unbound variable。 + echo "[dry-run] 以下 ${#FILES[@]} 个文件包含 ${OLD_VERSION}，将被替换为 ${NEW_VERSION}：" + for file in "${FILES[@]}"; do + echo " ${file#${REPO_ROOT}/}" + grep -nE "$MATCH_RE" "$file" | sed -e 's/^/ /' + done + echo "[dry-run] 未写入任何文件。" exit 0 fi -echo "Updating ${#FILES[@]} file(s): $OLD_VERSION -> $NEW_VERSION" +echo "正在更新 ${#FILES[@]} 个文件：${OLD_VERSION} -> ${NEW_VERSION}" for file in "${FILES[@]}"; do - # `sed -i.bak` is the portable in-place form accepted by both BSD and GNU sed. - sed -i.bak "s/${ESCAPED_OLD}/${ESCAPED_NEW}/g" "$file" - rm -f "${file}.bak" - echo " updated: ${file#${REPO_ROOT}/}" + # 单次 sed 会消费掉匹配右侧的分隔字符，导致同一行内相邻的版本号被跳过， + # 因此反复替换直到文件内容不再变化。 + round=0 + while [[ $round -lt 10 ]]; do + cp "$file" "${file}.prev" + # sed -i.bak 是 BSD sed 和 GNU sed 都支持的原地编辑形式；-E 启用 ERE。 + sed -E -i.bak \ + -e "s/${LEFT}${OLD_RE}${RIGHT}/\\1${NEW_ESCAPED}\\2/g" \ + -e "s/${LEFT}${OLD_RE}\$/\\1${NEW_ESCAPED}/g" \ + "$file" + rm -f "${file}.bak" + if cmp -s "$file" "${file}.prev"; then + rm -f "${file}.prev" + break + fi + rm -f "${file}.prev" + round=$((round + 1)) + done + echo " 已更新：${file#${REPO_ROOT}/}" done -echo "Done." +echo "更新完成。请执行 git diff docs/en/ 检查改动。" diff --git a/llms.txt b/llms.txt index 78ceabc..b43e3e8 100644 --- a/llms.txt +++ b/llms.txt @@ -13,7 +13,7 @@ - [docs/en/about/lifecycle-policy/alauda-build-of-opentelemetry.mdx](docs/en/about/lifecycle-policy/alauda-build-of-opentelemetry.mdx): Lifecycle policy table for the Alauda Build of OpenTelemetry v2 Operator, showing v2.0.z released 2026-04-21 with end of support 2027-10-21. States that a new operator version ships every 4 months with 18 months of maintenance including patch tracking, security updates compliant with Alauda standards, and upgrade assistance. - [docs/en/about/lifecycle-policy/index.mdx](docs/en/about/lifecycle-policy/index.mdx): Section index page for the Lifecycle Policy area of the docs, rendering an `` listing of policy documents that detail supported versions and maintenance windows for the Alauda Build of OpenTelemetry v2 Operator. - [docs/en/about/release-notes/index.mdx](docs/en/about/release-notes/index.mdx): Section index page for Release Notes, surfacing an `` list of per-version release announcement pages for Alauda Build of OpenTelemetry v2. -- [docs/en/about/release-notes/v2-0-0.mdx](docs/en/about/release-notes/v2-0-0.mdx): Release notes for Alauda Build of OpenTelemetry v2.0.0, the first independent release shipped via Operator 0.147.0 aligned with upstream OpenTelemetry Collector 0.147.0. Enumerates supported components — 14 receivers (OTLP, Jaeger, Prometheus, Kafka, Filelog, Kubernetes Objects, etc.), 14 processors (Batch, Memory Limiter, Tail Sampling, Transform, k8sattributes, etc.), 8 exporters, 4 connectors, 8 extensions — plus auto-instrumentation for Java, Python, Node.js, .NET, Go, and Apache HTTPD, and the four `OpenTelemetryCollector` deployment modes (Deployment, StatefulSet, DaemonSet, Sidecar). +- [docs/en/about/release-notes/v2-1-0.mdx](docs/en/about/release-notes/v2-1-0.mdx): Release notes for Alauda Build of OpenTelemetry v2.1.0, shipped via Operator 0.156.0 with upstream OpenTelemetry Collector 0.158.0. Enumerates supported components — 14 receivers (OTLP, Jaeger, Prometheus, Kafka, Filelog, Kubernetes Objects, etc.), 14 processors (Batch, Memory Limiter, Tail Sampling, Transform, k8s_attributes, etc.), 8 exporters, 4 connectors, 8 extensions — plus auto-instrumentation for Java, Python, Node.js, .NET, Go, and Apache HTTPD, and the four `OpenTelemetryCollector` deployment modes. Includes upgrade notes covering the snake_case component type renames, removal of service identity labels from internal metrics, the `error_mode` default change to `ignore`, per-signal Kafka exporter topics, and sidecar-mode resource provisioning changes. - [docs/en/apis/index.mdx](docs/en/apis/index.mdx): Top-level landing page for the API Reference section, rendering an `` of API documentation including the Kubernetes APIs subsection that covers OpenTelemetry Operator custom resources. - [docs/en/apis/intro.mdx](docs/en/apis/intro.mdx): Introduction page that embeds the shared `` component to surface Alauda Container Platform API conventions used by the OpenTelemetry documentation. - [docs/en/apis/kubernetes_apis/index.mdx](docs/en/apis/kubernetes_apis/index.mdx): Section index for the Kubernetes APIs reference, rendering an `` of CRD-backed APIs exposed by the OpenTelemetry Operator (OpenTelemetryCollector, Instrumentation).