关于apisix:可观测性能力升级Apache-APISIX-集成-OpenTelemetry

本文为您介绍 Apache APISIX opentelemetry 插件概念以及如何如何开启和部署 opentelemetry 插件。

背景信息

Apache APISIX 是一个动静、实时、高性能的 API 网关，提供负载平衡、动静上游、灰度公布、服务熔断、身份认证、可观测性等丰盛的流量治理性能。作为 API 网关，Apache APISIX 不仅领有泛滥实用的插件，而且反对插件动静变更和热插拔。

OpenTelemetry 是一个开源的遥测数据采集和解决零碎，它不仅提供了各种 SDK 用于利用端遥测数据的收集和上报，以及数据收集端用于数据接管、加工和导出，还反对通过配置导出到任意一个或者多个曾经适配 OpenTelemetry Exporter 的后端，比方 Jaeger、Zipkin、OpenCensus 等。您能够在 opentelemetry collector contrib 库中查看曾经适配 OpenTelemetry Collector 的插件列表。

插件介绍

Apache APISIX opentelemetry 插件是基于 OpenTelemetry 原生规范（OTLP/HTTP）实现的 Tracing 数据采集，并通过 HTTP 协定发送至 OpenTelemetry Collector。该性能将在 Apache APISIX 2.13.0 版本中上线反对。

因为 OpenTelemetry 的 Agent/SDK 与后端实现无关，当利用集成了 OpenTelemetry 的 Agent/SDK 之后，用户可能在利用侧无感知的状况下轻松地、自在地变更可观测性后端服务，比方从 Zipkin 切换成 Jaeger。

opentelemetry 插件在 Apache APISIX 中集成了 OpenTelemetry Agent/SDK，能够实现采集被追踪的申请生成 trace 后转发到 OpenTelemetry Collector。

opentelemetry 插件位于上图中的 Agent 侧，但目前仅反对 trace 协定，还不反对 OpenTelemetry 的 logs 和 metrics 协定。

如何应用

启用插件

您须要在 conf/config.yaml 配置文件中启用 opentelemetry 插件并批改 collector 配置。

假如您曾经实现 OpenTelemetry Collector 的部署，并且启用了 OTLP HTTP Receiver。

如果您未实现部署，可参考下一节的场景示例局部，实现 OpenTelemetry Collector 的部署。

其中 OTLP HTTP Receiver 的默认端口为 4318，collector 的地址为 OpenTelemetry Collector 的 HTTP Receiver 地址，相干字段可参考 Apache APISIX 官网文档。

plugins
... # 曾经启用的其它插件
- opentelemetry
plugin_attr:
...
opentelemetry:
  trace_id_source: x-request-id
  resource:
    service.name: APISIX
  collector:
    address: 127.0.0.1:4318 # OTLP HTTP Receiver 地址
    request_timeout: 3

办法一：将插件绑定到指定路由

为了更不便的展现测试成果，示例中临时将 sampler 设置为全采样，以确保每次申请都被追踪后产生 trace 数据，不便您在 Web UI 上查看 trace 的相干数据。您也能够依据理论状况，设置相干参数。

curl http://127.0.0.1:9080/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-X PUT -d '{"uri":"/get","plugins": {"opentelemetry": {"sampler": {"name":"always_on"}
      }
  },
  "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
  }
}'

形式二：设置 Global Rules

您也能够通过 Apache APISIX Plugins 性能启用 opentelemetry 插件。实现全局配置后，您依然须要创立路由，否则将无奈进行测试。

curl 'http://127.0.0.1:9080/apisix/admin/global_rules/1' \
-H 'X-API-KEY:  edd1c9f034335f136f87ad84b625c8f1' \
-X PUT -d '{"plugins": {"opentelemetry": {"sampler": {"name":"always_on"}
      }
  }
}'

形式三：通过 additional_attributes 为 Span 自定义标签

对于 sampler 和 additional_attributes 的配置您能够参考 Apache APISIX 官网文档，其中 additional_attributes 是一系列的 Key:Value 键值对，您能够应用它为 Span 自定义标签，并且能够追随 Span 在 Web UI 上展现。通过 additional_attributes 为某个路由的 Span 减少 route_id 和 http_x-custom-ot-key，能够参考如下配置：

curl http://127.0.0.1:9080/apisix/admin/routes/1001 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
-X PUT -d '{"uri":"/put","plugins": {"opentelemetry": {"sampler": {"name":"always_on"},"additional_attributes":["route_id","http_x-custom-ot-key"]
      }
  },
  "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
  }
}'

测试示例

您能够通过以上三种形式中的任意一种形式启用 opentelemetry，以下示例应用形式三的办法创立路由，创立胜利后，您能够参考如下命令拜访路由：

curl -X PUT -H `x-custom-ot-key: test-ot-val` http://127.0.0.1:9080/put

拜访胜利之后，您能够在 Jaeger UI 中看到相似如下图所示 /put 的 Span 详情，并能够看到 Tags 列表中展现了路由中自定义的 tag：http_x-custom-ot-key 和 route_id。

您须要留神，additional_attributes 配置的设定是从 Apache APISIX 和 Nginx 变量取值作为 attribute 的值，因而 additional_attributes 必须是 Apache APISIX 或者 Nginx 的无效变量。其中也包含 HTTP Header，然而在取 http_header 时，须要增加 http_ 作为变量名的前缀。如果变量不存在，就不会展现这个 tag 了。

场景示例

