Argo Workflows 遥测体系详解Metrics、Tracing 与 Logs 三大信号的配置与实战【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows本文围绕 Argo Workflows 的遥测Telemetry体系展开系统讲解 workflow-controller、argoexec、argo-server 与 CLI 如何通过 OpenTelemetry 协议与 Prometheus 暴露标准观测信号——指标Metrics、追踪Tracing与日志Logs。读完本文你将掌握遥测的启用条件、ConfigMap 与环境变量的完整配置方法、内置控制器指标与自定义工作流指标的定义方式、追踪 Span 的语义以及基于 Grafana Tempo Prometheus Grafana 的端到端可观测性落地路径。遥测体系总览三大标准信号Argo Workflows 发射的是业界标准的可观测性信号参见 docs/telemetry.md 与 docs/telemetry-configuration.md指标Metrics由 workflow-controller 发射控制器级与工作流级指标可通过 OpenTelemetry 协议OTLP或 Prometheus 抓取两种方式采集。argo-server 也通过 Prometheus 抓取提供指标但该部分在文档中几乎没有任何公开说明属未记录功能。追踪Tracing通过 OpenTelemetry 协议从 workflow-controller 与 argoexec 传输 Span展示工作流的执行性能argo-server 目前尚无追踪支持。日志Logs所有组件argo-server、CLI、workflow-controller、argoexec均向 stderr 输出日志日志级别与格式可通过命令行参数控制。这三个信号覆盖了从控制器自身运行状态到单个工作流节点执行细节的完整观测链路指标回答系统现在怎么样追踪回答一次执行经历了什么、慢在哪里日志回答出错时的原始上下文是什么。一、Metrics指标采集Argo Workflows 的指标分为两类控制器指标controller metrics与自定义指标custom metrics详见 docs/metrics.md。控制器指标回答控制器当前的状态是什么默认可从workflow-controller-metrics服务的host:9090/metrics端点抓取。自定义指标由用户在 Workflow Spec 中定义回答某一类工作流或某系列工作流的状态是什么。指标发射的正确性由发射方即定义工作流的用户负责。1.1 OpenTelemetry 指标推荐OpenTelemetry 是官方推荐的指标采集方式。它的通用配置与追踪共用如下必须设置环境变量OTEL_EXPORTER_OTLP_ENDPOINT或信号专属端点OTEL_EXPORTER_OTLP_METRICS_ENDPOINT/OTEL_EXPORTER_OTLP_TRACES_ENDPOINT。该变量必须设置在 workflow-controller 上理想情况下也应设置在负载的所有容器main、init、wait上。只有当这些端点被配置且非空时OTLP 才会启用。协议默认使用 gRPC要切换为 HTTP设置OTEL_EXPORTER_OTLP_PROTOCOL或信号专属的OTEL_EXPORTER_OTLP_METRICS_PROTOCOL/OTEL_EXPORTER_OTLP_TRACES_PROTOCOL为http/protobuf。其余协议参数遵循 OpenTelemetry 标准环境变量约定。可以使用 OpenTelemetry Operator 部署 Collector 并对 workflow-controller 进行注入也可用它为你的工作负载 Pod 插桩使其 Span 纳入工作流追踪体系——这是官方推荐的做法。OpenTelemetry Collector 可通过 Prometheus Remote Write Exporter 将指标转发给 Prometheus。典型 Collector 配置接收 OTLP gRPCreceivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317Temporality时间性可以在 Workflow Controller ConfigMap 中配置 OpenTelemetry 指标的时间性默认值为Cumulative累计可选Delta增量。该配置项在 3.6 版本起可用metricsConfig: | # 3.6. 选择 OpenTelemetry 使用的时间性。默认 Cumulative temporality: Delta在源码 config/config.go 中MetricsTemporality定义了Cumulative与Delta两个枚举GetTemporality()据此返回对应的 SDK TemporalitySelector未配置时回退到 OpenTelemetry SDK 的默认选择器metricsdk.DefaultTemporalitySelector。注意下述metricsTTL、modifiers与temporality会影响 OpenTelemetry 行为而其他 Prometheus 专属参数不会。1.2 Prometheus 抓取Argo 的安装并不自带指标 Service若要配合 Prometheus ServiceMonitor 使用需要自行添加。如果存在多个控制器 Pod例如以热备 high-availability 方式部署应使用无头服务headless service确保每个 Pod 都被抓取、不遗漏指标。官方给出的 Service ServiceMonitor 示例cat EOF | kubectl apply -f - apiVersion: v1 kind: Service metadata: labels: app: workflow-controller name: workflow-controller-metrics namespace: argo spec: clusterIP: None ports: - name: metrics port: 9090 protocol: TCP targetPort: 9090 selector: app: workflow-controller --- apiVersion: monitoring.coreos.com/v1 kind: ServiceMonitor metadata: name: argo-workflows namespace: argo spec: endpoints: - port: metrics selector: matchLabels: app: workflow-controller EOF在 Workflow Controller ConfigMap 中可调整 Prometheus 指标的配置项metricsConfig: | # Enabled 控制 prometheus 指标开关。默认 true设置 enabled: false 可关闭 enabled: true # Path 是 prometheus 指标暴露的路径。必须以 / 开头。默认 /metrics path: /metrics # Port 是 prometheus 指标暴露的端口。默认 9090 port: 8080 # IgnoreErrors 指示 prometheus 忽略指标发射错误。默认 false ignoreErrors: false # 使用自签名证书启用 TLS secure: true要点该机制发射的指标名以argo_workflows_为前缀Attributes以同名 Prometheuslabels暴露。非 leader 的 workflow-controller 会返回空指标leader 概念参见 docs/high-availability.md。通过端口转发可查看指标kubectl -n argo port-forward deploy/workflow-controller 9090:9090然后在浏览器访问https://localhost:9090/metrics单副本部署时。UTF-8 兼容性Argo v3.7 升级了github.com/prometheus/client_golangNameValidationScheme改为UTF8Validation指标名可保留原始分隔符如.而不再替换为下划线。若要维持旧行为可设置环境变量PROMETHEUS_LEGACY_NAME_VALIDATION_SCHEME。1.3 通用指标设置与 Modifiers在 ConfigMap 的metricsConfig中可统一调节metricsConfig: | # MetricsTTL 设置自定义指标多久从内存中清除一次。默认 0 表示永不清除。直方图指标永不清除。 metricsTTL: 10m # Modifiers 允许对每个已发射的指标进行调优 modifiers: pod_missing: disabled: true cronworkflows_triggered_total: disabledAttributes: - name k8s_request_duration: histogramBuckets: [ 1.0, 2.0, 10.0 ]Modifiers 可作用于内置指标与自定义指标每个 modifier 只作用于指定名称的指标且对所有输出方式生效disabled: true完全停止该指标的发射。disabledAttributes禁用指定的属性标签。指标仍会发射只是该属性缺失其余属性值仍会被正确聚合。典型用途是降低指标基数cardinality。histogramBuckets仅对直方图指标有效修改桶的边界值所有值必须是浮点数。metricsTTL的底层逻辑在 workflow/metrics/metrics.go 中体现New()会启动go metrics.customMetricsGC(ctx, config.TTL)协程周期性地清理内存中的自定义指标。1.4 内置控制器指标指标分为计数器counter、仪表gauge与直方图histogram三类其语义由 OpenTelemetry 定义counter单调递增的累积值如同汽车里程表其变化速率是强有力的分析工具。gauge读取时刻的当前值如同油表。histogram客户端侧聚合的值分布如请求延迟适合回答多少请求耗时少于 1 秒这类统计问题。对应四大黄金信号的内置指标包括延迟Latencyqueue_latency流量Trafficgauge与queue_depth_gauge错误Errorscount与error_count饱和度Saturationworkers_busy与workflow_condition以下是全部内置控制器指标一览完整属性说明见 docs/metrics.md属性表为自动生成指标名类型说明client_rate_limiter_latencyhistogram客户端 client-go 限流器等待耗时默认开启默认桶 0.01~180cronworkflows_concurrencypolicy_triggeredcounterCronWorkflow 触发concurrencyPolicy限制运行的次数属性含name⚠️、namespace、concurrency_policycronworkflows_triggered_totalcounterCronWorkflow 被触发总次数Forbid抑制的运行不计数deprecated_featurecounter已废弃特性被使用的次数feature属性error_countcounter控制器按原因计数的错误causeOperationPanic、CronWorkflowSubmissionError、CronWorkflowSpecErrorgaugegauge集群中处于各 phase 的工作流数量phase属性is_leadergauge是否为 leader1/0关闭 leader 选举时恒为 1k8s_request_durationhistogram发往 Kubernetes API 的请求耗时kind/verb/status_codek8s_request_totalcounter发往 Kubernetes API 的请求数可由k8s_request_duration推导locks_held/locks_pending/locks_taken_totalgauge / gauge / counter同步锁持有数、等待数、获取总数type/storage/lock_name⚠️/namespacelog_messagescounter控制器按级别error/warn/info输出的日志条数operation_duration_secondshistogram单次工作流调谐reconciliation循环的耗时衡量控制器性能pod_missingcounter未观测到 Pod 的次数如被 Kubernetes 删除通常只在高负载下出现pod_pending_countcounter处于 pending 的 Pod 数按reason汇总pod_restarts_totalcounter因基础设施故障如节点驱逐在主容器启动前被自动重启的 Pod 数pods_gauge/pods_total_countgauge / counter各 phase 的工作流 Pod 数量 / 进入各 phase 的 Pod 总数queue_adds_count/queue_depth_gauge/queue_duration/queue_latency/queue_longest_running/queue_retries/queue_unfinished_work混合控制器内部工作队列cron_wf_queue、pod_cleanup_queue、workflow_queue、workflow_ttl_queue、workflow_archive_queue的各类度量直接源自 client-go workqueueresource_rate_limiter_latencyhistogram资源创建限流器造成的延迟默认关闭total_countcounter工作流进入各 phase 的计数按 namespaceversiongauge控制器构建元数据version、platform、go_version、build_date、compiler、git_commit等workers_busy_countgauge各队列忙碌的 worker 数workflow_conditiongauge具有不同 condition 的工作流数量目前仅PodRunningworkflowtemplate_runtimehistogram使用workflowTemplateRef的工作流运行时不含 Pending 时间workflowtemplate_triggered_totalcounter使用workflowTemplateRef的工作流进入各 phase 的计数注意部分属性的基数可能很高文档中以 ⚠️ 标记例如cronworkflows_*的name、锁指标的lock_name、模板指标的name必要时应禁用该指标或该属性见上文 Modifiers。operation_duration_seconds的桶大小默认由环境变量OPERATION_DURATION_METRIC_BUCKET_COUNT与MAX_OPERATION_TIME配置除非在metricsConfig中用histogramBucketsmodifier 显式指定pod_missing的recently_started属性由环境变量RECENTLY_STARTED_POD_DURATION控制默认 10 秒。在源码层面所有内置指标都在 workflow/metrics/metrics.go 的New()中通过populate()批量注册包括addIsLeader、addPodPhaseGauge、addCronWfTriggerCounter、addLocksGauges、addWorkQueueMetrics、addK8sRequests等 20 余个注册函数version与deprecated_feature则通过telemetry.AddVersion、telemetry.AddDeprecationCounter注入。1.5 自定义工作流指标Workflow 内定义自定义指标直接在 Workflow/Step/Task 上就地定义详见 docs/workflow-telemetry.md。关键规则指标在 Workflow/Step/Task完成后才被处理实时指标除外定义放在 yaml 的prometheus标签下历史遗留命名并通过所有已启用的协议发射。每个指标必须包含name与help文档字符串name相同则help字符串必须完全一致Prometheus 硬性要求且不得改变指标类型。标签可定义任意数量注意避免基数爆炸指标名只能包含字母数字与_兼容 Prometheus 与 OpenTelemetry即使只用其中一个协议。所有指标可通过when子句条件发射语义与工作流中其他when一致。指标类型为gauge、histogram、counter之一类型内必须指定value可以是字面值或 Argo 变量。直方图必须提供buckets。Argo 变量可用在指标定义的任何位置labels、name、help、when等。Workflow 级 Gauge 指标示例上报工作流时长发射时名称会被加上argo_workflows_前缀apiVersion: argoproj.io/v1alpha1 kind: Workflow metadata: generateName: model-training- spec: entrypoint: steps metrics: prometheus: - name: exec_duration_gauge # 指标名发射时前缀 argo_workflows_ labels: # 标签可选。避免基数爆炸。 - key: name value: model_a help: Duration gauge by name # 指标说明文档。必填。 gauge: # 指标类型gauge、histogram、counter value: {{workflow.duration}} # 指标值。可以是 Argo 变量或字面值Gauge 支持可选的operation标志取值必须为Set、Add或Sub未指定时等价于operation: SetSet让 gauge 报告valueAdd/Sub在现值上增减。Template 级 Counter 指标示例每次步骤失败时递增计数templates: - name: flakey metrics: prometheus: - name: result_counter help: Count of step execution by result status labels: - key: name value: flakey - key: status value: {{status}} # labels 中使用 Argo 变量 when: {{status}} Failed # 条件发射用法与普通 when 相同 counter: value: 1 # 使计数器加 1 container: image: python:alpine3.23 command: [python, -c] args: [import random; import sys; exit_code random.choice([0, 1, 1]); sys.exit(exit_code)]Template 级 Histogram 指标示例跟踪内部数值直方图的桶属于指标描述符的一部分同一系列的所有指标桶必须一致templates: - name: random-int metrics: prometheus: - name: random_int_step_histogram help: Value of the int emitted by random-int at step level when: {{status}} Succeeded # 仅当步骤成功时发射 histogram: buckets: # 直方图必须定义桶 - 2.01 - 4.01 - 6.01 - 8.01 - 10.01 value: {{outputs.parameters.rand-int-value}} outputs: parameters: - name: rand-int-value globalName: rand-int-value valueFrom: path: /tmp/rand_int.txt container: image: alpine:3.23 command: [sh, -c] args: [RAND_INT$((1 RANDOM % 10)); echo $RAND_INT; echo $RAND_INT /tmp/rand_int.txt]实时指标Real-Time MetricsArgo 支持有限的实时指标——从步骤执行开始到结束实时发射。仅 Gauge 类型且仅限有限的变量集见 docs/variables.md。定义方式是在 gauge 上添加realtime: truegauge: realtime: true value: {{duration}}1.6 指标设计建议与历史数据Prometheus 指标应被理解为运行进程的瞬时数据点适合上报失败次数、工作流时长、训练得分等不适合存放历史数据如单次实例的状态、单步耗时。指标是短暂的不保证持久化需要历史分析时应使用 工作流归档 或日志。要分析工作流随时间的行为需要用相同的指标描述符指标名 键值标签把不同实例串联成系列。例如argo_workflows_model_exec_time{model_namemodel_a,phasevalidation}与...{model_namemodel_b,...}是不同指标、各自跟踪独立系列——因此固定使用相同名称与标签是跨时间链接指标的关键。二、Tracing分布式追踪Argo Workflows 使用 OpenTelemetry 协议支持分布式追踪详见 docs/tracing.md。2.1 状态与限制追踪目前处于Beta状态未视为完成可能在未来次要版本中以不兼容方式变更例如计划采纳 OpenTelemetry Semantic Conventions。在一个 workflow-controller 中开始、因控制器重启而在另一个 workflow-controller 中结束的 Span 将不完整长生命周期 Span 的管理仍在推进中。2.2 配置追踪完全通过 OpenTelemetry 环境变量配置与指标共用上文OpenTelemetry一节的通用配置设置OTEL_EXPORTER_OTLP_ENDPOINT或OTEL_EXPORTER_OTLP_TRACES_ENDPOINT即启用默认 gRPC 协议可通过OTEL_EXPORTER_OTLP_TRACES_PROTOCOLhttp/protobuf切换。2.3 主要 Span 与追踪结构追踪以Workflowtrace 为主干属性name、namespace其子 Span 包括控制器侧workflow-controller 发射startup_controller→startup_cache_sync控制器启动与 informer 缓存同步workflow→node属性node_id、name、namespace、node_type→node_phase工作流生命周期内每个 DAG 节点及其阶段reconcile_workflow→pod_reconciliation/reconcile_task_results→reconcile_task_result实际状态与期望状态的调谐create_workflow_pod属性node_id为节点创建 Podpersist_updates将工作流状态更新持久化到 Kubernetesworkflow_phase属性phase工作流的每个阶段try_acquire_lock属性lock_name⚠️、acquired获取同步锁wait_client_rate_limiter等待 Kubernetes 客户端限流器受 workflow-controller 的--qps、--burst控制。executor 侧argoexec 发射run_init_container/run_main_container/run_supervisor_containerinit-less 模式/run_wait_container属性name、namespacerun_workload你的工作负载若启用 OpenTelemetry 追踪其 Span 将出现在此处Argo 自身不发射此 Span仅作占位stage_files暂存脚本或清单文件load_artifacts→load_artifact属性path→unarchive_artifact属性archivenone/zip/tarsave_artifacts→save_artifact→archive_artifactsave_logs→save_container_logs属性container_namecapture_script_result、create_task_result、patch_task_result、patch_task_result_labels、process_data_template、wait_workload等。完整的 Span 参考含全部属性见 docs/tracing.md。三、Logs日志输出所有组件argo-server、CLI、workflow-controller、argoexec的日志都从stderr输出。日志级别由以下命令行参数控制详见 docs/telemetry-configuration.mdflag默认值有效值--log-levelinfodebug、info、warn、error--log-formattexttext、json--gloglevel0整数例如6一般建议将log-format设为json以获得易于查询的结构化日志。workflow-controller 会把这些 flag 自动透传给 argoexec 容器如需在 argoexecexecutor上覆盖可在 Workflow Controller ConfigMap 中配置。--gloglevel设置 Kubernetes 客户端kloglogger 的冗长级别与 Argo 日志级别相互独立控制 Kubernetes Go 客户端库的输出仅在调试 Kubernetes API 交互时需要设置。在源码 cmd/workflow-controller/main.go 中可见--gloglevel默认 0与--log-format默认text等 flag 的定义。四、端到端实战用 OTel Collector Tempo Prometheus Grafana 观测工作流docs/telemetry-getting-started.md 提供了一套开箱即用的动手指南作者明确声明这是观点性指南用于看到效果并非参考架构或生产推荐也未做安全加固请按环境调整组件与配置。其数据流如下workflow-controller 与 argoexec 通过 gRPC 向 OpenTelemetry Collector 发送 Span 与指标Collector 通过 OTLP HTTP 将追踪转发给 Tempo、通过 Remote Write 将指标转发给 PrometheusGrafana 同时查询 Prometheus 与 Tempo。Step 1部署 Argo Workflows 与观测栈。仓库内置了 manifests/quick-start-telemetry.yaml自动生成清单一次安装 Argo Workflowscontroller、server、MinIO、OpenTelemetry Collector接收 OTLP gRPC/HTTP 并转发到 Tempo 与 Prometheus、Grafana Tempo、Prometheus启用 remote write 接收与 Grafana预置 Tempo 与 Prometheus 数据源。其中 workflow-controller 已配置指向 Collector 的OTEL_EXPORTER_OTLP_ENDPOINTexecutor 的 ConfigMap 也包含 OTEL 环境变量使 argoexec 同样发送追踪kubectl create namespace argo kubectl apply -n argo --server-side -f manifests/quick-start-telemetry.yaml kubectl wait -n argo --forconditionReady pod --all --timeout120sStep 2访问 Grafanakubectl port-forward svc/grafana -n argo 3000:3000打开http://localhost:3000匿名 admin 访问已启用、无需登录Tempo 与 Prometheus 数据源已预置。Step 3运行工作流并查看追踪。提交 DAG 钻石示例 examples/dag-diamond.yamlargo submit -n argo --watch examples/dag-diamond.yaml工作流完成后在 Grafana 中查看追踪进入Explore→ 选择Tempo数据源 →Search标签页 → 选择Service Name查找 workflow-controller 服务→Run query→ 点击某条 trace。你将看到类似如下的 Span 层级workflow—— 工作流的整个生命周期nodeDAG 每个节点 A、B、C、D 各一个createWorkflowPod—— Pod 创建reconcileWorkflow—— 调谐循环每个工作流 Pod 还会产生来自 argoexec 的 SpanrunInitContainer、runMainContainer、runWaitContainer及其子 Span。Step 4查看指标。在 Explore 中选择Prometheus数据源可尝试以下 PromQL# 当前运行中的工作流数 gauge{phaseRunning} # 5 分钟内工作流阶段计数器速率 rate(total_count_total{phaseError}[5m]) # 操作耗时p95 histogram_quantile(0.95, rate(operation_duration_seconds_bucket[5m]))清理kubectl delete namespace argo即可移除本指南创建的全部资源。五、深入源码遥测实现要点从源码结构看遥测实现集中在以下位置可供继续深入配置定义config/config.go 中MetricsConfig同时承载metricsConfig与telemetryConfig两个 ConfigMap 键config/config.go 定义了MetricsConfig结构enabled、path、port、ignoreErrors、secure、metricsTTL、modifiers、temporality及GetTemporality()的实现。指标注册workflow/metrics/metrics.go 的New()统一创建基于 OpenTelemetry SDK 的指标对象注册version与deprecated_feature随后通过populate()批量注册全部内置指标并启动customMetricsGC协程按metricsTTL清理自定义指标。指标采集器目录workflow/metrics 下按指标类型拆分实现例如counter_pod_phase.go、gauge_workflow_phase.go、histogram_durations.go、work_queue.go、metrics_k8s_request.go、metrics_custom.go等并配套*_test.go测试。日志 flagcmd/workflow-controller/main.go 定义--gloglevel、--log-format等参数。六、继续阅读docs/telemetry.md —— 遥测体系总览本文主题文档docs/telemetry-configuration.md —— 环境变量与 ConfigMap 完整配置docs/telemetry-getting-started.md —— OpenTelemetry 快速上手docs/metrics.md —— 全部内置指标与自定义指标细节docs/tracing.md —— 完整 Span 参考docs/workflow-telemetry.md —— 工作流内自定义指标docs/workflow-controller-configmap.md —— Workflow Controller ConfigMap 说明【免费下载链接】argo-workflowsWorkflow Engine for Kubernetes项目地址: https://gitcode.com/gh_mirrors/ar/argo-workflows创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考