跳到主要内容

监控 Kubernetes 集群的服务器和应用使用OneAgent定制探针版本

最后 更新

APO 分为两部分:

  • APO-server: APO 服务侧组件
  • APO-one-agent: APO 用户侧组件,用于采集Kubernetes集群或者虚机环境下被监控业务以及集群、主机信息。

本文档包含配置 APO-one-agent 自定义 Java 探针,并使用使用 Helm Chart 在 Kubernetes 上安装和运行定制版镜像 APO-one-agent 的说明。请确保在安装 APO-one-agent 之前,您已经安装 APO-server

注意: 不建议用本文档的安装方式将 APO-server 与 APO-one-agnet 安装在同一 Kubernetes 集群中,会产生不必要的资源浪费;如果想要将 APO-server 与 APO-one-agent 部署在同一 Kubernetes 集群中,请参考快速开始文档

注意: 使用默认探针版本的 APO-one-agent ,可以根据监控 Kubernetes 集群中的服务器和应用使用OneAgent默认OTEL探针版本

APO-one-agent 内置各个编程语言的默认采集探针版本:

  1. Java agent: opentelemetry-java-instrumentation v2.5.0
  2. Python agent: opentelemetry-python 1.23.0/0.44b0
  3. NodeJs agent: opentelemetry-js v1.24.1/0.51.1
  4. Go agent: opentelemetry-go-instrumentation v0.13.0-alpha

注意: 目前只推荐使用 Skywalking 或者 OpenTelemetry 的 Java 探针;暂不支持除 Java 以外的语言的探针替换。

如何替换 APO-one-agent 中的 Java 探针

针对 Java 应用,APO-one-agent 默认集成了以下版本 Java 探针:

  • Opentelemetry v2.5.0(默认)

本文档介绍如何在安装 APO-one-agent 时使用其他 Java 探针版本。

如果默认集成的探针版本不满足你的需求,参考下面的步骤构建自定义的 APO-one-agent 中的探针镜像;这样你可以使用比如 Skywalking v9.2.0 或 Opentelemetry v2.2.0 之类的其他版本探针。

1. 下载 OneAgent builder 模版

下载地址: https://apo-ce.oss-cn-hangzhou.aliyuncs.com/preload-builder.zip

模版的文件目录结构如下:

preload-builder
├── opentelemetry-java
│ ├── Dockerfile
│ ├── libapoinstrument.conf
│ └── opentelemetry
│ └── opentelemetry-javaagent.jar
└── skywalking-java
├── Dockerfile
├── libapoinstrument.conf
└── skywalking-agent
├── ...
└── skywalking-agent.jar

2. 替换探针文件

注意: 你只需要替换自己需要的探针,不需要同时替换OTEL和Skywalking的探针

OTEL探针

OTEL的JAVA探针以单个Jar包的方式提供。

使用需要的版本的OTEL探针替换模版目录中的 opentelemetry-java/opentelemetry/opentelemetry-javaagent.jar 文件, 注意不要更改文件名。

Skywalking探针

从Skywalking官网获得的探针文件通常是一个包含有 skywalking-agent.jar 和其配置文件的文件夹;

推荐的做法是移除模版中的 skywalking-java/skywalking-agent 目录, 随后用官网下载的探针文件进行替换;

这是因为不同版本的 skywalking-agent.jar 和 其他文件可能不兼容, 完整替换是最安全的。

注意替换后不要更改skywalking-java/skywalking-agent/skywalking-agent.jar的文件名.

3. 构建镜像

如果使用的是自定义的OTEL探针

使用下面的脚本来进行探针构建

cd opentelemetry-java
docker build -t registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom .

如果使用的是自定义的Skywalking探针

使用下面的脚本来进行探针构建

cd skywalking-java
docker build -t registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom .

4. 同步镜像文件到机器

你需要将构建好的镜像文件推送到可用的Harbor仓库,或者手动同步到机器.

  • 推送到Harbor仓库(注意将脚本中的HARBOR_REGISTRY修改为仓库地址)
HARBOR_REGISTRY=#修改为仓库地址

docker tag registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet $HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom
docker push $HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom
  • 手动同步到机器
docker save registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom | gzip > apo-odiglet.tgz

