Alauda Container Platform
简体中文

OTel

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

目录

术语

术语说明
Trace提交到 OTel 服务器的数据，是一组相关事件或操作的集合，用于跟踪分布式系统中请求的流动；每个 Trace 由多个 Span 组成。
SpanTrace 中的一个独立操作或事件，包括开始时间、持续时间和其他相关信息。
OTel Server能够接收和存储 Trace 数据的 OTel 服务器，如 Jaeger、Prometheus 等。
Jaeger一种开源分布式追踪系统，用于监控和排查微服务架构，支持与 OpenTelemetry 的集成。
Attributes附加到 Trace 或 Span 的键值对，以提供额外的上下文信息。包括资源属性和 Span 属性；有关更多信息，请参见 Attributes。
Sampler一种策略组件，用于决定是否对 Trace 进行采样和报告。可以配置不同的采样策略，如全量采样、比例采样等。
ALB（另一个负载均衡器）分配网络请求到集群中可用节点的软件或硬件设备；平台使用的负载均衡器（ALB）是一个第七层软件负载均衡器，能够配置监控流量并使用 OTel。ALB 支持将 Traces 提交到指定的收集器，并允许配置不同的采样策略；它还支持配置是否在 Ingress 层提交 Traces。
FT（前端）ALB 的端口配置，指定端口级别的配置。
Rule在端口（FT）上的路由规则，用于匹配特定路由。
HotROD（按需乘车）Jaeger 提供的示例应用程序，用于演示分布式追踪的使用；有关更多详细信息，请参考 Hot R.O.D. - Rides on Demand。
hotrod-with-proxy通过环境变量指定 HotROD 内部微服务的地址；有关更多详细信息，请参考 hotrod-with-proxy。

先决条件

  • 确保操作性的 ALB 存在：创建或使用现有的 ALB，本文件中 ALB 的名称用 <otel-alb> 替换。有关创建 ALB 的说明，请参考 Creating Load Balancer。

  • 确保存在 OTel 数据报告服务器地址：该地址在此后称为 <jaeger-server>。

步骤

更新 ALB 配置

  1. 在集群的主节点上，使用 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 服务器。

    :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 控制器在处理请求时启用 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 配置

    此配置允许您自定义 OTel 的行为和数据导出方法，以便对不同的 Ingress 资源进行细粒度的追踪策略或目标控制。

    步骤

    在 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 收集器（OTel 数据报告服务器）。
    • address：指定 OTel 收集器的地址。
    • request_timeout：指定请求超时时间。

在应用程序中使用 OTel

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

在集群主节点上，使用 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": "" }, }, }

参数说明：

参数描述
otel.enable是否启用 OTel 功能。
exporter.collector.addressOTel 数据报告服务器的地址，支持 http/https 协议和域名。
flags.hide_upstream_attrs是否报告关于上游规则的信息。
flag.notrust_incoming_span是否信任并使用来自传入请求的 OTel Trace 信息（例如 trace ID）。
flags.report_http_request_header是否报告请求头。
flags.report_http_response_header是否报告响应头。
sampler.name采样策略名称；有关详细信息，请参见 Sampling Strategies。
sampler.options.fraction采样率。
sampler.options.parent_name父级基于采样策略的父策略。

继承

默认情况下，如果 ALB 配置了某些 OTel 参数且 FT 未配置，则 FT 将从 ALB 继承参数作为其配置；即 FT 继承 ALB 的配置，Rules 可以从 ALB 和 FT 两者继承配置。

  • ALB：ALB 上的配置通常是全局的和默认的。在此可以配置例如 Collector 地址等全局参数，这些参数将被下级 FT 和 Rules 继承。

  • FT：FT 可以从 ALB 继承配置，这意味着未在 FT 中配置的某些 OTel 参数将使用来自 ALB 的配置。然而，FT 也可以进一步细化；例如，您可以选择在 FT 上选择性地启用或禁用 OTel，而不影响其他 FT 或 ALB 的全局设置。

  • Rule：Rule 可以从 ALB 和 FT 两者继承配置。然而，Rule 也可以进一步细化；例如，特定的 Rule 可以选择不信任传入的 OTel Trace 信息或调整采样策略。

步骤

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

附加说明

采样策略

参数说明
always on始终报告所有追踪数据。
always off从不报告追踪数据。
traceid-ratio根据 traceid 决定是否报告。traceparent 的格式为 xx-traceid-xx-flag，其中 traceid 的前 16 个字符代表一个 32 位的十六进制整数。如果此整数小于 fraction 乘以 4294967295（即 (2^32-1)），则将被报告。
parent-base根据请求中 traceparent 的标志部分决定是否报告。当标志为 01 时，将被报告；例如：curl -v "http://$ALB_IP/" -H 'traceparent: 00-xx-xx-01'；当标志为 02 时，将不会被报告；例如：curl -v "http://$ALB_IP/" -H 'traceparent: 00-xx-xx-02'。

属性

  • 资源属性

    默认情况下报告这些属性。

    参数说明
    hostnameALB Pod 的主机名
    service.nameALB 的名称
    service.namespaceALB 所在的命名空间
    service.type默认是 ALB
    service.instance.idALB Pod 的名称

  • Span 属性

    • 默认情况下报告的属性：

      参数说明
      http.status_code状态码
      http.request.resend_count重试计数
      alb.rule.rule_name此请求匹配的规则名称
      alb.rule.source_type此请求匹配的规则类型，目前仅 Ingress
      alb.rule.source_nameIngress 的名称
      alb.rule.source_nsIngress 所在的命名空间

    • 默认情况下报告但可以通过修改 flag.hide_upstream_attrs 字段排除的属性：

      参数说明
      alb.upstream.svc_name转发流量的服务（内部路由）的名称
      alb.upstream.svc_ns被转发的服务（内部路由）所在的命名空间
      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 访问地址以查看结果。

本页概览