配置

Collector扩容

默认情况下，仅创建一个Collector的实例，当Collector资源不足以支持监控需求时，需要对Collector进行扩容。

首先，确保集群内空闲的资源大于扩容的Collector需要最小消耗的资源：每个Collector消耗 2Core CPU和8G内存。

推荐方式

通过修改安装探针时的yaml文件方式扩容。

修改tingyunagent.yaml内tingyun-collector的replicas数量。

---
# 必选项-collector
# collector StatefulSet

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: tingyun-collector
  namespace: tingyun
spec:
  replicas: 1  # 修改此处
  serviceName: tingyun-collector

然后使用yaml文件更新。

kubectl apply -f tingyunagent.yaml

命令方式

如果安装时的yaml文件已丢失，请使用以下命令扩容。

kubectl edit StatefulSet tingyun-collector -n tingyun

您会看到类似以下界面，修改tingyun-collector的replicas数量，保存并退出。

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: tingyun-collector
  namespace: tingyun
  resourceVersion: "29435"
  uid: e078cf79-ee84-43cd-a3fb-a9d6efe9c878
spec:
  podManagementPolicy: OrderedReady
  replicas: 1          # 修改此处

启用激进的嵌码模式

请在部署管理页面，使用报表开关 "APM激进模式" 开启激进的嵌码模式

启用自定义匹配规则的嵌码模式

默认情况下，必须首先对Namespace打label，然后对Pod打label，才能对Pod嵌入探针。

但在某些定制的 Kubernetes 管理平台， 没有提供对特定Pod打label的途径，此时可以通过定制webhook的对象选择器对特定的Pod嵌码。

首先参考启用激进的嵌码模式步骤，将tingyunagent.yaml内tingyun-common-config的apm_aggressive配置为true。

然后修改tingyun-agent-webhook的对象选择器objectSelector, 具体objectSelector的匹配规则可以根据实际情况进行修改。

---
# APM探针-Webhook, 需要集群管理员权限安装
# register webhook

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
metadata:
  name: tingyun-agent-webhook
  labels:
    app: tingyun-webhook
webhooks:
- name: tingyun-webhook-service.tingyun.svc
  namespaceSelector:
    matchLabels:
      tingyun-injection: enabled
  objectSelector:                 # 增加的部分
    matchExpressions:             # 增加的部分
      - key: app                  # 修改此处
        operator: In              # 增加的部分
        values:                   # 增加的部分
          - "匹配值1"             # 修改此处
          - "匹配值2"             # 修改此处

然后使用yaml文件更新。

kubectl apply -f tingyunagent.yaml

更改pod内的探针配置文件

默认情况下，所有Pod的探针配置文件都是一样的，因为配置文件均是从探针原始镜像内复制出来的。Pod初始化阶段，探针提供了shell脚本接口，您可以通过更改configmap内的pod-init.sh来修改探针配置文件。

修改配置后会动态生效，但有一定的延迟，延迟时间依赖kubelet的启动参数--sync-frequency，默认值是1分钟，所以更新ConfigMap的内容后，需等待2分钟左右。

推荐方式

通过修改安装探针时的yaml文件方式更改脚本。

修改tingyunagent.yaml内tingyun-injector-config的pod-init.sh。

# APM探针-探针配置文件
# configmap.yaml
# tingyun-agent 配置项

apiVersion: v1
kind: ConfigMap
metadata:
  name: tingyun-injector-config
  namespace: tingyun
data:
  pod-init.sh: |
    #!/bin/sh
    modifyConfig() {
      sed -i -e "/$2=/d" "$1"
      echo "$2=$3" >> "$1"
      grep "$2=" "$1"
    }
    echo "TINGYUN_APP_NAME=${TINGYUN_APP_NAME}"
    if [ "${TINGYUN_APP_NAME}" = "www.tomcat.com(test)" ]; then
        modifyConfig "${JAVA_AGENT_CONF}" "agent_log_level" "debug"
    fi

然后使用yaml文件更新。

kubectl apply -f tingyunagent.yaml

命令方式