将生成的文件复制到后续部署探针的机器上(如果是K8s环境需要复制到每个节点上) 在每个节点上执行下面的命令加载镜像

gunzip -c apo-odiglet.tgz | docker load 

5. 安装时使用新构建的镜像

完成上面的镜像推送步骤,你会获得一个可用的探针镜像版本:

  1. 如果你使用Harbor,后续使用$HARBOR_REGISTRY/originx/odigos-odiglet:latest-custom, 注意$HARBOR_REGISTRY修改为你的仓库地址
  2. 如果你是手动推送的,后续使用 registry.cn-hangzhou.aliyuncs.com/originx/odigos-odiglet:latest-custom
安装准备工作

使用 Helm 安装 APO,请确保已完成以下操作:

  • 在计算机上安装 Kubernetes 服务器。有关安装 Kubernetes 的信息,请参阅安装 Kubernetes

  • 安装 Helm 的最新稳定版本。有关安装 Helm 的信息,请参阅安装 Helm

  • 网络策略:需要 APO-one-agent 所在集群/机器能够访问 APO-server 集群的 30044、31363、30317、30319 端口。

设置 APO Helm 仓库

要设置 APO Helm 存储库,以便在计算机上下载正确的 APO Helm charts,请完成以下步骤: 使用下方命令添加 apo Helm 仓库

helm repo add apo https://apo-charts.oss-cn-hangzhou.aliyuncs.com
helm repo update apo
K8s 环境安装

安装 APO-one-agent 时,使用下面的参数以指定使用您的自定义版本镜像: 在安装前修改配置文件,更换配置中的镜像名以及tag

# apoServerIP 为 APO-server 所在的 ClusterIP
global:
apoServerIP: x.x.x.x # FIXME

# APO-one-agent enabled标志位,默认为 false
odigos:
config:
javaAgentType: otherveriosns
instrumentor:
# targetNamespace
# name:目标命名空间
# value:
# enabled: 注入现有的所有服务,但不注入后续新增应用
# enabledFuture: 注入现在以及后续的所有服务
# disabled: 不注入指定namespace下的服务,用于在instrument-all-namespace时忽略特定的Namespace
targetNamespace:
- name: default
value: enabledFuture
- name: default2
value: enabled
- name: default3
value: disabled
# instrument-all-namespace 是否注入所有namespace
# 等价于设置所有namespace的enabledFuture
# 但如果已经设置了ns或者workload的disabled将不会注入
instrumentAllNamespace: false
# force-instrument-all-namespace 是否强制注入所有namespace
# 和instrument-all-namespace类似,所有ns设置enabledFuture
# 并忽略所有disabled设置
forceInstrumentAllNamespace: false

# 如果您的自定义探针为skywalking版本,请加上这段配置
# apoOneAgent:
# config:
# javaAgentType: "skywalking"

odiglet:
image:
repository: "registry.cn-hangzhou.aliyuncs.com/originx/apo-odiglet" # FIXME
tag: "latest-custom" # FIXME 本文档打包默认tag为latest-custom,如果您打包时tag有修改,请同步为您的自定义tag

这里提供的为 APO 部署的基础配置,如果您要进行更多配置更改,请从 APO Helm Charts 库中下载values.yaml文件:

helm show values apo/apo-one-agent > values.yaml
部署 APO-one-agent

运行以下命令,在指定命名空间中部署 APO 。

helm install apo-one-agent apo/apo-one-agent -n apo --create-namespace \
-f apo-one-agent-values.yaml
验证

见到类似输出既代表安装成功

NAME: apo-one-agent
LAST DEPLOYED: Fri Aug 9 09:33:16 2024
NAMESPACE: apo
STATUS: deployed
REVISION: 1
NOTES:
=======================================
___ ___ ___
/\ \ /\ \ /\ \
/::\ \ /::\ \ /::\ \
/:/\:\ \ /:/\:\ \ /:/\:\ \
/::\~\:\ \ /::\~\:\ \ /:/ \:\ \
/:/\:\ \:\__\ /:/\:\ \:\__\ /:/__/ \:\__\
\/__\:\/:/ / \/__\:\/:/ / \:\ \ /:/ /
\::/ / \::/ / \:\ /:/ /
/:/ / \/__/ \:\/:/ /
/:/ / \::/ /
\/__/ \/__/
Official Website: https://apo.kindlingx.com/

