#OTel

OpenTelemetry (OTel) 是一个开源项目，旨在为分布式系统（如微服务架构）中遥测数据的收集、处理和导出提供厂商中立的标准。它帮助开发者更轻松地分析软件的性能和行为，从而促进应用问题的诊断和解决。

#术语

#前提条件

• 确保存在可用的 ALB：创建或使用已有的 ALB，本文档中 ALB 名称用 <otel-alb> 代替。有关创建 ALB 的操作步骤，请参见 Configure ALB。

• 确保有 OTel 数据上报服务器地址：该地址下文称为 <jaeger-server>。

#操作步骤

#更新 ALB 配置

1. 在集群的 Master 节点，使用 CLI 工具执行以下命令编辑 ALB 配置。

   kubectl edit alb2 -n cpaas-system <otel-alb> # 将 <otel-alb> 替换为实际的 ALB 名称

2. 在 spec.config 部分添加以下字段。

   otel:
     enable: true
     exporter:
       collector:
         address: '<jaeger-server>' # 将 <jaeger-server> 替换为实际的 OTel 数据上报服务器地址
         request_timeout: 1000

   完成后的示例配置：

   spec:
     address: 192.168.1.1
     config:
       otel:
        enable: true
        exporter:
          collector:
            address: "http://jaeger.default.svc.cluster.local:4318"
            request_timeout: 1000
       antiAffinityKey: system
       defaultSSLCert: cpaas-system/cpaas-system
       defaultSSLStrategy: Both
       gateway:
       ...
   type: nginx

3. 执行以下命令保存更新。更新后，ALB 默认启用 OpenTelemetry，所有请求的 Trace 信息将上报至 Jaeger Server。

   :wq

#相关操作

#在 Ingress 中配置 OTel

• 启用或禁用 Ingress 上的 OTel

  通过配置是否启用 Ingress 上的 OTel，可以更好地监控和调试应用的请求流，追踪请求在不同服务间的传播，定位性能瓶颈或错误。

  操作步骤

  在 Ingress 的 metadata.annotations 字段下添加如下配置：

  nginx.ingress.kubernetes.io/enable-opentelemetry: "true"

  参数说明：

  • nginx.ingress.kubernetes.io/enable-opentelemetry：设置为 true 表示 Ingress 控制器在处理该 Ingress 的请求时启用 OpenTelemetry 功能，即会收集并上报请求的 Trace 信息。设置为 false 或移除此注解，则不收集或上报请求 Trace 信息。

• 启用或禁用 Ingress 上的 OTel Trust

  OTel Trust 决定 Ingress 是否信任并使用来自请求的 Trace 信息（如 trace ID）。

  操作步骤

  在 Ingress 的 metadata.annotations 字段下添加如下配置：

  nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span: "true"

  参数说明：

  • nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span：设置为 true 时，Ingress 会继续使用已有的 Trace 信息，有助于保持跨服务追踪的一致性，使整个请求链路能在分布式追踪系统中完整追踪和分析。设置为 false 时，会为请求生成新的追踪信息，可能导致请求进入 Ingress 后被视为新的追踪链，打断跨服务追踪的连续性。

• 在 Ingress 上添加不同的 OTel 配置

  该配置允许针对不同的 Ingress 资源自定义 OTel 的行为和数据导出方式，实现对各服务追踪策略或目标的精细化控制。

  操作步骤

  在 Ingress 的 metadata.annotations 字段下添加如下配置：

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    annotations:
      alb.ingress.cpaas.io/otel: >
        {
           "enable": true,
           "exporter": {
               "collector": {
                   "address": "<jaeger-server>", # 将 <jaeger-server> 替换为实际的 OTel 数据上报服务器地址，例如 "address": "http://128.0.0.1:4318"
                   "request_timeout": 1000
               }
           }
        }

  参数说明：

  • exporter：指定如何将采集到的 Trace 数据发送到 OTel Collector（OTel 数据上报服务器）。
  • address：指定 OTel Collector 的地址。
  • request_timeout：请求超时时间。

#在应用中使用 OTel

以下配置展示了完整的 OTel 配置结构，可用于定义如何启用和使用应用中的 OTel 功能。