如果安装时的yaml文件已丢失，请使用以下命令更改脚本。

kubectl edit configmap tingyun-injector-config -n tingyun

进入configmap修改界面，修改其中pod-init.sh脚本。

脚本中可用的环境变量包括：

变量名	对应文件
ONEAGENT_CONF	oneagent.conf
JAVA_AGENT_CONF	java.conf
PHP_AGENT_CONF	php.conf
NETCORE_AGENT_CONF	netcore.conf
NGINX_AGENT_CONF	nginx.conf
PYTHON_AGENT_CONF	python.conf
NODEJS_AGENT_CONF	nodejs.conf
GO_AGENT_CONF	go.conf
BLACK_LIST_CONF	blacklist.txt
INTERCEPTOR_CONF	interceptor.conf

例如，如果要打开Namespace名称为test，Deployment名称为mysite的Pod内Java探针的debug日志，配置如下：

pod-init.sh: |
    #!/bin/sh
    modifyConfig() {
      sed -i -e "/$2=/d" "$1"
      echo "$2=$3" >> "$1"
      grep "$2=" "$1"
    }
    if [ "${TINGYUN_APP_NAME}" = "mysite(test)" ]; then
        modifyConfig "${JAVA_AGENT_CONF}" "agent_log_level" "debug"
    fi

例如， 如果要打开所有Pod内Java探针的debug日志，配置如下：

pod-init.sh: |
    #!/bin/sh
    modifyConfig() {
      sed -i -e "/$2=/d" "$1"
      echo "$2=$3" >> "$1"
      grep "$2=" "$1"
    }
    modifyConfig "${JAVA_AGENT_CONF}" "agent_log_level" "debug"

例如，nginx探针应用命名默认是按照server_name:port命名, 如果想将nginx探针应用名改成和Java应用一样的命名格式:workload(namespace)，配置如下：

  pod-init.sh: |
    #!/bin/sh
    modifyConfig() {
      sed -i -e "/$2=/d" "$1"
      echo "$2=$3" >> "$1"
      grep "$2=" "$1"
    }
    modifyConfig "${NGINX_AGENT_CONF}" "naming_mode" "5"
    modifyConfig "${NGINX_AGENT_CONF}" "host_ip" "${TINGYUN_APP_NAME}"

查看pod启动时的pod-init.sh日志

pod-init.sh日志在Pod的init容器的日志里面。

kubectl logs [pod名称] -c tingyun-oneagent -n [应用所在namespace]

探针的pod-init.sh脚本是如何保证不会破坏客户应用pod的？

pod-init.sh运行时的Container不是客户应用所在的Container，而是独立启动的Container，无论运行什么样的破坏性脚本，包括 rm -rf / ，均是在独立的Container内运行，相当于一个安全沙盒，不会对客户应用造成任何影响。

pod-init.sh是唯一的可以对探针执行修改的入口，脚本运行完之后，才会将探针及配置文件拷贝到客户应用的Pod内。

限制同一Workload内Pod嵌码的数量

限量功能仅支持 Kubernetes 1.15 及以上版本。

默认情况下，如果开启了对某一Workload嵌码，此Workload下所有Pod均会被嵌码。探针提供了可选的嵌码数量限制功能，在此功能开启的情况下仅嵌入指定数量的探针。

开启限制同一Workload内Pod嵌码的数量的原理是通过API Server读取Pod列表及Pod的标签判断是否已嵌码，所以Webhook上的嵌码时间和资源消耗会比不限量时更高。

修改配置后会动态生效，但有一定的延迟，延迟时间依赖kubelet的启动参数--sync-frequency，默认值是1分钟，所以更新ConfigMap的内容后，需等待2分钟左右。

推荐方式

通过修改安装探针时的yaml文件方式启用。

修改tingyunagent.yaml内tingyun-injector-config的policy.yaml，将其中的limit: disabled修改为limit: enabled。

maxcountPerWorkload 限定每个Workload下最多的嵌码数量，如果需要自定义个别Workload下的嵌码数量，需修改限制规则rules。定义如下：

