This is an automated email from the ASF dual-hosted git repository.
moonming pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 8bc3eb13af docs(opentelemetry): port current enablement guidance
(#13933)
8bc3eb13af is described below
commit 8bc3eb13afb2b62015e5fa2ca88be994b62287ea
Author: Traky Deng <[email protected]>
AuthorDate: Tue Nov 10 14:27:23 2026 +0800
docs(opentelemetry): port current enablement guidance (#13933)
* docs: clarify opentelemetry plugin enablement
* docs(opentelemetry): sync current enablement paths
---
docs/en/latest/plugins/opentelemetry.md | 52 +++++++++++++++++++++++----------
docs/zh/latest/plugins/opentelemetry.md | 52 +++++++++++++++++++++++----------
2 files changed, 74 insertions(+), 30 deletions(-)
diff --git a/docs/en/latest/plugins/opentelemetry.md
b/docs/en/latest/plugins/opentelemetry.md
index 298563a131..759a9e325d 100644
--- a/docs/en/latest/plugins/opentelemetry.md
+++ b/docs/en/latest/plugins/opentelemetry.md
@@ -36,11 +36,45 @@ The `opentelemetry` Plugin can be used to report tracing
data according to the [
The Plugin only supports binary-encoded [OTLP over
HTTP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/#otlphttp).
-## Configurations
+## Enable `opentelemetry` Plugin
+
+The `opentelemetry` Plugin is disabled by default. Load it in the APISIX
static configuration before configuring Plugin Metadata or Routes that use it.
+
+### Host or Docker
+
+In `conf/config.yaml`, keep the complete Plugin list used by your deployment
and add `opentelemetry`. If you are starting from `conf/config.yaml.example`,
uncomment the existing entry:
+
+```yaml title="config.yaml"
+plugins:
+ # Keep the complete Plugin list used by your deployment.
+ - opentelemetry
+```
+
+Reload APISIX for the change to take effect.
+
+### Kubernetes with Helm
+
+The `apisix.plugins` value replaces the loaded Plugin list. Start from the
complete list used by your deployment and add `opentelemetry`:
+
+```yaml title="values.yaml"
+apisix:
+ plugins:
+ # Keep the complete Plugin list used by your deployment.
+ - opentelemetry
+```
-By default, configurations of the Service name, tenant ID, collector, and
batch span processor are pre-configured in [default
configuration](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua).
+Apply the values file with the APISIX Helm chart, replacing the placeholders
with the installed release and chart version:
-You can change this configuration of the Plugin through the endpoint
`apisix/admin/plugin_metadata/opentelemetry` For example:
+```shell
+helm upgrade <release-name> <chart-name> \
+ --version <chart-version> \
+ -n <namespace> \
+ -f values.yaml
+```
+
+## Configurations
+
+The `opentelemetry` Plugin reads its plugin-level settings from Plugin
Metadata. Configure the metadata through the endpoint
`/apisix/admin/plugin_metadata/opentelemetry`. For example:
:::note
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
@@ -110,18 +144,6 @@ apisix:
tracing: true
```
-### Enable `opentelemetry` Plugin
-
-By default, the `opentelemetry` Plugin is disabled in APISIX. To enable, add
the Plugin to your configuration file as such:
-
-```yaml title="config.yaml"
-plugins:
- - ...
- - opentelemetry
-```
-
-Reload APISIX for changes to take effect.
-
### Send Traces to OpenTelemetry
The following example demonstrates how to trace requests to a Route and send
traces to OpenTelemetry.
diff --git a/docs/zh/latest/plugins/opentelemetry.md
b/docs/zh/latest/plugins/opentelemetry.md
index fe15e74885..338b1cece6 100644
--- a/docs/zh/latest/plugins/opentelemetry.md
+++ b/docs/zh/latest/plugins/opentelemetry.md
@@ -35,11 +35,45 @@ description: opentelemetry 插件可用于根据 OpenTelemetry 协议规范上
`opentelemetry` 插件可用于根据 [OpenTelemetry
Specification](https://opentelemetry.io/docs/reference/specification/) 协议规范上报
Traces 数据。该插件仅支持二进制编码的 OTLP over HTTP，即请求类型为 `application/x-protobuf` 的数据上报。
-## 配置
+## 启用 opentelemetry 插件
+
+`opentelemetry` 插件默认处于禁用状态。在配置插件元数据或使用该插件的路由之前，请先在 APISIX 静态配置中加载该插件。
+
+### 主机或 Docker
+
+在 `conf/config.yaml` 中保留部署使用的完整插件列表，并添加 `opentelemetry`。如果以
`conf/config.yaml.example` 为基础配置 APISIX，请取消注释已有的条目：
+
+```yaml title="config.yaml"
+plugins:
+ # 保留部署使用的完整插件列表。
+ - opentelemetry
+```
+
+重新加载 APISIX 以使更改生效。
+
+### 使用 Helm 的 Kubernetes
+
+`apisix.plugins` 会替换已加载的插件列表。请从部署使用的完整列表开始，并添加 `opentelemetry`：
+
+```yaml title="values.yaml"
+apisix:
+ plugins:
+ # 保留部署使用的完整插件列表。
+ - opentelemetry
+```
+
+使用 APISIX Helm Chart 应用 values 文件，并将占位符替换为已安装的发布名称和 Chart 版本：
+
+```shell
+helm upgrade <release-name> <chart-name> \
+ --version <chart-version> \
+ -n <namespace> \
+ -f values.yaml
+```
-默认情况下，服务名称、租户 ID、collector 和 batch span processor
的配置已预配置在[默认配置](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua)中。
+## 配置
-你可以通过端点 `apisix/admin/plugin_metadata/opentelemetry` 更改插件的配置，例如：
+`opentelemetry` 插件从插件元数据中读取插件级配置。通过端点
`/apisix/admin/plugin_metadata/opentelemetry` 配置插件元数据，例如：
:::note
你可以从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
@@ -109,18 +143,6 @@ apisix:
tracing: true
```
-### 启用 opentelemetry 插件
-
-默认情况下，APISIX 中的 `opentelemetry` 插件是禁用的。要启用它，请将插件添加到配置文件中，如下所示：
-
-```yaml title="config.yaml"
-plugins:
- - ...
- - opentelemetry
-```
-
-重新加载 APISIX 以使更改生效。
-
### 将 Traces 上报到 OpenTelemetry
以下示例展示了如何追踪对路由的请求并将 traces 发送到 OpenTelemetry。
