API网关后端云原生【免费下载链接】tykOpen Source API and AI Gateway supporting REST, GraphQL, TCP, gRPC and MCP (Model Context Protocol)项目地址https://gitcode.com/gh_mirrors/ty/tyk点击查看免费下载导读本文聚焦 Tyk 开源仓库中 ci/tests/tracing/README.md 所描述的 OpenTelemetry 端到端e2e测试体系剖析其背后的 Docker Compose 多服务编排、OpenTelemetry Collector 采集链路、Tracetest 断言引擎以及覆盖 HTTP、认证、GraphQL、gRPC、版本化 API 等场景的测试用例。读完本文你将掌握如何在本地一键拉起 Tyk 网关 OTel Collector Tracetest 的完整追踪测试环境如何编写基于 span 属性的断言以及 Tyk 网关追踪配置opentelemetry与 API 级detailed_tracing标志的底层实现机制。一、测试体系全景为什么要做 OpenTelemetry e2e 测试Tyk 网关在 internal/otel/config.go 中内置了 OpenTelemetry 支持可将每个 API 请求的追踪数据trace通过 gRPC 或 HTTP 导出到任意兼容 OTLP 的后端。要验证网关产出的 span 是否符合预期——例如中间件是否产生 span、API 元数据属性是否正确写入——仅靠单元测试远远不够需要一个真实运行网关、真实导出 trace、再对 trace 内容做结构化断言的完整链路。ci/tests/tracing目录正是为此设计的黑盒 e2e 测试套件其核心思路在 Docker Compose 中启动真实 Tyk 网关内部版本需先make docker构建镜像网关通过 OTLP gRPC 把 trace 发给OpenTelemetry CollectorCollector 将 trace 转发给Tracetestkubeshop/tracetest 镜像Tracetest CLI发起 HTTP/gRPC 请求触发网关处理并对照scenarios/*.yml中的 span 断言执行验证。该目录的关键组成ci/tests/tracing/ ├── docker-compose.yml # 多服务编排 ├── Taskfile.yml # setup / test / teardown 自动化 ├── tracetest/Taskfile.yml # tracetest CLI 安装与配置 ├── configs/ │ ├── tyk.env # 网关 OpenTelemetry 环境变量 │ ├── otelcollector/collector.config.yml │ └── tracetest/{tracetest.yml, tracetest-provision.yml} ├── apps/ # 预加载的 API 定义JSON ├── policies/ # 预加载的策略 ├── keys/ # 预加载的 key └── scenarios/ # Tracetest 测试场景YAML二、Docker Compose 多服务架构逐层拆解docker-compose.yml 定义了一个多服务应用各服务职责如下。2.1 被测主体tyk网关服务镜像由GATEWAY_IMAGE环境变量指定默认internal/tyk-gateway。README 明确指出从冷启动运行本套件前必须先在 Tyk 仓库根目录执行make docker构建内部网关镜像。环境变量从本地文件 configs/tyk.env 加载。通过卷挂载将 apps/ 下的预加载 API 定义与 policies/ 下的策略放入网关。对外映射9000:8080依赖redis服务。2.2 基础设施服务服务镜像/版本职责健康检查redisredis:6网关存储--appendonly yes启用 AOF 持久化无cacheredis:6Tracetest 缓存unless-stopped重启策略redis-cli pingqueuerabbitmq:3.8-management消息队列带管理插件rabbitmq-diagnostics -q check_runningpostgrespostgres:14Tracetest 元数据存储pg_isready -U $POSTGRES_USER -d $POSTGRES_DBhttpbin.orgkennethreitz/httpbin:latestHTTP 测试上游无grpcapiromk/grpc-helloworld-reflectiongRPC 测试上游映射50001:50051无注README 描述中提及 Collector 0.80.0、Tracetest v0.11.16、Redis 4.0 等版本而当前 compose 文件实际使用otel/opentelemetry-collector-contrib:0.100.0、kubeshop/tracetest:v1.7.1、redis:6说明 README 与编排文件存在版本迭代差异以当前 compose 文件为准。2.3 追踪链路otel-collector与tracetestotel-collectorotel/opentelemetry-collector-contrib:0.100.0启动参数--config /otel-local-config.yml该配置由本地 configs/otelcollector/collector.config.yml 挂载暴露4317OTLP gRPC与4318OTLP HTTP端口。tracetestkubeshop/tracetest:v1.7.1启动参数--provisioning-file /app/provision.yml健康检查为wget --spider localhost:11633Web/API 端口11633映射到宿主机。它depends_ontyk-checkerhealthy、otel-collectorstarted、postgreshealthy三个条件。2.4 网关就绪探针tyk-checkertyk-checker是一个巧妙的网关健康门卫使用badouralix/curl-jq镜像通过curl -s --fail http://tyk:8080/hello | jq校验网关/hello健康端点的返回 JSON 中status pass只有通过后 Tracetest 才会启动避免测试在网关未就绪时竞态失败。三、网关侧 OpenTelemetry 配置tyk.env 逐项解读configs/tyk.env 是网关追踪能力的开关总控TYK_LOGLEVELdebug TYK_GW_OPENTELEMETRY_ENABLEDtrue TYK_GW_OPENTELEMETRY_EXPORTERgrpc TYK_GW_OPENTELEMETRY_ENDPOINTotel-collector:4317 TYK_GW_HTTPSERVEROPTIONS_ENABLEHTTP2true TYK_GW_PROXYENABLEHTTP2true TYK_GW_STORAGE_HOSTredis TYK_GW_POLICIES_POLICYSOURCEfile TYK_GW_POLICIES_POLICYPATH/opt/tyk-gateway/policies各变量含义TYK_GW_OPENTELEMETRY_ENABLEDtrue总开关。对应网关配置中的opentelemetry.enabled在 config/config.go 中定义于OpenTelemetry otel.OpenTelemetry配置节。TYK_GW_OPENTELEMETRY_EXPORTERgrpc导出协议为 OTLP gRPC可选http。环境变量覆盖机制在 config/config_test.go 中有对应测试用例env var override、env var only例如TYK_GW_OPENTELEMETRY_EXPORTERhttp与TYK_GW_OPENTELEMETRY_ENDPOINTlocalhost:4318的组合。TYK_GW_OPENTELEMETRY_ENDPOINTotel-collector:4317OTLP gRPC 接收端地址指向 compose 网络中的 Collector。TYK_GW_HTTPSERVEROPTIONS_ENABLEHTTP2/TYK_GW_PROXYENABLEHTTP2启用 HTTP/2gRPC 上游调用所需。TYK_GW_STORAGE_HOSTredis网关存储指向 compose 中的redis服务。TYK_GW_POLICIES_POLICYSOURCEfileTYK_GW_POLICIES_POLICYPATH策略以文件方式加载自/opt/tyk-gateway/policies挂载目录。从源码看internal/otel的配置结构在 internal/otel/config.go 中被拆分为Traces根级内联字段的向后兼容层与Metrics两大子节网关侧MetricsConfig额外支持runtime_metricsGo 运行时指标默认随 metrics 启用与api_metrics可声明维度范围的自定义指标仪表TracesConfig则支持mcp子配置定义从 MCP 请求的 W3C trace context 读取位置。这些配置均可在本 e2e 套件中通过环境变量驱动。3.1 API 级追踪开关detailed_tracing除全局开关外每个 API 可独立决定是否产生详细追踪 span。在 apps/test.json 中可见detailed_tracing: trueapps/test-graphql-tracing.json 同样设置detailed_tracing: true。这一标志与do_not_track是否记录分析数据相互独立test.json同时设置了do_not_track: true说明关闭分析记录不影响追踪 span 的生成。四、OpenTelemetry Collector 与 Tracetest 配置4.1 CollectorOTLP 接收 批量 转发configs/otelcollector/collector.config.ymlreceivers: otlp: protocols: grpc: http: processors: batch: timeout: 100ms exporters: logging: loglevel: debug otlp/1: endpoint: tracetest:4317 tls: insecure: true service: pipelines: traces/1: receivers: [ otlp ] processors: [ batch ] exporters: [ otlp/1 ]要点同时启用 OTLP gRPC 与 HTTP 两种接收协议对应端口 4317/4318batch处理器以 100ms 超时聚合 span降低转发开销loggingexporter 以 debug 级别输出日志便于本地排障主出口otlp/1指向tracetest:4317tracetest服务的 OTLP 端口tls.insecure: true关闭 TLS。4.2 Tracetest 数据存储与配置configs/tracetest/tracetest.yml 指向postgres服务用户/密码/库名均为postgressslmodedisable。configs/tracetest/tracetest-provision.yml 通过--provisioning-file注入三项配置DataStoreotlp声明 Tracetest 通过 OTLP 接收 trace 数据ConfiganalyticsEnabled: truePollingProfile名为Custom Profile、default: true的轮询配置timeout: 2m、retryDelay: 3s用于周期性地从数据存储拉取新 trace 供断言引擎消费。五、Tracetest 场景文件span 断言实战scenarios/目录包含 18 个测试声明*.yml/*.yaml覆盖 HTTP、JWT、多重认证、Tyk 内部协议、gRPC、版本化 API、GraphQL 追踪与无效配置等场景。每个文件是一个type: Test的 Tracetest 定义包含trigger如何发起请求与specs对 span 的断言。5.1 基础 HTTP 场景span 属性断言以 scenarios/tyk_test_200.yml 为例type: Test spec: id: 4pnmVurVg name: HTTP Test API - ok request trigger: type: http httpRequest: method: GET url: tyk:8080/test/ip headers: - key: Content-Type value: application/json - key: User-Agent value: Go-http-client/1.1 specs: - selector: span[tracetest.span.typehttp nameGET /test/ip http.request.methodGET] name: Test main span attributes assertions: - attr:http.request.method GET - attr:http.response.status_code 200 - attr:user_agent.original Go-http-client/1.1 - attr:http.response.body.size ! 0 - attr:tracetest.span.type http - attr:tyk.api.id 3 - attr:tyk.api.name TestAPI - attr:tyk.api.orgid default - attr:tyk.api.tags not-contains test - attr:tyk.api.path /test/ - attr:tyk.original_path /test/ip这里展示的断言模式包括标准语义约定http.request.method、http.response.status_code、user_agent.original、http.response.body.sizeTyk 自定义属性tyk.api.id、tyk.api.name、tyk.api.orgid、tyk.api.path、tyk.original_path原始请求路径、tyk.api.tagsspan 选择器span[tracetest.span.typehttp nameGET /test/ip ...]按 span 类型与名称定位。这些tyk.*属性与 apps/test.json 中的 API 定义一一对应api_id: 3、name: TestAPI、org_id: default、listen_path: /test/形成预加载 API → 网关生成 span → 断言属性的闭环验证。5.2 中间件 span 断言同一场景还对网关内部中间件产生的 span 做了断言- selector: span[tracetest.span.typegeneral nameRateCheckMW] name: Check for RateCheckMiddleware assertions: - attr:name RateCheckMW - selector: span[tracetest.span.typegeneral nameVersionCheck] name: VersionCheck MW attributes assertions: - attr:tyk.api.version Non Versioned即验证RateCheckMW限流中间件与VersionCheck版本检查中间件生成了名为对应中间件名称的 span且tyk.api.version属性正确未版本化 API 输出Non Versioned。这从 e2e 层面确认了中间件执行可观测的设计。5.3 版本化 API 场景scenarios/tyk_versioned_200.yml 通过请求头x-api-version: v1触发版本化 API断言tyk.api.version v1tyk_versioned_403.yml 则验证无正确版本头时的 403 行为——同一 API 的正反两例确保版本解析逻辑稳定。5.4 GraphQL 追踪场景深度 span 结构验证GraphQL 是 Tyk 追踪能力最复杂的部分。scenarios/tyk_test-graphql-tracing_200.yml 对POST /test-graphql-tracing/test-graphql-tracing发起 GraphQL 查询并断言上游请求合法ResolvePlanspan 下的 HTTP span 指向https://countries.trevorblades.com/且状态码 200GraphqlEngine 子 span 数量tracetest.selected_spans.count 3验证引擎内部产生恰好 3 个 spanValidateRequest span携带graphql.operation.type、graphql.operation.name、graphql.document等 GraphQL 语义属性并逐字符比对查询文档。配套的 apps/test-graphql-tracing.json 定义了graphql.enabled: true、execution_mode: proxyOnly、version: 2及完整 schema 与detailed_tracing: true与场景断言互相印证。其余场景还验证了tyk_test-graphql-tracing_400.yml请求体校验失败时的 400 行为tyk_test-graphql-tracing-invalid_404.yml无效追踪配置如detailed_tracing: false的 API应返回 404即追踪开关影响路由可达性tyk_test-graphql-detailed-tracing-disabled_{200,400}明确关闭 detailed tracing 后不产生详细 span 的行为差异。5.5 其他场景一览场景文件验证目标tyk_test_500.yml上游 500 错误的 span 记录tyk_testauth_401.yml认证失败返回 401tyk_jwt_200.yml/tyk_multiauth_jwt_200.ymlJWT 与多重认证成功路径tyk_tykprotocol_{200,401}.ymlTyk 内部协议访问与未授权tyk_grpcapi_200.ymlgRPC API 追踪tyk_test_with_response_mw.yml响应中间件参与追踪tyk_body_size_200.yaml请求体大小限制正常路径对应地apps/ 中的test-auth.json、test-jwt.json、test-multiauth.json、tykprotocol.json、grpcapi.json等即为各场景预加载的 API 定义policies/ 与 keys/keys.json 提供策略与预置 key。六、一键运行Taskfile 自动化编排Taskfile.yml 封装了完整生命周期6.1 安装与配置 tracetest CLItracetest/Taskfile.ymlinstall按平台安装 tracetest CLI——macOS 用brew install kubeshop/tracetest/tracetestLinux 通过 APT 添加apt.fury.io/tracetest源并安装tracetest1.0.0configure执行tracetest configure -g --server-url http://localhost:11633将 CLI 指向本地 Tracetest 服务。6.2 任务流setup → info → test → teardowntasks: default: desc: setup, execute and shutdown e2e opentelemetry tests cmds: - defer: task: teardown - task: setup - task: info - task: testsetup先mkdir -p apps policies chmod 777 apps policies确保非 root 网关进程 uid 65532 可写挂载目录再docker compose up -d --wait启动全部服务并等待健康最后task: tracetest:configureinfo打印预检信息——docker compose run --rm tyk version、docker version、docker compose ps、tracetest versiontestdocker compose logs -f 后台跟随日志随后逐条执行 17 个tracetest run test -f ./scenarios/... -o pretty命令pretty 输出便于人工阅读teardowndocker compose down --remove-orphans清理环境并通过defer保证即使测试中途失败也会执行清理。运行方式在 ci/tests/tracing 目录下执行task或task default即自动完成构建镜像 → 起服务 → 配置 CLI → 跑全部场景 → 清理的完整闭环也可单独执行task setup、task test、task teardown分步调试。七、从 e2e 反推实现网关追踪的源码印证本套件的断言之所以有效源于网关内部的实现支撑配置层opentelemetry配置节含enabled、exporter、endpoint、sampling、connection_timeout等定义于 config/config.go 的OpenTelemetry otel.OpenTelemetry字段并通过 config/config_test.go 验证了环境变量覆盖TYK_GW_OPENTELEMETRY_*与纯环境变量无配置文件两种加载方式类型别名层internal/otel/config.go将ExporterConfig、Sampling、SpanBatchConfig等类型别名化TracesConfig支持嵌套的opentelemetry.traces子配置MetricsConfig增加网关特有的runtime_metrics与api_metrics中间件层场景中断言的RateCheckMW、VersionCheckspan 名称与网关中间件源码命名一致说明追踪埋点直接复用中间件名称作为 span 名属性层tyk.api.*、tyk.original_path、tyk.api.version等属性在 e2e 中断言其精确值是对网关追踪属性生成逻辑的强约束。这些测试不仅是回归保障更是网关追踪行为的活文档——任何新增中间件或属性都能以同样的方式补充场景文件获得可验证的追踪覆盖。八、结语如何复用这套追踪测试体系对希望为自己的 Tyk 部署建立链路追踪验证的团队本套件提供了可直接借鉴的模式本地复现在 Tyk 仓库根目录执行make docker构建网关镜像进入ci/tests/tracing后运行task即可完整跑通扩展场景在 apps/ 新增 API 定义 JSON在 scenarios/ 仿照tyk_test_200.yml编写 trigger selector assertions并在 Taskfile.yml 的test任务中追加对应tracetest run test命令接入生产后端将 Collector 配置中的otlp/1exporter 指向自己的 OTLP 后端如 Jaeger、Tempo即可把同一套网关配置用于真实环境的追踪采集。整个体系以真实网关 真实导出 结构化断言三位一体为 API 网关的可观测性质量提供了可重复、可审计的自动化保障。赞分享API网关后端云原生【免费下载链接】tykOpen Source API and AI Gateway supporting REST, GraphQL, TCP, gRPC and MCP (Model Context Protocol)项目地址https://gitcode.com/gh_mirrors/ty/tyk点击查看免费下载相关推荐Apache Druid OpenTelemetry Emitter 扩展实战查询 Span 追踪与端到端链路关联Apache Druid OpenTelemetry Emitter 扩展实战查询 Span 追踪与端到端链路关联 OpenTelemetry Emitter数据库OLAP大数据后端Synapse 分布式追踪实践基于 OpenTracing 与 Jaeger 的端到端链路观测指南Synapse 分布式追踪实践基于 OpenTracing 与 Jaeger 的端到端链路观测指南 导读 SynapseMatrix 协议的服务端实现使用后端即时通讯NocoBase 服务端 Telemetry 遥测开发指南基于 OpenTelemetry 的指标采集与链路追踪NocoBase 服务端 Telemetry 遥测开发指南基于 OpenTelemetry 的指标采集与链路追踪 NocoBase 的遥测Telemetry低代码后端前端人工智能AI 应用工作流自动化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考