
KubeSphere WizTelemetry Tracing 分布式追踪扩展基于 OpenTelemetry 的架构、安装配置与查询 API 实战指南【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphereWizTelemetry Tracing 是 KubeSphere 可观测性平台WizTelemetry Observability Platform中负责分布式追踪Distributed Tracing的扩展组件基于 OpenTelemetry Trace 标准实现。本文以仓库中 skills/wiztelemetry-tracing/SKILL.md 为骨架完整讲解其组件架构、InstallPlan 安装流程、全部配置参数、Tracing 查询 API 以及应用自动注入Auto-Instrumentation方法并辅以仓库内其他可观测性扩展文档与脚本作为佐证帮助你从零部署并掌握一条完整的 trace 数据链路应用 → Agent/Collector → Generator → OpenSearch → 查询 API。概述WizTelemetry Tracing 是什么WizTelemetry Tracing 是 KubeSphere 可观测性平台中的扩展组件Extension提供基于 OpenTelemetry 标准的分布式追踪功能。它的核心价值在于让运行在 Kubernetes 多集群环境中的微服务应用能够以标准化的方式产生、采集、存储和查询 trace调用链、span调用段与服务拓扑图service graph从而定位跨服务调用的性能瓶颈与故障点。在 KubeSphere 的扩展体系中它并非孤立组件而是与 WizTelemetry Platform Servicewhizard-telemetry、WizTelemetry Data Pipelinevector以及 OpenSearch 等扩展协同工作是平台可观测性能力日志、审计、事件、通知、追踪中的追踪一环。架构与核心组件WizTelemetry Tracing 采用「Generator Operator Collector Agent」的分层架构各组件职责与默认启用状态如下组件说明默认启用generatorWizTelemetry Tracing Generator根据追踪数据生成服务拓扑图Service Graph以 StatefulSet 部署trueoperatorOpenTelemetry Operator管理 OpenTelemetry Collector 与应用自动注入Auto-Instrumentationtruecollector面向 WizTelemetry 的 OpenTelemetry Collector接收 trace导出到 Vector 与 OpenSearchtrueagentWizTelemetry Tracing Agent从本地日志文件采集追踪数据以 DaemonSet 部署falsedemoOpenTelemetry Demo生成示例追踪数据用于演示false从部署形态可以推断其数据流应用通过 SDK 或自动注入上报 trace → CollectorDeployment默认 2 副本接收并汇聚 → GeneratorStatefulSet可多分片根据 traceId 路由并聚合出服务拓扑 → 数据最终落盘 OpenSearch 并供 whizard-telemetry-apiserver 查询。其中 agent 是一个可选的日志采集通道从本地日志文件扫描 trace 日志并转发给 generatordemo 则用于演示与验证链路。依赖关系依赖说明级别WizTelemetry Platform Servicewhizard-telemetry提供统一 APIServer 后端服务Tracing 查询 API 由它承载必需OpenSearchopensearch存储 span / service 索引的分布式搜索引擎必需对照仓库中 skills/whizard-telemetry/SKILL.md 可知whizard-telemetry-apiserver 是各可观测性扩展的公共 APIServer而 skills/opensearch/SKILL.md 说明 OpenSearch 承载日志、事件、审计与通知历史等观测数据trace 数据同样存储于此。安装流程从确认集群到生成 InstallPlan在生成 InstallPlan 之前必须按顺序完成以下准备步骤其中每一步都有强制的确认与取值要求。Step 1获取可用集群并确认目标首先列出当前多集群环境中的可用集群kubectl get clusters -o jsonpath{.items[*].metadata.name}随后确定部署目标如果用户在需求中明确指定了目标集群直接使用如果未指定必须向用户确认后再继续例如Available clusters: host, dev Which clusters do you want to deploy WizTelemetry Tracing to?注意在确认目标集群之前不要继续后续步骤。KubeSphere 的多集群扩展机制要求 InstallPlan 显式声明clusterScheduling.placement.clusters。Step 2获取最新版本号通过 KubeSphere 扩展版本 API 获取该扩展的最新版本kubectl get extensionversions -n kubesphere-system -l kubesphere.io/extension-refwiztelemetry-tracing -o jsonpath{range .items[*]}{.spec.version}{\n}{end} | sort -V | tail -1该命令输出形如1.0.6的版本号随后将填入 InstallPlan 的spec.extension.version。Step 3获取 Generator 端点先从目标集群获取一个节点 IP作为 generator 的外部访问端点kubectl get nodes -o jsonpath{.items[0].status.addresses[?(.typeExternalIP)].address} 2/dev/null || \ kubectl get nodes -o jsonpath{.items[0].status.addresses[?(.typeInternalIP)].address}输出形如192.168.1.100。默认场景下 generator 通过 NodePort 32318 暴露端点为http://NODE_IP:32318。如果 generator 配置了多分片例如generator.shardCount: 3需要生成全部分片的端点各分片端口从基础 NodePort 开始依次递增NODE_IPNODE_IP for i in 0 1 2; do PORT$((32318 i)) echo - http://${NODE_IP}:${PORT} done将NODE_IP替换为上一步实际获取的节点 IP。Step 4与用户确认配置在创建 InstallPlan 前将完整配置项与用户确认Ill install WizTelemetry Tracing with the following configuration: - Version: VERSION - Target clusters: TARGET_CLUSTERS - Generator endpoint: http://NODE_IP:32318 - OpenSearch endpoint: OPENSEARCH_ENDPOINT Do you want to proceed? (yes/no)用户确认后继续否则根据用户反馈调整配置。Step 5创建 InstallPlan创建 InstallPlan 时有三个硬性约束InstallPlan 的metadata.name必须为wiztelemetry-tracing不得使用其他名称config字段为 YAML 格式必须严格使用模板中的结构与层级不得新增模板之外的配置字段也不得修改结构所有占位符必须替换为真实值不能残留占位符。基于前面的选择默认值如下目标集群用户确认的集群名OpenSearch 端点用户提供默认https://opensearch-cluster-data.kubesphere-logging-system.svc:9200OpenSearch 凭据用户提供默认用户名admin完整模板如下apiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: wiztelemetry-tracing namespace: kubesphere-system spec: extension: name: wiztelemetry-tracing version: VERSION # From Step 2 enabled: true upgradeStrategy: Manual config: | global: generator: endpoints: - http://HOST_NODE_IP:32318 storage: opensearch: auth: strategy: basic user: OPENSEARCH_USER password: OPENSEARCH_PASSWORD endpoints: - OPENSEARCH_ENDPOINT generator: shardCount: 1 service: nodePort: 32318 clusterScheduling: placement: clusters: - TARGET_CLUSTERS占位符替换清单占位符来源示例VERSIONStep 2 获取1.0.6HOST_NODE_IPStep 3 获取的节点 IP192.168.1.100OPENSEARCH_USER用户提供adminOPENSEARCH_PASSWORD用户提供—OPENSEARCH_ENDPOINT用户提供https://opensearch-cluster-data.kubesphere-logging-system.svc:9200TARGET_CLUSTERS用户确认的集群名host其中global.storage.opensearch段与 skills/vector/SKILL.md 中agent.sinks.opensearch的凭据结构一致auth.strategy: basicuser/passwordendpoints整个可观测性平台统一使用该 OpenSearch 认证模式。高级配置Agent、Demo、Tempo 与多分片启用 Agent日志文件采集默认agent.enabled: false。若需从本地日志文件采集追踪数据在 config 中设置agent.enabled: true此时会部署一个 DaemonSet扫描日志文件并将 trace 转发给 generator。结合 skills/whizard-logging/SKILL.md 中 logsidecar-injector 的磁盘日志采集模式可以理解这种「从文件捞 trace」的方式服务于无法直接接入 OTLP SDK 的应用场景。启用 Demo设置demo.enabled: true可部署 OpenTelemetry Demo持续生成示例追踪数据用于验证链路是否打通以及体验查询 API。将 trace 转发到 Tempo如果不使用 OpenSearch 而希望将 trace 转发到 Tempo可修改collector.collector.config为 Collector 配置 OTLP 导出器collector: enabled: true collector: config: | exporters: otlp: endpoint: TEMPO_DISTRIBUTOR_GRPC_ENDPOINT headers: x-scope-orgid: wiztelemetry-tracing-ks tls: insecure: true service: pipelines: traces: exporters: - otlp - otlphttp这里通过x-scope-orgid头将数据归属于wiztelemetry-tracing-ks租户多租户 Tempo 的常见组织隔离方式同时保留otlp与otlphttp两个导出器以兼容不同下游。多 Generator 实例水平扩展为提高吞吐量可增加generator.shardCount并同步扩展global.generator.endpointsglobal: generator: endpoints: - http://HOST_NODE_IP:32318 - http://HOST_NODE_IP:32319 - http://HOST_NODE_IP:32320 generator: shardCount: 3 service: nodePort: 32318两个关键约束shardCount必须与global.generator.endpoints中的端点数一致每个分片的 nodePort 从配置的service.nodePort开始依次递增即 32318、32319、32320…。结合参数表中「Tracing data is routed to different shards bytraceId」的说明可以推断其分片策略为按 traceId 对 trace 进行一致性哈希路由保证同一条调用链的 span 始终落入同一分片从而在分片内完成完整的服务拓扑聚合。配置参数详解Global 参数DNS Service参数类型默认值说明global.dnsServicestringcorednsDNS 服务名称Generator 全局参数参数类型默认值说明global.generator.endpointslist[http://ip:32318]所有 generator 分片的端点。追踪数据按traceId路由到不同分片。OpenSearch 存储参数参数类型默认值说明global.storage.opensearch.auth.strategystringbasic认证策略global.storage.opensearch.auth.userstringadminOpenSearch 用户名global.storage.opensearch.auth.passwordstringadminOpenSearch 密码global.storage.opensearch.endpointslistOpenSearch 端点 URL 列表global.storage.opensearch.index.prefixstringwiz-tracing-span索引前缀global.storage.opensearch.index.timestringstring%Y.%m.%d索引时间格式strftime 模式索引前缀与时间格式共同决定 span 索引的命名例如默认配置下索引形如wiz-tracing-span-2026.09.13前缀 按天滚动。Generator 参数参数类型默认值说明generator.shardCountint1generator 分片数必须等于global.generator.endpoints中端点数generator.image.tagstringv1.0.2generator 镜像 taggenerator.image.imagePullPolicystringIfNotPresent镜像拉取策略generator.service.nodePortint32318第一个分片的 NodePort后续分片端口依次递增generator.resources.limits.cpustring2CPU 上限generator.resources.limits.memorystring2000Mi内存上限generator.resources.requests.cpustring100mCPU 请求generator.resources.requests.memorystring100Mi内存请求Operator 参数参数类型默认值说明operator.enabledbooltrue启用 OpenTelemetry Operatoroperator.fullnameOverridestringwiztelemetry-tracing-operatoroperator Deployment 的名称覆盖Collector 参数ISM Policy 参数索引生命周期管理参数类型默认值说明collector.ism_policy.enablebooltrue启用 OpenSearch Index State Management 策略collector.ism_policy.span_index_patternstring*wiz-tracing-span*span 索引匹配模式collector.ism_policy.service_index_patternstring*wiz-tracing-service*service 索引匹配模式collector.ism_policy.min_index_agestring7d索引最小保留周期collector.ism_policy.span_index_priorityint9950span 索引优先级ISM 策略负责对 span 与 service 两类索引做滚动与清理min_index_age: 7d意味着超过 7 天的索引进入后续管理动作。这与 skills/whizard-auditing/SKILL.md、skills/whizard-events/SKILL.md 中ism_policy.enable/min_index_age的用法一致是 WizTelemetry 系列扩展统一的索引治理机制。Collector 部署参数参数类型默认值说明collector.enabledbooltrue启用 OpenTelemetry Collectorcollector.collector.modestringdeployment部署模式deployment或daemonsetcollector.collector.replicasint2Collector 副本数collector.collector.upgradeStrategystringautomatic升级策略Agent 参数参数类型默认值说明agent.enabledboolfalse启用 Tracing AgentDaemonSetagent.dockerRootDirstring/var/lib/dockerDocker 根目录agent.config.scanIntervalstring1m日志文件扫描间隔agent.config.deletionDelaystring5m处理完成后删除文件的延迟agent.config.logPathstring/app/logs/*/*trace*.logtrace 日志文件路径模式agent.config.podLabelSelectormap{}按标签选择器过滤 Podagent.config.namespaceLabelSelectormap{}按标签选择器过滤命名空间agent.config.includeNamespaceslist[]包含的命名空间列表agent.config.excludeNamespaceslist[]排除的命名空间列表agent.resources.limits.cpustring500mCPU 上限agent.resources.limits.memorystring500Mi内存上限agent.resources.requests.cpustring10mCPU 请求agent.resources.requests.memorystring10Mi内存请求agent.vector.resources.limits.cpustring2Vector sidecar CPU 上限agent.vector.resources.limits.memorystring2000MiVector sidecar 内存上限agent.vector.resources.requests.cpustring100mVector sidecar CPU 请求agent.vector.resources.requests.memorystring100MiVector sidecar 内存请求Agent 以 DaemonSet 形态在每个节点上运行通过logPath默认/app/logs/*/*trace*.log匹配 trace 日志并可通过 include/exclude 命名空间与标签选择器精准圈定采集范围。其 sidecar 基于 Vector这与 skills/vector/SKILL.md 所描述的 WizTelemetry Data Pipeline 技术栈一脉相承。Demo 参数参数类型默认值说明demo.enabledboolfalse启用 OpenTelemetry Demo与 WizTelemetry 平台服务的集成Tracing 查询 API 并非由 WizTelemetry Tracing 扩展自身暴露而是由平台服务 whizard-telemetry-apiserver 承载。仓库中的 skills/whizard-telemetry/scripts/generate-config.sh 展示了二者的集成方式对应installplan_controller.go中generateConfig的实现逻辑脚本检测wiztelemetry-tracing扩展是否已安装check_extension wiztelemetry-tracing若已安装则读取 wiztelemetry-tracing 自己的 InstallPlan config提取 OpenSearch 端点、用户名、密码以及 span 索引前缀默认wiz-tracing-span与时间格式默认%Y.%m.%d最后在 whizard-telemetry 的 config 中生成tracing.enable: true与tracing.server.elasticsearch.*段并写入spanIndex.prefix/spanIndex.timeString。值得注意的是脚本注释明确说明tracing 使用自己的 InstallPlan config而非从 vector secret 获取这与 logging/auditing/events 等扩展不同——tracing 的 OpenSearch 配置端点、认证、索引前缀完全由 wiztelemetry-tracing 的global.storage.opensearch.*参数独立管理。这一设计意味着调整追踪数据存储时只需修改 wiztelemetry-tracing 的 InstallPlan无需改动 vector。Tracing 查询 API 实战所有查询 API 均通过 whizard-telemetry-apiserver 暴露请求头携带X-Remote-User此处示例为admin完成身份标识。以下接口路径统一为/kapis/tracing.wiztelemetry.io/v1alpha1/。查询 Traces调用链curl -X POST http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/traces \ -H X-Remote-User: admin \ -H Content-Type: application/json \ -d {condition: {}, limit: 20}请求体中的condition用于携带查询过滤条件limit控制返回条数示例返回 20 条。查询 Spans调用段curl -X POST http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/spans \ -H X-Remote-User: admin \ -H Content-Type: application/json \ -d {condition: {}, limit: 20}获取服务拓扑图Service Graphcurl -X POST http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/servicegraphs \ -H X-Remote-User: admin \ -H Content-Type: application/json \ -d {condition: {start: START_TIME, end: END_TIME}}condition.start/condition.end为时间范围的 Unix 秒级时间戳服务拓扑由 generator 依据 trace 数据聚合生成。获取服务列表Servicescurl -X GET http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/services \ -H X-Remote-User: admin获取 Tags标签curl -X GET http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/tags \ -H X-Remote-User: admin按 Tag 获取 Valuescurl -X GET http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/values?tagsspan.kindlimit100 \ -H X-Remote-User: admintags指定要查询的 tag 键如span.kindlimit控制返回数量。获取 Histogram指标直方图curl -X GET http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/histogram?keyKEYkind1interval15mstartTimeSTARTendTimeEND \ -H X-Remote-User: admin查询参数参数类型说明keystring节点或边的 keykindint直方图类型1RequestTotal请求总数2RequestTimeAverage请求平均耗时3FailedRequestTotal失败请求总数4ResponseTotal响应总数5ResponseTimeAverage响应平均耗时6FailedResponseTotal失败响应总数intervalstring时间间隔如15m、1h、1dstartTimestring起始时间Unix 秒级时间戳endTimestring结束时间Unix 秒级时间戳kind的六种取值覆盖了拓扑图中「请求/响应」与「总数/均值/失败数」的组合维度可支撑服务拓扑的性能分析视图。获取关联工作负载Workloadscurl -X GET http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/workloads?keysKEYSstartTimeSTARTendTimeEND \ -H X-Remote-User: admin查询参数参数类型说明keysstring逗号分隔的节点 key 列表startTimestring起始时间Unix 秒级时间戳endTimestring结束时间Unix 秒级时间戳获取 / 设置 Apdex 阈值ApdexApplication Performance Index用于衡量应用性能满意度通过阈值将请求分为满意、可容忍、失望三档。# 获取 apdex 阈值 curl -X GET http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/apdex/thresholds?keysKEYS \ -H X-Remote-User: admin # 设置 apdex 阈值 curl -X PUT http://whizard-telemetry-apiserver.extension-whizard-telemetry.svc:80/kapis/tracing.wiztelemetry.io/v1alpha1/apdex/thresholds \ -H X-Remote-User: admin \ -H Content-Type: application/json \ -d {serviceA:serviceB: 0.5}设置接口以 JSON 对象形式提交「服务对 → 阈值」映射如serviceA:serviceB对应 0.5 秒键由服务对标识组成。OpenTelemetry 自动注入Auto-Instrumentation除了在应用中手动接入 OpenTelemetry SDKWizTelemetry Tracing 借助 OpenTelemetry Operator 提供零侵入的自动注入能力。创建 Instrumentation 资源首先创建一个InstrumentationCR声明注入所需的导出端点、传播器与采样器kubectl apply -f - EOF apiVersion: opentelemetry.io/v1alpha1 kind: Instrumentation metadata: name: my-instrumentation spec: exporter: endpoint: http://wiztelemetry-tracing-collector.wiz-telemetry-tracing:4317 propagators: - tracecontext - baggage - b3 sampler: type: parentbased_traceidratio argument: 0.25 python: env: - name: OTEL_EXPORTER_OTLP_ENDPOINT value: http://wiztelemetry-tracing-collector.wiz-telemetry-tracing:4318 dotnet: env: - name: OTEL_EXPORTER_OTLP_ENDPOINT value: http://wiztelemetry-tracing-collector.wiz-telemetry-tracing:4318 go: env: - name: OTEL_EXPORTER_OTLP_ENDPOINT value: http://wiztelemetry-tracing-collector.wiz-telemetry-tracing:4318 EOF要点解读exporter.endpoint指向 Collector 的 gRPC 端口 4317wiztelemetry-tracing-collector.wiz-telemetry-tracing为集群内 Service 地址propagators声明了tracecontext、baggage、b3三种传播格式兼容 OpenTelemetry 原生与 Zipkin/B3 生态的上下游sampler采用parentbased_traceidratio按0.25比例采样——父 span 被采样则子 span 必然采样其余按 25% 概率采样兼顾链路完整性与数据量Python/.NET/Go 语言通过env覆写OTEL_EXPORTER_OTLP_ENDPOINT指向 Collector 的 HTTP 端口 4318其中 Java 等语言默认使用 4317 gRPC 导出因此语言级覆盖是必要的。通过注解启用注入在 Pod 或命名空间上添加注解即可触发自动注入语言注解Javainstrumentation.opentelemetry.io/inject-java: trueNodeJSinstrumentation.opentelemetry.io/inject-nodejs: truePythoninstrumentation.opentelemetry.io/inject-python: true.NETinstrumentation.opentelemetry.io/inject-dotnet: trueGoinstrumentation.opentelemetry.io/inject-go: trueApache HTTPDinstrumentation.opentelemetry.io/inject-apache-httpd: trueNginxinstrumentation.opentelemetry.io/inject-nginx: trueSDK onlyinstrumentation.opentelemetry.io/inject-sdk: true注解取值语义取值行为true从命名空间的 Instrumentation 资源注入my-instrumentation使用当前命名空间中名为my-instrumentation的 Instrumentation CRmy-ns/my-instrumentation使用其他命名空间my-ns中的 Instrumentation CRfalse不注入通过注解值即可实现从「命名空间级默认注入」到「按 CR 精确指定」的灵活控制同一命名空间内的不同工作负载也可以使用不同 Instrumentation 配置。扩展运维操作检查扩展状态kubectl get installplan wiztelemetry-tracing kubectl get extensions wiztelemetry-tracing检查组件运行状态WizTelemetry Tracing 的组件部署在wiz-telemetry-tracing命名空间可按工作负载类型分别检查kubectl get statefulset -n wiz-telemetry-tracing kubectl get deployment -n wiz-telemetry-tracing kubectl get daemonset -n wiz-telemetry-tracing kubectl get pods -n wiz-telemetry-tracing从工作负载形态可以直观验证架构generator 以 StatefulSet 运行多分片有状态服务collector 与 operator 以 Deployment 运行agent 以 DaemonSet 运行。卸载扩展从所有集群卸载kubectl delete installplan wiztelemetry-tracing**仅从特定集群卸载**更新 InstallPlan将该集群从clusterScheduling.placement.clusters中移除apiVersion: kubesphere.io/v1alpha1 kind: InstallPlan metadata: name: wiztelemetry-tracing spec: extension: name: wiztelemetry-tracing version: VERSION enabled: true upgradeStrategy: Manual clusterScheduling: placement: clusters: - REMAINING_CLUSTERS # Remove the cluster you want to uninstall from该模式与 skills/whizard-logging/SKILL.md 等 WizTelemetry 系列扩展的卸载方式完全一致——通过 InstallPlan 的多集群调度声明实现精细的集群级卸载控制。总结与最佳实践综合全文部署与使用 WizTelemetry Tracing 的建议路径如下按依赖顺序部署先确保 OpenSearch 与 whizard-telemetry 平台服务就绪对照 skills/opensearch/SKILL.md 与 skills/whizard-telemetry/SKILL.md再安装 WizTelemetry Tracing严格遵循五步安装前置流程确认目标集群 → 获取版本 → 计算 generator 端点多分片时生成完整端点列表→ 与用户确认 → 按模板创建wiztelemetry-tracingInstallPlan所有占位符必须替换按需启用能力日志文件采集agent.enabled、演示数据demo.enabled、Tempo 替代存储修改 collector 导出器、水平扩展shardCount与 endpoints 同步调整善用自动注入创建 Instrumentation CR 后通过instrumentation.opentelemetry.io/inject-*注解以极低成本接入主流语言应用通过统一 API 查询借助 whizard-telemetry-apiserver 的/kapis/tracing.wiztelemetry.io/v1alpha1/接口查询 traces、spans、service graph、直方图与 apdex 阈值并与平台日志、事件、审计能力联动完成端到端排障。【免费下载链接】kubesphereThe container platform tailored for Kubernetes multi-cloud, datacenter, and edge management ⎈ ☁️项目地址: https://gitcode.com/GitHub_Trending/ku/kubesphere创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考