• namespace：Workload部署的Namespace名称。
• kind：Workload的类型，常见的3个类型: deployment, daemonset, statefulset。
• name：Workload的名称。
• max：Workload内Pod嵌码的最大数量。

例如：

# APM探针-探针配置文件
# configmap.yaml
# tingyun-agent 配置项

apiVersion: v1
kind: ConfigMap
metadata:
  name: tingyun-injector-config
  namespace: tingyun
data:
  policy.yaml: |
    limit: enabled
    maxcountPerWorkload: 99
    rules:
    - namespace: test
      kind: deployment
      name: www.tomcat.com
      max: 1
    - namespace: test
      kind: daemonset
      name: www.tomcat.com
      max: 1
    - namespace: test
      kind: statefulset
      name: www.tomcat.com
      max: 1

然后使用yaml文件更新。

kubectl apply -f tingyunagent.yaml

命令方式

如果安装时的yaml文件已丢失，请使用以下命令启用。

kubectl edit configmap tingyun-injector-config -n tingyun

您会看到类似以下界面，将policy.yaml的limit: disabled修改为limit: enabled，并增加限制规则，保存并退出。

apiVersion: v1
data:
  policy.yaml: |
    limit: enabled
    maxcountPerWorkload: 99
    rules:
    - namespace: test
      kind: deployment
      name: www.tomcat.com
      max: 1
    - namespace: test
      kind: daemonset
      name: www.tomcat.com
      max: 1
    - namespace: test
      kind: statefulset
      name: www.tomcat.com
      max: 1

特定的Workload拉取特定版本探针的镜像

默认情况下，Workload嵌入的探针版本为tingyunagent.yaml内tingyun-injector-config中initContainers指定的镜像版本。

例如下面的配置，默认拉取的探针版本为2.3.0.0，拉取地址为goinline.cn/tingyunagent/oneagent:2.3.0.0。

apiVersion: v1
kind: ConfigMap
metadata:
  name: tingyun-injector-config
  namespace: tingyun
data:
  mutate.yaml: |
    initContainers:
    - name: tingyun-oneagent
      image: goinline.cn/tingyunagent/oneagent:2.3.0.0
      imagePullPolicy: IfNotPresent

当需要对特定的Workload拉取特定版本探针的镜像时，修改Workload yaml内的labels，将 tingyun-oneagent-version 设置为指定版本号。

注意：如果是从私有镜像库拉取特定版本的镜像，一定要确认此版本在镜像库内存在，否则会导致Workload启动失败。

以Tomcat部署的Deployment为例，配置如下：

apiVersion: apps/v1
kind: Deployment
metadata:
name: demo1
namespace: default
spec:
selector:
  matchLabels:
    app: demo1
template:
  metadata:
    labels:
      tingyun-agent-injected: "true"
      tingyun-oneagent-version: "2.3.2.0"      # 指定探针版本为2.3.2.0
  spec:
    containers:
    - name: demo1
      image: tomcat

tingyun-oneagent-version 指定版本为 2.3.2.0 ，此Workload下会拉取 goinline.cn/tingyunagent/oneagent:2.3.2.0 的探针镜像。

injector镜像版本2.4.6.0 及以上版本支持在探针的policy.yaml内指定特定的Workload的探针镜像，配置方法为：

修改Kubernetes探针内名称为tingyun-injector-config的ConfigMap内容,在policy.yaml内agentVersions列表指定特定的Workload加载对应的探针镜像。

其中appName格式为workload名称(NameSpace名称)，oneagentTag为oneagent镜像的Tag名称。

例如下面配置时，名称为busybox的Workload下会拉取 oneagent:2.4.3.0 的探针镜像。

apiVersion: v1
kind: ConfigMap
metadata:
  name: tingyun-injector-config
  namespace: ${NameSpace}
data:
  policy.yaml: |
    agentVersions:
    - appName: busybox(test)
      oneagentTag: 2.4.3.0

注意：如果是从私有镜像库拉取特定版本的镜像，一定要确认此版本在镜像库内存在，否则会导致Workload启动失败。

从业务Pod的label内获取应用名称