在集群 Master 节点，使用 CLI 工具执行以下命令获取完整的 OTel 配置结构。

kubectl get crd alaudaloadbalancer2.crd.alauda.io -o json|jq ".spec.versions[2].schema.openAPIV3Schema.properties.spec.properties.config.properties.otel"

返回结果：

{
    "otel": {
        "enable": true
    }
    "exporter": {
        "collector": {
            "address": ""
          },
    },
    "flags": {
        "hide_upstream_attrs": false
        "notrust_incoming_span": false
        "report_http_request_header": false
        "report_http_response_header": false
    },
    "sampler": {
        "name": "",
        "options": {
            "fraction": ""
            "parent_name": ""
          },
      },
 }

参数说明：

#继承关系

默认情况下，如果 ALB 配置了某些 OTel 参数且 FT 未配置，则 FT 会继承 ALB 的参数作为自身配置；即 FT 继承 ALB 配置，而 Rule 可以继承 ALB 和 FT 的配置。

• ALB：ALB 上的配置通常是全局默认配置，可在此配置全局参数如 Collector 地址，供下层 FT 和 Rule 继承。

• FT：FT 可继承 ALB 配置，未配置的 OTel 参数将使用 ALB 配置。但 FT 也可进一步细化配置，例如可选择性地启用或禁用 FT 上的 OTel，而不影响其他 FT 或 ALB 的全局设置。

• Rule：Rule 可继承 ALB 和 FT 的配置，但也可进一步细化配置，例如某条 Rule 可选择不信任传入的 OTel Trace 信息，或调整采样策略。

操作步骤

通过在 ALB、FT 和 Rule 的 YAML 文件中配置 spec.config.otel 字段，添加 OTel 相关配置。

#附加说明

#采样策略

#Attributes

• Resource Attributes

  这些属性默认上报。

  参数	说明
  hostname	ALB Pod 的主机名
  service.name	ALB 的名称
  service.namespace	ALB 所在的命名空间
  service.type	默认值为 ALB
  service.instance.id	ALB Pod 的名称

• Span Attributes

  • 默认上报的属性：

    参数	说明
    http.status_code	状态码
    http.request.resend_count	重试次数
    alb.rule.rule_name	本次请求匹配的规则名称
    alb.rule.source_type	本次请求匹配的规则类型，目前仅支持 Ingress
    alb.rule.source_name	Ingress 名称
    alb.rule.source_ns	Ingress 所在命名空间

  • 默认上报但可通过修改 flag.hide_upstream_attrs 字段排除的属性：

    参数	说明
    alb.upstream.svc_name	流量转发的 Service（内部路由）名称
    alb.upstream.svc_ns	流量转发的 Service（内部路由）所在命名空间
    alb.upstream.peer	被转发 Pod 的 IP 地址和端口

  • 默认不上报但可通过修改 flag.report_http_request_header 字段上报的属性：

    参数	说明
    **http.request.header.<header>**	请求头

  • 默认不上报但可通过修改 flag.report_http_response_header 字段上报的属性：

    参数	说明
    **http.response.header.<header>**	响应头

#配置示例

以下 YAML 配置部署了一个 ALB，并使用 Jaeger 作为 OTel 服务器，Hotrod-proxy 作为示范后端。通过配置 Ingress 规则，当客户端请求 ALB 时，流量将转发至 HotROD。同时，HotROD 内部微服务间的通信也通过 ALB 路由。

