公共配置¶

本页以应用与 DataKit 同机部署为例，说明 Beacon 的接收端配置。跨主机或容器部署时，将 127.0.0.1 替换为应用可访问的 DataKit 地址，并调整 DataKit 监听地址。

开启 DataKit 采集器¶

先安装 DataKit并确保其已连接目标工作空间。默认安装路径下，复制 OpenTelemetry 示例配置：

sudo cp /usr/local/datakit/conf.d/samples/opentelemetry.conf.sample \
  /usr/local/datakit/conf.d/opentelemetry.conf

编辑该文件，确认保留以下接收配置；若已存在对应配置，修改原配置即可，不要重复添加采集器：

[[inputs.opentelemetry]]
  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"
  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"

完成后重启 DataKit。HTTP 使用 DataKit HTTP 服务端口，默认 9529。跨主机接入时，还需调整 HTTP 服务监听地址及 gRPC addr，并通过网络策略限制访问范围。Kubernetes 配置及完整参数见 OpenTelemetry 采集器。

服务标识与 OTLP 参数¶

上报至 DataKit 时，建议先使用 env、version 标识环境与版本。其他自定义资源属性如需作为标签保留，应加入 OpenTelemetry 采集器的 customer_tags 白名单；属性名中的 . 会转换为 _。

export OTEL_SERVICE_NAME=order-service
export OTEL_RESOURCE_ATTRIBUTES=env=prod,version=1.0.0
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317

export OTEL_SERVICE_NAME=order-service
export OTEL_RESOURCE_ATTRIBUTES=env=prod,version=1.0.0
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel

HTTP 通用地址会按信号追加 /v1/traces、/v1/metrics 或 /v1/logs；DataKit HTTP 地址需保留 /otel 前缀。DataKit OTLP/HTTP 仅支持 Protobuf，请使用 http/protobuf。

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 等信号专用变量优先于通用地址。使用信号专用变量时，HTTP 地址必须填写完整路径，例如 http://127.0.0.1:9529/otel/v1/traces。gRPC 地址不要追加 HTTP 路径。

上述配置应注入实际应用进程。systemd、容器和 PHP-FPM 不一定继承当前终端环境；配置后需重新启动应用。认证信息应通过部署平台的 Secret 注入，避免写入代码库。

Profile 与 Security¶

• Profile：先开启 DataKit Profile 采集器，上传地址为 http://127.0.0.1:9529/profiling/v1/input。Java 使用 JFR，Python 和 Node.js 使用 pprof，详见各语言接入页。
• Security：默认关闭，支持的语言使用现有探针并通过 OTLP Logs 上报。按 Security 配置运行时范围与导出参数后，在「日志」中验证记录。

验证接入¶

1. 从应用运行环境执行以下命令，检查 DataKit HTTP 服务可达。该检查不验证 4317 端口或采集器是否开启。

   curl -f http://127.0.0.1:9529/v1/ping
   

2. 按对应语言指南启动应用，检查探针已加载且没有 OTLP 导出错误。

3. 访问经过受支持 Web 框架、HTTP 客户端或数据库的应用接口，产生真实请求。
4. 在观测云「应用性能监测 > 链路」中选择当前时间范围，按 service 筛选服务名；指标需等待至少一个导出周期。
5. 已开启 Profile 时，保持应用运行超过采集周期，再进入「应用性能监测 > Profiling」按服务名检查。已开启 Security 时，在「日志」中检查对应服务的记录。

查询不到数据时，参见故障排查。