Tekton 组件的指标采集
目录
概述前提条件Tekton PipelinesPipelineRun 指标running_pipelineruns 标签级别状态标签值TaskRun 指标config-observability 配置Histogram 桶推荐的生产配置Tekton TriggersController 指标(端口 9000)EventListener Sink 指标Tekton ResultsWatcher 指标删除指标共享指标Watcher config-observabilityAPI Server 指标Tekton ChainsChains 指标Controller Framework 指标设置 ServiceMonitorPipeline ServiceMonitorTriggers ServiceMonitorEventListener Sink ServiceMonitorResults ServiceMonitorChains ServiceMonitor验证直接检查指标端点检查 Prometheus 目标PromQL 查询示例监控面板示例Tekton Pipeline 监控面板Tekton Pipeline 监控面板解读(常见问题)Tekton Triggers 监控面板Tekton Triggers 监控面板解读(常见问题)Tekton Results 监控面板Tekton Results 监控面板解读(常见问题)Tekton Chains 监控面板Tekton Chains 监控面板解读(常见问题)概述
Tekton 组件通过 HTTP 端点公开 Prometheus 兼容的指标。部署 ServiceMonitor 资源后,Prometheus(或 VictoriaMetrics)可以自动发现并抓取这些指标。
命名空间说明:本文档使用
tekton-pipelines作为控制平面组件(Pipelines、Triggers、Results、Chains)的默认命名空间。 主要例外是 EventListener Service,它们运行在创建 EventListener 的应用命名空间中。如果您的部署使用不同的命名空间,请同时更新以下命令以及下方
ServiceMonitor资源中的namespaceSelector字段。
本文档涵盖以下 Tekton 组件的指标:
- Tekton Pipelines - PipelineRun / TaskRun 执行指标
- Tekton Triggers - EventListener、TriggerBinding 及相关资源指标
- Tekton Results - 运行删除和存储指标
- Tekton Chains - 签名和来源证明指标
- Controller Framework - 所有 controller 共享的基础设施指标
本文档还介绍:
- 如何通过
config-observability配置指标行为 - 如何部署用于抓取指标的
ServiceMonitor资源 - 如何验证指标采集是否正常工作
前提条件
- 已安装并运行 Tekton 控制平面组件(至少包括您计划抓取的组件:Pipelines、Triggers、Results 和/或 Chains)。
- 已针对目标集群配置
kubectl,且您的账户可以在监控命名空间中创建ServiceMonitor资源。 - 已部署监控栈(Prometheus 或兼容的 VictoriaMetrics),并且能够发现/抓取
ServiceMonitor资源(或平台使用的等效抓取发现对象)。 - 您的 Prometheus/VictoriaMetrics 实例已配置为发现您创建的
ServiceMonitor对象(命名空间和标签选择器必须匹配)。 - 网络策略和防火墙允许抓取器 Pod 访问 Tekton 指标端口(大多数控制平面服务使用
9090,Triggers controller 和 EventListener sink 使用9000)。 - 如果需要 EventListener sink 指标,则目标命名空间中必须存在 EventListener,并公开
http-metrics端口。
Tekton Pipelines
Tekton Pipelines 组件包含多个子服务,这些服务在端口 9090 上公开指标:
Pipeline controller 指标使用前缀 tekton_pipelines_controller_。
PipelineRun 指标
* 带有 * 标记的标签为可选标签,具体取决于
config-observability配置。
running_pipelineruns 标签级别
running_pipelineruns 指标的标签由 metrics.running-pipelinerun.level 控制:
状态标签值
对于 PipelineRun 指标:
success- PipelineRun 已成功完成failed- PipelineRun 失败cancelled- PipelineRun 已取消
对于 TaskRun 指标:
success- TaskRun 已成功完成failed- TaskRun 失败
TaskRun 指标
config-observability 配置
config-observability 命名空间中的 tekton-pipelines ConfigMap 控制 Pipeline controller 的指标行为。此 ConfigMap 由 Tekton Operator 管理,应通过 TektonConfig 资源的 spec.pipeline.options.configMaps 字段进行配置。详情请参阅调整子组件的可选配置项。
热加载行为:
config-observability会在运行时受到监视。大多数关键更改(例如metrics.*)无需重启 Pod 即可生效。请等待一到两个抓取间隔,以便监控面板/查询中显示更改。只有在 Pod 规范设置发生更改时才需要重启(例如更改 Deployment 中的CONFIG_OBSERVABILITY_NAME)。
通过 TektonConfig 配置的示例:
Histogram 桶
当持续时间类型为 histogram 时,将使用以下桶边界(单位为秒):
这对应于:10s、30s、1m、5m、15m、30m、1h、1.5h、3h、6h、12h、24h。
推荐的生产配置
对于生产环境,请使用聚合级别来控制标签基数:
如果需要逐个运行的粒度以进行调试,可以临时切换为:
请注意,这将显著增加时间序列的数量。
Tekton Triggers
Tekton Triggers 组件从不同进程中公开两类指标。
Controller 指标(端口 9000)
Triggers controller 每 60 秒报告一次资源数量指标。
Triggers controller 指标使用前缀 controller_。
EventListener Sink 指标
每个 EventListener pod 都会公开额外的 HTTP 和事件处理指标。这些指标来自 EventListener sink 进程(而非 controller)。Prometheus 指标前缀为 eventlistener_。
eventlistener_http_duration_seconds直方图桶:0.001, 0.01, 0.1, 1, 10(秒)eventlistener_event_received_count状态值:succeeded、failedeventlistener_triggered_resources类型值:所创建对象的 Kubernetes 资源 Kind(例如PipelineRun、TaskRun)
这些 sink 指标按 EventListener pod 分别公开,而不是由中心 controller 公开。如果 EventListener pod 暴露了指标端口,可能需要单独的
ServiceMonitor或PodMonitor来抓取这些指标。
Tekton Results
Tekton Results 包含两个公开指标的子服务。
Watcher 指标
Watcher 指标使用前缀 watcher_。
删除指标
* 可选标签取决于 Results Watcher 的
config-observability设置。
注意:仅当 Watcher 实际删除运行时,才会记录
pipelinerun_delete_count、pipelinerun_delete_duration_seconds、taskrun_delete_count和taskrun_delete_duration_seconds。除非在tekton-results-watcherDeployment 上将--completed_run_grace_period标志设置为非零值,否则这些指标将保持为空(没有数据点)。默认情况下,此标志为0,会禁用自动删除。将其设置为正时长(例如10m)可启用宽限期后的删除,或将其设置为负值,以便在归档后立即删除。
Results Watcher 的状态标签值:
success- 运行成功完成failed- 运行失败cancelled- 运行已取消
共享指标
Watcher 中的 PipelineRun 和 TaskRun reconciler 都会注册这些指标,用于跟踪与存储相关的事件。
kind 标签用于标识运行类型(某些指标序列中为 PipelineRun / TaskRun,其他指标序列中为 pipelinerun / taskrun)。
注意:仅当运行在 Watcher 持有 finalizer 以协调归档期间被外部删除(例如通过
kubectl delete)时,才会记录runs_not_stored_count。只有满足以下所有条件时,该指标才不会为空:
--logs_api标志为false(禁用日志存储);如果启用了日志,Watcher 会完全跳过基于 finalizer 的协调。--disable_crd_update标志为false(启用 annotation 更新)。--store_deadline标志设置为非零时长;这是 Watcher 在放弃并允许删除之前等待归档完成的最长时间。- 运行在成功归档之前被外部删除(没有
results.tekton.dev/stored=trueannotation),并且store_deadline已经过期。在正常运行中(运行在删除前已完成归档,或删除由 Watcher 通过
--completed_run_grace_period自身触发),该计数器保持为零。非零值表示可能存在数据丢失:运行在其状态保存到 Results API 之前就被删除。
快速复现(测试环境): 如果看不到此指标,通常意味着未满足触发条件,而不是指标缺失。
- 通过
TektonConfig配置 Results Watcher,使logs_api=false、disable_crd_update=false和store_deadline为非零值(例如30s)。- 通过
TektonConfig(spec.result.options.deployments.tekton-results-api.spec.replicas: 0)暂时将 Results API 副本数设置为0,使运行无法归档。- 创建一个 TaskRun 或 PipelineRun,并等待其完成。
- 等待
store_deadline经过,然后从外部删除该运行(kubectl delete ...)。- 检查 Watcher 的
/metrics,或在 Prometheus 中检查watcher_runs_not_stored_count(exposition 格式中的组件前缀名称);其值应增加。- 恢复原始的
TektonConfig(重新启用 Results API 副本并恢复正常的logs_api设置)。
run_storage_latency_seconds 直方图使用以下桶边界(以秒为单位):
Watcher config-observability
Results Watcher 有自己的 config-observability ConfigMap(其名称通过 CONFIG_OBSERVABILITY_NAME 环境变量指定,通常为 tekton-results-config-observability)。此 ConfigMap 由 Tekton Operator 管理,应通过 TektonConfig 资源的 spec.result.options.configMaps 字段进行配置。详情请参阅调整子组件的可选配置项。
热重载行为:Results Watcher 也会监视此 ConfigMap,并在无需重启 Pod 的情况下应用大多数键的更改。只有更改 Deployment 级别的设置(例如 env/args)时才需要重启。
它支持以下键:
注意:与 Tekton Pipelines 不同,Results Watcher 不支持
pipelinerun/taskrun这种单个运行粒度级别。它也没有metrics.count.enable-reason、metrics.running-pipelinerun.level或metrics.taskrun.throttle.enable-namespace键。上游已知问题:
taskrun_delete_duration_seconds使用metrics.pipelinerun.duration-type(而不是metrics.taskrun.duration-type)来确定聚合类型。这似乎是 Results 源代码中的复制粘贴错误。
API Server 指标
API server 通过 go-grpc-prometheus 库在端口 9090 上公开标准 gRPC Prometheus 指标。这些指标包括:
grpc_server_handled_total- server 上完成的 RPC 总数grpc_server_started_total- server 上启动的 RPC 总数grpc_server_msg_received_total/grpc_server_msg_sent_total- 消息数量grpc_server_handling_seconds(如果启用了PROMETHEUS_HISTOGRAM)- RPC 处理持续时间
Tekton Chains
Tekton Chains 是一个安全组件,用于为使用 Tekton Pipelines 构建的制品生成、签名并存储来源信息。它会监视已完成的 TaskRun 和 PipelineRun,然后创建证明和签名。
Chains controller 指标使用前缀 watcher_(与 Results Watcher 相同,但自定义指标名称不同,因此不会发生冲突)。
Chains 指标
所有 Chains 指标均为不带标签的 Counter。
注意:官方 Tekton Chains 文档还提到了 TaskRun 和 PipelineRun 的
*_signing_failures_totalCounter,但当前上游源代码中并不存在这些指标。请根据已部署的版本进行确认。
Controller Framework 指标
所有 Tekton controller 都会自动公开以下基础设施指标。这些指标使用与组件自定义指标相同的前缀(例如 tekton_pipelines_controller_、controller_、watcher_)。
设置 ServiceMonitor
要启用对 Tekton 组件的 Prometheus 抓取,请部署 ServiceMonitor 资源。
前置条件请参阅前置条件。
请根据您使用的监控栈参阅以下指导:
- 如果您使用 Prometheus(Prometheus Operator),则
metadata.labels.prometheus: kube-prometheus等标签必须与 Prometheus CRspec.serviceMonitorSelector匹配;否则,此ServiceMonitor不会被抓取。 - 如果您使用 VictoriaMetrics,通常不需要
prometheus: kube-prometheus等标签;请根据您的监控设置创建ServiceMonitor/VMServiceScrape。
使用 Prometheus 时,请使用以下命令查找并验证 selector:
如果集群中不存在 Prometheus CR,则监控通常由平台管理(例如 VictoriaMetrics),或采用了其他实现方式。在这种情况下,通常不需要 prometheus: kube-prometheus 等标签;请遵循平台的抓取规则。
有关更多信息,请参阅 集成外部指标。
Pipeline ServiceMonitor
Pipeline ServiceMonitor YAML
此 ServiceMonitor 会匹配带有 app.kubernetes.io/part-of: tekton-pipelines 标签的 Pipeline 服务(包括 remote-resolvers),并抓取 tekton-pipelines 命名空间中的服务。
Triggers ServiceMonitor
Triggers ServiceMonitor YAML
此 ServiceMonitor 仅收集 Triggers controller 指标(controller_*)。它不包含 EventListener sink 指标。
EventListener Sink ServiceMonitor
EventListener Sink ServiceMonitor YAML
EventListener Service 通常运行在应用命名空间中,因此此示例使用
namespaceSelector.any: true进行跨命名空间抓取。如果需要更严格的范围,请切换为matchNames,并显式列出允许的命名空间。
Results ServiceMonitor
Results 服务同时具有 app.kubernetes.io/part-of: tekton-results 和 app.kubernetes.io/name 标签。为了精确定位 API + Watcher 并排除 Postgres,此示例匹配 app.kubernetes.io/name:
Results ServiceMonitor YAML
Results API server 使用端口名称
prometheus(9090),Watcher 使用端口名称metrics(9090)。每个服务只公开其中一个端口名称,因此只会抓取匹配的端点。
Chains ServiceMonitor
Chains ServiceMonitor YAML
验证
部署 ServiceMonitor 资源后,验证 Prometheus 是否正在抓取目标。
直接检查指标端点
EventListener sink 指标(例如
eventlistener_event_received_count和eventlistener_http_duration_seconds)由请求驱动。在验证这些指标之前,至少向 EventListener 发送一个请求。
检查 Prometheus 目标
PromQL 查询示例
监控面板示例
以下 MonitorDashboard 资源提供了用于监控 Tekton 组件的开箱即用监控面板。将其部署到 cpaas-system 命名空间下的 tekton 文件夹中。
重要:每个图表都必须包含
id(唯一整数)、datasource: prometheus和transformations: []。每个目标都必须包含datasource: prometheus和refId。本文档中的持续时间 P50/P95 图表使用*_bucket查询,并要求使用metrics.*.duration-type=histogram;如果使用lastvalue,请将这些查询替换为 LastValue 风格的表达式,例如avg_over_time(...)。
Tekton Pipeline 监控面板
Tekton Pipeline Dashboard YAML
Tekton Pipeline 监控面板解读(常见问题)
PipelineRun Total (by status)是由 controller 记录的完成事件计数器,而不是 PipelineRun 对象的总数。在当前实现中,用户触发的取消操作(spec.status=Cancelled)可能不会进入此计数路径,因此cancelled系列可能不存在。要验证取消量,请检查 PipelineRun 对象和事件。Running PipelineRuns是实时快照(当前正在运行的数量)。它可以独立于PipelineRun Total发生变化。Completed PipelineRuns (last 5m)是吞吐量(过去 5 分钟内新完成的运行次数)。在低流量或空闲期间看到0是预期行为。PipelineRun Success Rate (cumulative)是 controller 启动以来的累计值,而不是 5 分钟窗口内的成功率。短期故障不会立即导致数值大幅变化。Reconcile Count (by success)衡量的是 controller reconcile 循环,而不是 PipelineRun 数量。- 只有在所选时间范围内实际存在样本的标签值才会显示状态系列。如果某个状态在该时间窗口内没有样本,则不会显示其曲线或图例。
TaskRun Duration P50 / P95 (Standalone)和TaskRun Duration P50 / P95 (In-Pipeline)分开显示,以避免混合查询不稳定。在仅公开其中一个直方图系列的环境中,另一个图表可能为空,这是预期行为。
Tekton Triggers 监控面板
Tekton Triggers Dashboard YAML
Tekton Triggers 监控面板解读(常见问题)
EventListener Count、TriggerTemplate Count、TriggerBinding Count、ClusterTriggerBinding和ClusterInterceptor是对象数量快照,而不是请求量或事件处理吞吐量。All Trigger Resource Counts (trend)显示相同资源数量的综合趋势。与单资源趋势图表相比,在一个抓取间隔内出现短暂偏差是预期行为。- 在不存在 Triggers 资源时显示
0属于正常现象,并不表示抓取失败。
Tekton Results 监控面板
Tekton Results Dashboard YAML
Tekton Results 监控面板解读(常见问题)
- 此监控面板版本基于 Results Watcher
reconcile/workqueue指标以及 Results API gRPC 指标,因此在常见部署配置(logs_api=true、禁用自动删除)下仍会显示数据。 PipelineRun Reconcile Count (last 5m)和TaskRun Reconcile Count (last 5m)分别显示success=true和success=false在 5 分钟内的增量。PipelineRun Reconcile Latency P95和TaskRun Reconcile Latency P95根据 watcher reconcile 延迟直方图计算。在低流量情况下,曲线可能较为稀疏。Workqueue Depth显示当前队列深度,Workqueue Adds (last 5m)显示过去 5 分钟内的入队量。gRPC Error Percentage (Results API, excl. NotFound/Canceled)是异常错误占全部请求的百分比,其中排除了常见业务返回码(NotFound、Canceled)。
Tekton Chains 监控面板
Tekton Chains Dashboard YAML
Tekton Chains 监控面板解读(常见问题)
TaskRun Signatures Created (last 5m)、PipelineRun Signatures Created (last 5m)、Payloads Stored (last 5m)和Marked Signed (last 5m)使用increase(...[5m]),表示过去五分钟内的增量。- 没有新的签名或存储活动时,这些曲线会降至
0;这并不表示组件发生故障。 Payloads Stored和Marked Signed表示不同的处理阶段,因此其值不一定始终匹配。