默认情况下，应用名称为Workload的名称，但在某些基于kubenetes定制的平台上，通过Web页面部署时，Workload的名称会附加上版本号、日期等内容，造成每重新部署一次，应用名称就会变更一次。此时可能需要通过获取Pod内的特定label作为应用名称，配置方法如下：

修改tingyun-agent的yaml，增加环境变量NAMING_BY_LABEL，值为Pod内的特定label名称。

例如：

describe 业务Pod 如下，需要获取label里面的applicationName作为应用名称：

kubectl describe pod boe-fcc-expense-v1-1439-6349f45-lzdx6

Start Time:       Wed, 12 Apr 2023 10:22:03 +0800
Labels:           applicationName=boe-fcc-expense
                  versionName=boe-fcc-expense-v1-1439
                  pod-template-hash=856c4586d5

配置方法如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tingyun-agent
  namespace: tingyun
  labels:
    app: tingyun-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tingyun-agent
  template:
    metadata:
      labels:
        app: tingyun-agent
    spec:
      containers:
        - name: tingyun-agent
          image: tingyunagent/injector:2.4.3.0
          imagePullPolicy: Always
          args:
          - -commonCfgFile=/etc/tingyun/conf/tingyun-common.yaml
          - -mutateCfgFile=/etc/tingyun/injector/mutate.yaml
          - -podInitFile=/etc/tingyun/injector/pod-init.sh
          - -policyFile=/etc/tingyun/injector/policy.yaml
          - -tlsCertFile=/etc/tingyun/certs/cert.pem
          - -tlsKeyFile=/etc/tingyun/certs/key.pem
          - -version=v1
          env:
          - name: SECURITY_CONTEXT_ENABLED
            value: 'false'
          - name: NAMING_BY_LABEL              # 增加环境变量NAMING_BY_LABEL
            value: 'applicationName'           # 增加环境变量value为applicationName

修改应用名称的格式

通过修改环境变量APP_NAMING_RULE设置自定义名称的格式，目前支持以下变量替换：

REPLACE_WITH_WORKLOAD_NAME: 会被替换为Workload名称

REPLACE_WITH_NAMESPACE: 会被替换为Namespace名称

如果没有环境变量定义APP_NAMING_RULE，默认值为REPLACE_WITH_WORKLOAD_NAME(REPLACE_WITH_NAMESPACE)

例如：

在测试环境上，将应用名称格式修改为 Workload名称-dev(Namespace名称)，配置方法如下：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tingyun-agent
  namespace: tingyun
  labels:
    app: tingyun-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tingyun-agent
  template:
    metadata:
      labels:
        app: tingyun-agent
    spec:
      containers:
        - name: tingyun-agent
          image: tingyunagent/injector:2.6.0.0
          imagePullPolicy: Always
          args:
          - -commonCfgFile=/etc/tingyun/conf/tingyun-common.yaml
          - -mutateCfgFile=/etc/tingyun/injector/mutate.yaml
          - -podInitFile=/etc/tingyun/injector/pod-init.sh
          - -policyFile=/etc/tingyun/injector/policy.yaml
          - -tlsCertFile=/etc/tingyun/certs/cert.pem
          - -tlsKeyFile=/etc/tingyun/certs/key.pem
          - -version=v1
          env:
          - name: SECURITY_CONTEXT_ENABLED
            value: 'false'
          - name: APP_NAMING_RULE              # 增加环境变量APP_NAMING_RULE
            value: 'REPLACE_WITH_WORKLOAD_NAME-dev(REPLACE_WITH_NAMESPACE)'

将应用namespace名称映射为听云业务系统名称

仅Kubernetes探针4.2.0 (injector镜像版本为4.0.1) 及以上版本支持。

通过修改mutate.yaml中环境变量TINGYUN_DEFAULT_BUSINESS_SYSTEM设置自定义名称的格式，目前支持以下变量替换：

REPLACE_WITH_NAMESPACE: 会被替换为应用Namespace名称

例如：

  mutate.yaml: |
    initContainers:
    - name: tingyun-oneagent
      env:
      - name: TINGYUN_DEFAULT_BUSINESS_SYSTEM
        value: REPLACE_WITH_NAMESPACE          # 替换为应用Namespace名称