输入下方命令检查pod是否启动成功

kubectl get po -n apo

# 您应该看到类似于以下内容的输出
NAME READY STATUS RESTARTS AGE
apo-odigos-instrumentor-7f96957cb6-6sq2r 1/1 Running 0 5m
apo-one-agent-vbkzl 7/7 Running 0 5m
apo-otel-collector-85bdfd5898-fgcbf 1/1 Running 0 5m
卸载 APO-one-agent
helm uninstall apo-one-agent -n apo
kubectl delete ns apo

探针配置变更(高级功能)

注意: 如果你没有修改配置的需求,可以跳过这一部分. APO和提供的模版已经配置好了基础参数.

在大多数时候,你不需要考虑探针的配置问题, preload通过一定的逻辑为探针配置了必须的两个参数:

  • 服务名 (OTEL_SERVICE_NAME/SW_AGENT_NAME): 由 jar 包或主类名生成
  • 数据发送地址 (OTEL_EXPORTER_OTLP_ENDPOINT/ SW_AGENT_COLLECTOR_BACKEND_SERVICES): 由 apo 的部署文件进行维护

其余参数均使用探针的自身的默认配置

如果需要修改默认参数, 可以参考下面的内容修改模版中对应的libapoinstrument.conf文件 以下面的示例模版为例, 每个模版中包含三个文件或目录, 其中AAAA/BBBB都是泛指,即不限定文件名:

  • Dockerfile: 决定了要更新preload-agent镜像中的哪些文件,通常不需要修改
  • libapoinstrument.conf: 决定了使用探针时的配置
  • BBBB目录: 包含自定义探针的可执行文件和自带配置
preload-builder
└── AAAA
├── Dockerfile
├── libapoinstrument.conf
└── BBBB
└── CCCC.jar

构建镜像时

  • AAAA目录下的所有文件将被复制到镜像的/etc/apo/instrumentations/custom/目录下;
  • libapoinstrument.conf中的所有配置会替换镜像中已有的配置.

libapoinstrument.conf 配置说明

以 opentelemetry 的配置为例, 模版中的的配置文件如下:

[java]
OTEL_SERVICE_NAME={{APO_AUTO_SERVICE_NAME}}
OTEL_EXPORTER_OTLP_ENDPOINT= {{APO_COLLECTOR_GRPC_ENDPOINT}}
JAVA_TOOL_OPTIONS=-javaagent:/etc/apo/instrumentations/custom/opentelemetry/opentelemetry-javaagent.jar
JAVA_OPTS=-javaagent:/etc/apo/instrumentations/custom/opentelemetry/opentelemetry-javaagent.jar
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_TRACES_SAMPLER=always_on
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none

下面是配置的说明:

  • [java] 作为一小节的开头,标识本节的所有配置作为java程序启动时自动注入的环境变量; 目前支持 java/python/nodejs/dotnet 四种语言
  • OTEL_SERVICE_NAME={{APO_AUTO_SERVICE_NAME}}, 因为服务名信息需要在应用启动时动态生成,所以使用APO提供的动态变量{{APO_AUTO_SERVICE_NAME}}来替换.可用的动态参数如下
    • APO_AUTO_SERVICE_NAME: 自动发现服务名,目前仅支持JAVA,python/nodejs/dotnet会用对应的语言名作为APO_AUTO_SERVICE_NAME
    • APO_COLLECTOR_GRPC_ENDPOINT APO的OtelCollector地址,接收otlp协议数据
    • APO_COLLECTOR_HTTP_ENDPOINT 同上,接收otlphttp协议数据
    • APO_COLLECTOR_SKYWALKING_ENDPOINT 同上,接收skywalking协议数据
  • JAVA_TOOL_OPTIONS=-javaagent:/etc/apo/instrumentations/custom/BBBB/CCCC.jar, 因为模版目录下的文件全部会复制到镜像的/etc/apo/instrumentations/custom/目录下,所以用这个绝对路径来指定探针的文件
  • 其他参数为静态参数,将直接作为环境变量添加到程序启动, 下面的文档提供了如何使用环境变量设置探针参数

OTEL的自定义配置参考下面的文档 Configuration

Skywalking的自定义配置参考下面的文档 Setting Override