本场景示例通过简略批改 OpenTelemetry Collector 官网示例部署 Collector、Jaeger 和 Zipkin 作为后端服务，并且启动两个示例应用程序（Client 和 Server），其中 Server 提供了一个 HTTP 服务，而 Client 会循环调用 Server 提供的 HTTP 接口，从而产生包含两个 Span 的调用链。

步骤一：部署 OpenTelemetry

以下应用 docker-compose 作为示例，其它部署能够参考 OpenTelemetry 官网文档。

您能够参考如下命令部署：

git clone https://github.com/open-telemetry/opentelemetry-collector-contrib.git
cd opentelemetry-collector-contrib/examples/demo
docker-compose up -d

在浏览器中输出 http://127.0.0.1:16886（Jaeger UI）或者 http://127.0.0.1:9411/zipkin（Zipkin UI），如果能够失常拜访，则示意部署胜利。

下图为拜访胜利示例：

步骤二：配置测试环境

引入 Apache APISIX 服务，最终利用的拓扑如下图所示：

Trace 数据上报流程如下。其中因为 Apache APISIX 是独自部署的，并不在 docker-compose 的网络内，所以 Apache APISIX 是通过本地映射的端口（即 127.0.0.1:4138）拜访到 OpenTelemetery Collector 的 OTLP HTTP Receiver 的。

您须要确保曾经启用 opentelemetry 插件，并从新加载 Apache APISIX。

1. 您能够参考如下示例创立一个路由，并且启用 opentelemetry 插件进行采样：

   curl http://127.0.0.1:9080/apisix/admin/routes/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
    -X PUT -d '{"uri":"/hello","plugins": {"opentelemetry": {"sampler": {"name":"always_on",}
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {"127.0.0.1:7080": 1}
    }
   }'

2. 批改 ./examples/demo/otel-collector-config.yaml 文件，并增加 OTLP HTTP Receiver，如下所示：

   receivers:
    otlp:
    protocols:
      grpc:
      http:${ip:port}   # 增加 OTLP HTTP Receiver，默认端口为 4318

3. 批改 docker-compose.yaml。

您须要批改配置文件，把 Client 调用 Server 的接口地址批改为 Apache APISIX 的地址，将 OTLP HTTP Receiver 和 Server 服务的端口映射到本地。

以下示例是批改配置后残缺的 docker-compose.yaml：

version: "2"
services:

# Jaeger
jaeger-all-in-one:
  image: jaegertracing/all-in-one:latest
  ports:
    - "16686:16686" # jaeger ui 的端口
    - "14268"
    - "14250"

# Zipkin
zipkin-all-in-one:
  image: openzipkin/zipkin:latest
  ports:
    - "9411:9411"

# Collector
otel-collector:
  image: ${OTELCOL_IMG}
  command: ["--config=/etc/otel-collector-config.yaml", "${OTELCOL_ARGS}"]
  volumes:
    - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml
  ports:
    - "1888:1888"   # pprof extension
    - "8888:8888"   # Prometheus metrics exposed by the collector
    - "8889:8889"   # Prometheus exporter metrics
    - "13133:13133" # health_check extension
    - "4317"        # OTLP gRPC receiver
    - "4318:4318"   # 增加 OTLP HTTP Receiver 端口映射
    - "55670:55679" # zpages extension
  depends_on:
    - jaeger-all-in-one
    - zipkin-all-in-one

demo-client:
  build:
    dockerfile: Dockerfile
    context: ./client
  environment:
    - OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317
    - DEMO_SERVER_ENDPOINT=http://172.17.0.1:9080/hello # APISIX 的地址
  depends_on:
    - demo-server

demo-server:
  build:
    dockerfile: Dockerfile
    context: ./server
  environment:
    - OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317
  ports:
    - "7080:7080" # 将 Server 端口映射到宿主机
  depends_on:
    - otel-collector

prometheus:
  container_name: prometheus
  image: prom/prometheus:latest
  volumes:
    - ./prometheus.yaml:/etc/prometheus/prometheus.yml
  ports:
    - "9090:9090"

须要留神，demo-client.environment.DEMO_SERVER_ENDPOINT 处须要改为您的 Apache APISIX 地址，且保障在容器内能够失常拜访。

当然，您也能够通过 docekr-compose.yaml 部署 Apache APISIX，具体能够参考 Apache APISIX 官网文档。

步骤三：测试

重新部署实现后，拜访 Jaeger UI 或者 Zipkin UI 即可看到 Trace 中蕴含了 APISIX 的 Span，如下图：

禁用插件

如果您临时不须要某个路由的 Trace 采集，则仅需批改路由配置，将配置中的 plugins 下的 opentelemetry 相干配置删除即可。

如果您是通过绑定 Global Rules 全局启用的，则只能删除 opentelemetry 全局插件的配置。得益于 Apache APISIX 的动态化劣势，开启敞开插件的过程都不须要重启 Apache APISIX，非常不便。

总结

Apache APISIX 在集成 OpenTelemetery 之后，借助 OpenTelemetry 丰盛的插件可能与市场上大部分支流的 Trace 零碎轻松实现对接。此外，Apache APISIX 也实现了 SkyWalking 和 Zipkin 原生标准协议插件，也在踊跃与各大社区单干打造更加弱小的生态。

Apache APISIX 我的项目目前正在开发其余插件以反对集成更多服务，如果您对此有趣味，您能够通过 GitHub Discussions 发动探讨，或通过邮件列表进行交换.