更改Collector的配置文件

修改tingyunagent.yaml内tingyun-collector-config的collector.properties：

apiVersion: v1
kind: ConfigMap
metadata:
  name: tingyun-collector-config
  namespace: tingyun
data:
  collector.properties: |
    #
    # Collector 服务的监听端口.
    # 默认值: 7665
    collector.listen=7665
    #
    # 是否以https方式向DC发送数据.
    # 当 dc.ssl 设置为 true 时，Collector将以https方式向DC发送数据
    # 默认值: false
    dc.ssl=true
    #
    # 是否启用数据审计模式.
    # 这项设置是动态的，更改它您不需要重启Collector.
    # 当 audit_mode 设置为 true 时, 会将所有进出Collector的数据记录到日志文件.
    # 此功能比较消耗CPU，生产环境需要关闭此配置
    # 默认: false.
    collector.audit_mode=false

然后使用yaml文件更新。

kubectl apply -f tingyunagent.yaml

重建Collector pod。

kubectl delete pod tingyun-collector-0 -n tingyun

更改Collector的IP

仅Kubernetes探针2.4.3.0 (Collector镜像版本为3.6.6.3) 及以上版本支持。

在Kubernetes集群内部署Collector时，Collector默认会使用Pod的域名(tingyun-collector-0.tingyun-collector-service.tingyun)作为和探针通讯的地址。

当Kubernetes集群内的域名机制不能正常工作时，可通过配置Collector Pod的环境变量 TINGYUN_POD_IP 为指定IP，Collector会使用环境变量 TINGYUN_POD_IP 内指定的IP地址作为和探针通讯的地址。

修改tingyunagent.yaml内名称为tingyun-collector的StatefulSet描述：

删除tingyun-collector的env变量： TINGYUN_SERVICE_NAME、TINGYUN_POD_NAME 和 TINGYUN_POD_NAMESPACE

增加tingyun-collector的env变量： 名称为 TINGYUN_POD_IP 内容为 status.podIP

修改后的样例如下：

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: tingyun-collector
  namespace: tingyun
spec:
  replicas: 1
  serviceName: tingyun-collector-service
  selector:
    matchLabels:
      vendor: tingyun
      component: collector
  template:
    metadata:
      labels:
        vendor: tingyun
        component: collector
      name: tingyun-collector
    spec:
      containers:
      - name: agent-collector
        image: tingyunagent/collector:3.6.6.3
        resources:
          limits:
            cpu: "4"
            memory: "16Gi"
          requests:
            cpu: "2"
            memory: "8Gi"
        env:
          - name: RUN_IN_CONTAINER
            valueFrom:
              configMapKeyRef:
                name: tingyun-collector-config
                key: run_in_container
          - name: TINGYUN_POD_IP
            valueFrom:
              fieldRef:
                fieldPath: status.podIP
        volumeMounts:
        - name: config-vol
          mountPath: /tmp/cfg.yml
          subPath: cfg.yml
        - name: config-vol
          mountPath: /opt/tingyun-collector/infra/log4j.yml
          subPath: log4j.yml
        - name: config-vol
          mountPath: /opt/tingyun-collector/infra/rules.yml
          subPath: rules.yml
        - name: config-vol
          mountPath: /tmp/collector.properties
          subPath: collector.properties
        - name: config-vol
          mountPath: /opt/tingyun-collector/apm/ops-env.sh
          subPath: ops-env.sh
        - name: config-vol
          mountPath: /opt/tingyun-collector/infra/component/tingyun-env.sh
          subPath: tingyun-env.sh
        - name: config-vol
          mountPath: /opt/tingyun-collector/infra/component/oracle_exporter/oracle-env.sh
          subPath: oracle-env.sh
        - name: common-config-vol
          mountPath: /etc/tingyun/conf
          readOnly: true
      volumes:
      - name: config-vol
        configMap:
          name: tingyun-collector-config
      - name: common-config-vol
        configMap:
          name: tingyun-common-config