1. 将以下 YAML 保存为名为 all.yaml 的文件。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: hotrod
   spec:
     replicas: 1
     selector:
       matchLabels:
         service.cpaas.io/name: hotrod
         service_name: hotrod
     template:
       metadata:
         labels:
           service.cpaas.io/name: hotrod
           service_name: hotrod
       spec:
         containers:
           - name: hotrod
             env:
               - name: PROXY_PORT
                 value: '80'
               - name: PROXY_ADDR
                 value: 'otel-alb.default.svc.cluster.local:'
               - name: OTEL_EXPORTER_OTLP_ENDPOINT
                 value: 'http://jaeger.default.svc.cluster.local:4318'
             image: theseedoaa/hotrod-with-proxy:latest
             imagePullPolicy: IfNotPresent
             command: ['/bin/hotrod', 'all', '-v']
   ---
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: hotrod-frontend
   spec:
     ingressClassName: otel-alb
     rules:
       - http:
           paths:
             - backend:
                 service:
                   name: hotrod
                   port:
                     number: 8080
               path: /dispatch
               pathType: ImplementationSpecific
             - backend:
                 service:
                   name: hotrod
                   port:
                     number: 8080
               path: /frontend
               pathType: ImplementationSpecific
   ---
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: hotrod-customer
   spec:
     ingressClassName: otel-alb
     rules:
       - http:
           paths:
             - backend:
                 service:
                   name: hotrod
                   port:
                     number: 8081
               path: /customer
               pathType: ImplementationSpecific
   ---
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: hotrod-route
   spec:
     ingressClassName: otel-alb
     rules:
       - http:
           paths:
             - backend:
                 service:
                   name: hotrod
                   port:
                     number: 8083
               path: /route
               pathType: ImplementationSpecific
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: hotrod
   spec:
     internalTrafficPolicy: Cluster
     ipFamilies:
       - IPv4
     ipFamilyPolicy: SingleStack
     ports:
       - name: frontend
         port: 8080
         protocol: TCP
         targetPort: 8080
       - name: customer
         port: 8081
         protocol: TCP
         targetPort: 8081
       - name: router
         port: 8083
         protocol: TCP
         targetPort: 8083
     selector:
       service_name: hotrod
     sessionAffinity: None
     type: ClusterIP
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: jaeger
   spec:
     replicas: 1
     selector:
       matchLabels:
         service.cpaas.io/name: jaeger
         service_name: jaeger
     template:
       metadata:
         labels:
           service.cpaas.io/name: jaeger
           service_name: jaeger
       spec:
         containers:
           - name: jaeger
             env:
               - name: LOG_LEVEL
                 value: debug
             image: jaegertracing/all-in-one:1.58.1
             imagePullPolicy: IfNotPresent
         hostNetwork: true
         tolerations:
           - operator: Exists
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: jaeger
   spec:
     internalTrafficPolicy: Cluster
     ipFamilies:
       - IPv4
     ipFamilyPolicy: SingleStack
     ports:
       - name: http
         port: 4318
         protocol: TCP
         targetPort: 4318
     selector:
       service_name: jaeger
     sessionAffinity: None
     type: ClusterIP
   ---
   apiVersion: crd.alauda.io/v2
   kind: ALB2
   metadata:
     name: otel-alb
   spec:
     config:
       loadbalancerName: otel-alb
       otel:
         enable: true
         exporter:
           collector:
             address: 'http://jaeger.default.svc.cluster.local:4318'
             request_timeout: 1000
       projects:
         - ALL_ALL
       replicas: 1
       resources:
         alb:
           limits:
             cpu: 200m
             memory: 2Gi
           requests:
             cpu: 50m
             memory: 128Mi
         limits:
           cpu: '1'
           memory: 1Gi
         requests:
           cpu: 50m
           memory: 128Mi
     type: nginx

2. 在 CLI 工具中执行以下命令，部署 Jaeger、ALB、HotROD 及所有测试所需的 CR。

   kubectl apply ./all.yaml

3. 执行以下命令获取 Jaeger 的访问地址。

   export JAEGER_IP=$(kubectl get po -A -o wide |grep jaeger | awk '{print $7}');echo "http://$JAEGER_IP:16686"

4. 执行以下命令获取 otel-alb 的访问地址。

   export ALB_IP=$(kubectl get po -A -o wide|grep otel-alb | awk '{print $7}');echo $ALB_IP

5. 执行以下命令通过 ALB 向 HotROD 发送请求，此时 ALB 会将 Trace 上报至 Jaeger。

   curl -v "http://<$ALB_IP>:80/dispatch?customer=567&nonse=" # 将命令中的 <$ALB_IP> 替换为上一步获取的 otel-alb 访问地址

6. 打开第 步骤 3 中获取的 Jaeger 访问地址查看结果。