尧图网页设计 
OneUptime Kubernetes Agent 安装与配置全指南从 Helm 快速部署到 eBPF 自动埋点与持续 CPU 性能剖析【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime Kubernetes Agent 是 OneUptime 平台在 Kubernetes 集群内的数据采集组件负责收集集群指标、事件、Pod 日志、应用级 TracesHTTP/gRPC基于 eBPF以及OS 级别节点指标并通过 OpenTelemetry 协议OTLP上报到 OneUptime。本文以项目文档 kubernetes-agent.md 为主体结合 Helm Chart 源码values.yaml 与各模板文件逐项讲解安装、预设选择、两种日志采集模式、eBPF 自动插桩的调优与取舍以及升级、卸载与故障排查的完整操作。读完本文你将能独立完成 Agent 在任意主流 Kubernetes 发行版上的安装、按集群特性选择正确 preset、精细控制日志/追踪/剖析功能的开销并能在出问题时快速定位根因。快速开始一条命令接入集群Agent 以 Helm Chart 形式分发官方 Chart 仓库地址为oneuptime/kubernetes-agent当前 Chart 版本见 Chart.yaml。最小安装只需三步helm repo add oneuptime https://helm-chart.oneuptime.com helm repo update helm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameA_UNIQUE_NAME_FOR_THIS_CLUSTER安装完成后你的集群会在几分钟内出现在 OneUptime 界面中。三个必填参数的含义参数说明oneuptime.url你的 OneUptime 实例地址如https://oneuptime.comoneuptime.apiKey项目 API 密钥在 OneUptime 的Settings → API Keys设置 → API 密钥中创建clusterName该集群的唯一名称会被打标为每条记录的k8s.cluster.name属性从 values.yaml 的注释可以看到clusterName并非普通标签OneUptime 会把k8s.cluster.name折叠进它派生的每个 Kubernetes 实体的身份中它是区分本集群worker-1节点与default命名空间同其他集群的唯一依据。两个未设置clusterName的集群会被静默合并成同一份资产因此渲染时 Chart 会强制校验该值缺失则拒绝安装。为你的集群选择正确的 preset不同 Kubernetes 发行版对宿主访问的限制差异巨大——最关键的差异是工作负载能否挂载hostPath卷。为避免用户逐一阅读安全文档Chart 只暴露一个顶层开关preset它会自动选择兼容的默认值包括日志采集模式与安全上下文。Preset适用场景日志采集方式备注standard默认自建集群、EKS on EC2、GKE Standard、AKS、minikube、kind、k3s通过 hostPath 读取/var/log/pods的 DaemonSet开销最低这些平台上 hostPath 可用gke-autopilotGKE Autopilot基于 Kubernetes API tail 的 DeploymentAutopilot 屏蔽了 hostPath会套用一份足以通过 Autopilot Pod Security Standards 的加固安全上下文eks-fargateEKS Fargate基于 Kubernetes API tail 的 Deployment与gke-autopilot相同Fargate 同时屏蔽 hostPath 与 DaemonSet不确定时保持preset不设置即可会得到standard默认值。如果安装时被一条提及hostPath的 Pod Security 错误拒绝切换到gke-autopilotEKS Fargate 上用eks-fargate重新安装即可。三种场景的安装示例GKE Standard、EKS on EC2、自建集群或 AKShelm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprodGKE Autopilothelm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprod-gke-autopilot \ --set presetgke-autopilotEKS Fargatehelm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprod-eks-fargate \ --set preseteks-fargate两种日志采集模式的区别preset在底层只是设置了logs.mode的值——你也可以直接设置logs.mode来覆盖 preset 的默认值显式值永远优先见 values.yaml 中的logs.mode注释。DaemonSet 模式logs.mode: daemonset每节点运行一个 OpenTelemetry Collector Pod通过 hostPath 卷读取/var/log/pods/下的日志文件并经 OTLP 转发。对应模板 daemonset.yaml 中可以看到该 DaemonSet 以只读方式挂载了宿主的/var/log/pods。优点开销最低随节点数线性扩展完全不增加 Kubernetes API Server 的负载且能正确处理日志轮转。缺点需要 hostPath 和 DaemonSet 调度能力——这两者在 GKE Autopilot 与 EKS Fargate 上均不可用。API 模式logs.mode: api一个单副本 Deployment使用oneuptime/kubernetes-log-tailer镜像通过 Kubernetes API 流式拉取容器日志——与kubectl logs -f使用同一 endpoint。无需 hostPath、无宿主访问、无 DaemonSet。优点可在 GKE Autopilot、EKS Fargate 以及任何屏蔽 hostPath 或强制restrictedPod Security Standard 的集群上运行。缺点每个容器流都是与 kube-apiserver 的一条长连接单副本通常只能承载数千个容器。超大集群需要按 namespace 分片部署多份 release使用namespaceFilters.rules中podLogsscope 的 include 规则。从 deployment-logs-api.yaml 可以看到 API 模式的加固细节容器以非 rootrunAsUser: 1000运行、allowPrivilegeEscalation: false、只读根文件系统、丢弃全部 capabilities并通过livenessProbe/readinessProbe暴露/healthz端口 13133。这正是它能通过 Autopilot 这类严格平台安全审查的原因。该如何选择如果 hostPath 可用用 DaemonSet其余场景用 API 模式。preset会替你选好。也可以完全关闭日志采集--set logs.enabledfalse改用 OpenTelemetry SDK 直接从应用发送日志。此时节点 Collector 仍会继续运行并采集 kubelet / cAdvisor / 主机指标只是停止读取 Pod 日志values.yaml 的logs.enabled注释对此有明确说明。基于 eBPF 的应用 Traces 与 HTTP 请求指标默认开启Chart 会在每个节点上部署一个运行 OpenTelemetry eBPF InstrumentationOBI。OBI 把 eBPF 程序加载进 Linux 内核监控 socket 层流量从而重建每个 Pod 的 HTTP/HTTPS、gRPC 与 SQL/Redis 调用——不需要改代码、不需要 SDK、不需要 sidecar。捕获的流量以 OTLP Traces 与请求/延迟指标的形式直接上报 OneUptime。安装后约一两分钟内你的服务就会出现在Products → Traces产品 → 追踪与服务拓扑图中且每条记录带有k8s.cluster.nameclusterName可按集群过滤。模板中值得注意的实现细节OBI 以privileged: true运行并设置hostPID: true因为它需要特权来加载 eBPF 程序、查看节点上所有进程挂载了bpffs/sys/fs/bpf用于固定 eBPF map日志富化、profile 关联等功能依赖它挂载了tracefs与debugfs供stats特性挂接sock/inet_sock_set_state等内核 tracepoint以产出 TCP RTT、连接失败与重传指标OTEL_EBPF_METRICS_FEATURES由ebpf.features.*渲染而来环境变量与 YAML 配置合并时以环境变量优先因此 values.yaml 中的开关保持权威。何时应该关闭它eBPF默认开启。以下情况应设置--set ebpf.enabledfalse安装在GKE Autopilot或EKS Fargate上。这些平台屏蔽特权 Pod而 OBI 需要特权态才能加载 eBPF 程序。节点内核低于Linux 5.8且无 BTF backport现代发行版——Debian 11、Ubuntu 20.10、Fedora 34、RHEL/Stream 9——都满足RHEL 系经厂商 backport 后 4.18 也可用。应用已通过 OpenTelemetry SDK 上报 Traces不希望出现重复数据。输出哪些信号OBI 会从捕获的流量中提取多个信号族全部默认开启可用--set ebpf.features.keyfalse逐个关闭信号默认作用ebpf.features.httpMetricsonHTTP/gRPC RED 指标——请求速率、延迟直方图、错误计数按服务ebpf.features.spanMetricson基于 Span 属性的指标请求大小、响应大小、按路由/操作拆分的耗时ebpf.features.serviceGraphon服务到服务的边指标调用方 → 被调用方的请求速率 延迟驱动服务拓扑图ebpf.features.hostMetricson每个被插桩进程的 CPU 与内存——省去为基本容量问题单独跑一个 profilerebpf.features.networkMetricsonPod 间 TCP/UDP 流的字节与包计数器带 k8s 元数据可见每个互相通信的 Pod 对包括运行 OBI 无法解析协议的对ebpf.features.networkInterZoneMetricsoff网络指标的跨可用区变体基数翻倍仅在确实使用 zone 调度时开启ebpf.features.tcpStatson节点级 TCP 统计RTT 直方图、失败连接数、重传次数跨服务 Trace 上下文传播默认关闭OBI 还能跨服务边界传播 trace 上下文使 Pod B 侧的 span 与 Pod A 的出口请求链接进同一条 trace——两端应用都无需 SDK 改动。此项默认关闭需通过--set ebpf.contextPropagationtrue显式开启。设置默认说明ebpf.contextPropagationoff在出站流量中注入 W3Ctraceparent使 span 跨服务链接。默认关闭——先阅读下面的警告。无额外内核要求没有任何内核版本会让它失效ebpf.contextPropagationModeheaderstraceparent的注入方式headersHTTP/1.1 请求头影响面最小、tcp通过 Linux Traffic Control 注入 TCP option或all两者。仅在contextPropagation为 true 时读取ebpf.trackRequestHeaderson内核侧请求头追踪使传播在纯 HTTP 服务器非 Go、非 TLS上也能工作仅在contextPropagation为 true 时生效⚠️ 为什么默认关闭。所有传播模式都会改写已在途中的流量纯 HTTP 请求在内核中原地震宽缓冲以塞入额外头部TLS 与裸 TCP 则从 Traffic Control hook 追加 TCP option。如果连接的字节记账没有完全修正流会失去同步——报告的典型症状是经 nginx 等 L7 代理的传输在响应超过约 64KB 时卡在 body 中间而小请求正常因此极像应用故障而非 Agent 故障。Traces、RED 指标与服务拓扑图都不依赖它若要做跨服务串联用 OpenTelemetry SDK 在用户态传播 header不做内核改写是更安全的选择。任何内核版本都不会让该特性“安全失效”。内核 5.17 引入bpf_loop用于网络层头部解析更低版本 OBI 只是回退到有界扫描的程序变体并继续以相同方式改写流量。真正决定是否注入的是CAP_SYS_ADMIN与内核 lockdown 状态——而该 DaemonSet 以特权运行这道门始终是开的tcp/all模式还会额外加载 Traffic Control 程序需要CAP_NET_ADMIN。如果开启传播请假定每个节点上的流量都在被改写。历史上该值曾默认开启true升级时若沿用--reuse-values可能把旧值带过来可用helm get values release -n oneuptime-kubernetes-agent -a | grep -A2 contextPropagation核对实际生效值如为true请显式关闭。日志 ↔ Trace 关联同样默认开启OBI 的日志富化器会拦截被插桩进程的 Pod stdout 写入并做两件事对JSON 格式日志在行内注入trace_id与span_id字段日志中已有值保留。随后 filelog DaemonSet 把这些字段提升到 LogRecord 的原生 trace_id/span_id 槽位因此在 Trace 视图中点击 span 可跳到它的日志点击日志行可跳到父 Trace。对非 JSON 日志原样保留——仍会被采集只是不会自动关联。设置默认说明ebpf.logToTraceCorrelationon启用 OBI 日志富化器与 filelog 管道的 trace_id 提升设为false跳过两者需要注意的事项日志必须是 JSONtrace_id 才能显示。请把 logger 切到 JSON formatter——如structlog、pino、winston、serilog、logback-json、klog 的--logging-formatjson等。stdout 缓冲会破坏关联因为write()系统调用触发在另一条线程上。常见解法Python设置PYTHONUNBUFFERED1非 TTY 下运行时默认块缓冲 stdout。.NET启动时执行Console.SetOut(new StreamWriter(Console.OpenStandardOutput()) { AutoFlush true })。Microsoft.Extensions.Logging 的AddConsole()与 Serilog 的异步 sink 都不行——换成同步控制台 writerSerilog 默认的WriteTo.Console()即可。Greenlet / gevent、Tornado 等自定义异步运行时不在支持范围内。需补充的版本差异项目 Chart README 明确指出ebpf.logToTraceCorrelation在 Chart 中的默认值为falseopt-in。该特性极具侵入性在每个write()上挂 uprobe、进程内改写缓冲区与一类 APM 代理不兼容——LD_PRELOAD 型代理Dynatrace OneAgent、New Relic、AppDynamics、Datadog、Instana会包装 libcwrite()并持有调用方 stdout 缓冲区的指针OBI 日志富化器用 NUL 清零原缓冲区再重发富化行会与 APM 的 write 包装器竞态导致应用进程崩溃.NET 工作负载典型表现为 SIGSEGV / exit 139。启用前请确认 (a) 同 Pod 内没有 LD_PRELOAD 型 APM 代理或已用ebpf.logEnricher.services缩小作用范围(b) 应用向 stdout 输出 JSON。若必须与 APM 共存可将logEnricher.services限定为特定标签如k8s_pod_labels: {apm-agent: none}或特定语言如languages: python,go,nodejs,ruby——注意 OBI 的 log_enricher 只接受正向选择器不支持exclude_services。调优参数设置默认说明ebpf.enabledtrue总开关false时完全跳过 eBPF DaemonSetebpf.image.tagv0.9.0OBI 镜像 tag。OBI 尚未到 1.0升级时请固定到已知良好版本并回归测试ebpf.autoTargetExe*待插桩可执行文件的 glob。缩小范围如*/python,*/java可限定自动插桩ebpf.excludeExePathsshell、kubelet、runc、containerd、otelcol、OBI 自身等逗号分隔的跳过 glob。默认值已排除 shell/coreutils 噪音、集群管道组件、服务网格数据面 sidecarlinkerd2-proxy、envoy 等、CNI 代理、浏览器二进制以及 ClickHouse——后者尤其关键OBI 的 uprobe 会改写其内存文本触发 ClickHouse 启动时自校验失败CORRUPTED_DATA/ Code 246而 OneUptime 自己的遥测存储就是 ClickHouseebpf.logLevelinfodebug、info、warn或error排障时设debugebpf.printTracesfalse除 OTLP 导出外把 span 打印到 OBI 的 stdout——安装时验证是否捕获到流量很有用ebpf.resources.*100m / 256Mirequests、1000m / 1Gilimits高流量集群上调高需要提醒的是实际 Chart 默认值见 values.yaml 的ebpf.resources是100m / 512Mirequests、2000m / 2Gilimits且 OBI 内存随插桩进程数与流量增长——数据库与应用层混布的繁忙节点 1Gi limit 会 OOM 循环短生命周期进程负载如 Playwright/Firefox 探针 Pod会因 uprobe 挂接/解挂让 CPU 打满 1 核甚至拖垮节点容器运行时containerd CRI 调用超时 → Pod 卡在 Init/Terminating因此默认已排除浏览器二进制。若仍 OOM 或 CPU 打满应优先通过autoTargetExe/excludeExePaths缩小范围而非无限抬高资源。检查 OBI 是否运行并看到流量kubectl get pods -n oneuptime-kubernetes-agent -l componentebpf-instrument kubectl logs -n oneuptime-kubernetes-agent -l componentebpf-instrument --tail200持续 CPU 性能剖析默认关闭另一个独立 DaemonSet 运行 OpenTelemetry eBPF Profiler打包为otel/opentelemetry-collector-ebpf-profiler镜像。它按 19Hz 采样各受支持运行时Go、Java、.NET、Python、Ruby、Node.js、PHP、Perl、C/C、Rust的 on-CPU 调用栈并向 OneUptime 发送 OTLP profiles展示在Products → Performance Profiles产品 → 性能剖析中以及从单个 Trace span 链接的火焰图。为什么默认关闭它比 OBI 自动插桩更重每节点 CPU 更多、内存占用更大且并非所有集群都想要常开火焰图。需要更丰富遥测时启用--set profiling.enabledtrue。当 eBPF 自动插桩也开启时ebpf.enabled: true即默认每个 CPU 样本会通过共享的 bpffs map 与 OBI 的 trace 上下文关联——于是火焰图携带 trace_id/span_idOneUptime UI 可以为每个 span 展示专属火焰图。前置要求Linux 内核 5.10比 OBI 需要的 5.8 略新。需要特权 Pod 与 hostPID——与 eBPF 自动插桩 DaemonSet 的限制相同无法运行在 GKE Autopilot、EKS Fargate 或其他锁定环境。调优参数设置默认说明profiling.enabledfalse总开关默认关闭按需开启持续 CPU 火焰图profiling.image.tag0.152.0otel/opentelemetry-collector-ebpf-profiler镜像 tagprofiler 尚未到 1.0请固定到已知良好版本profiling.samplesPerSecond19采样频率Hz。上游默认与常见定时器频率错开以避免意外混叠profiling.offCpuThreshold0(0–1] 时启用 off-CPU 剖析——诊断锁竞争与阻塞 I/O默认关闭因会增加 tracepoint 开销profiling.tracers所有运行时逗号分隔的需加载的语言 tracer 列表profiling.obiProcessContexttrue将样本与 OBI 的 trace 上下文关联实现 trace ↔ profile 链接实现层面的补充见 values.yaml 的profiling段注释profiler 之所以是独立 DaemonSet是因为它直连 OneUptime 导出——集群内负责 k8s 指标/日志/traces 的 Collector 版本otel/opentelemetry-collector-contrib:0.96.0早于 OTLP profiles 信号无法中转。其他数据采集能力Chart 还可以采集以下数据对应 values.yaml 中的各*.enabled开关key.enabled默认作用hostMetricson每节点 OS 指标直接读取/proc与/sys——磁盘 I/O 队列深度、文件系统 inode 占用、NIC 错误计数、paging 统计、load average。运行在日志采集 DaemonSet 内部不增加 Pod。每条system.*序列带k8s.node.name可逐节点分组告警kubeletstats.utilizationMetricson饱和度指标——容器与 Pod 的 CPU/内存按 request/limit 的百分比表示。共 8 条派生指标族驱动“CPU/Memory vs Request”与“vs Limit”监控器。与既有kubeletstatsreceiver 同一次抓取不增加 PodPod 未设 request/limit 时恒为 0kubeletstats.volumeMetricson每 PVC 磁盘用量k8s.volume.available、k8s.volume.capacity驱动“PVC Low Disk Space”监控器。每条 PVC 每 Pod 一条序列——多数集群有界但 stateful 工作负载数千 PVC下较重cadvisoron从每节点 DaemonSet Pod 抓取 kubelet 的/metrics/cadvisor获取kubeletstats不翻译的容器级指标CFS 节流container_cpu_cfs_throttled_seconds_total、container_cpu_cfs_periods_total与 OOM kill 事件container_oom_events_total。receiver 端用 relabel allowlist 丢弃其余指标以控制基数kubeStateMetricsoff从 kube-state-metrics 拉取集群状态指标Pod 阶段Pending / Terminating、容器 waiting 原因CrashLoopBackOff、ImagePullBackOff、资源配额用量。mode: bundled默认为你部署一个小型 KSM Deploymentmode: external通过endpoint抓取既有 KSM。默认关闭因为 bundled 模式给 Chart 增加了 DeploymentauditLogsoff读取宿主的/var/log/kubernetes/audit.log捕获每次 Kubernetes API 请求——谁在几点对哪个资源做了什么。仅限自建集群——托管 K8sEKS、GKE、AKS、DOKS会把审计日志送到云厂商 sinkcsioff自动发现带appcsi-driver或app.kubernetes.io/componentcsi-driver标签的 Pod 并抓取其 Prometheusmetrics端口——卷挂载/卸载延迟、provisioning 失败、IOPScoreDnsoff抓取集群 CoreDNS 服务的:9153/metrics——查询速率、延迟、缓存命中率、错误计数常见的 P99 延迟隐患常用设置总览设置默认说明preset空按standard处理见上文表格oneuptime.url必填你的 OneUptime 实例 URLoneuptime.apiKey必填项目 API 密钥Settings → API KeysclusterName必填本集群唯一名称作为k8s.cluster.name打在每条记录上oneuptime.labels{}可选为 Agent 发出的每条记录自动打项目标签。每个键值对变成oneuptime.label.keyvalue资源属性OneUptime 摄取管道会将其提升为项目标签并附加到主机/服务/遥测记录上标签匹配大小写不敏感UI 里手工创建的标签不会被 Agent 移除namespaceFilters.rules默认从podLogs与ebpfDiscovery排除kube-system针对 podLogs、ebpfDiscovery、metrics、traces 的按作用域 include/exclude 规则。namespace 模式支持*全名匹配如team-*匹配team-a但不匹配my-team-a某个 scope 一旦有 include 规则就只保留匹配的 namespaceexclude 永远最后生效logs.enabledtrue开关日志采集logs.mode由preset推导daemonset、api或disabled显式设置覆盖 presetlogs.api.replicas1日志 tailer Deployment 副本数仅 API 模式filters.logs.minSeverity丢弃低于该严重级别的Pod 日志TRACE/DEBUG/INFO/WARN/ERROR/FATAL空保留全部。只作用于 Pod 日志Kubernetes events 与资源规格不参与过滤它们无严重级别阈值会整条删除。DaemonSet 模式下行无级别标签的 stdout 按 INFO、stderr 按 ERROR 回退API 模式无法区分 stdout/stderr无法识别的行一律保留filters.metrics.include/exclude[]/[]指标名 allowlist / denylist跨全部 receiver。include 非空时只发送匹配指标exclude 叠加在 include 之上、永远优先。matchType可为strict精确名或regexpRE2非锚定、无 lookahead非法正则会让 Collector 启动失败CrashLoopBackOff连日志一起停sampling.traces.percentage100保留的 trace 百分比0–100。基于 trace ID 的哈希而非掷硬币因此整条 trace 同留同弃绝不产生碎片。不影响 eBPF RED 指标它们走 metrics 管道rate/error/latency 依旧精确。但 span 派生监控Span Count、Exception Count会按比例缩小需按同系数重调阈值。0是真实速率而非关闭开关——彻底不想要 trace 应设ebpf.enabledfalse0.5等小数需用--set-json或 values 文件--set会解析为字符串且最小有效值约0.01低于此值量化到 0 桶等同于全丢。日志不做采样无 trace ID 的记录会哈希到同一桶导致全留或全删的数据丢失陷阱sampling.traces.hashSeed22trace-ID 哈希种子。需要对齐取舍的 Collector 必须共享相同 seed 与 percentage——默认全一致多集群 trace 天然完整ebpf.enabledtrue通过 OBI 自动捕获每个 Pod 的 HTTP/gRPC traces见上文profiling.enabledfalse通过 OpenTelemetry eBPF Profiler 做持续 CPU 火焰图见上文hostMetrics.enabledtrue每节点 OS 指标kubeletstats.utilizationMetrics.enabledtrue容器与 Pod 的 CPU/内存饱和度占 request/limit 百分比无额外抓取kubeletstats.volumeMetrics.enabledtrue每 PVC 磁盘用量k8s.volume.available、k8s.volume.capacitycadvisor.enabledtrue抓取本节点 kubelet/metrics/cadvisor的 CFS 节流 OOM kill 计数器allowlist 只留 3 条指标kubeStateMetrics.enabledfalse从 kube-state-metrics 拉取 Pod 阶段、容器 waiting 原因CrashLoopBackOff / ImagePullBackOff、ResourceQuota 用量bundled vs external 见kubeStateMetrics.modeauditLogs.enabledfalseKubernetes 审计日志仅自建集群csi.enabledfalseCSI driver Prometheus 指标coreDns.enabledfalseCoreDNS Prometheus 指标controlPlane.enabledfalse抓取 etcd / api-server / scheduler / controller-manager仅自建集群——托管集群EKS/GKE/AKS通常不暴露这些 endpointcost.enabledfalseKubernetes 成本可观测性一条命令完成安装捆绑 OpenCost 引擎与一个专用迷你 Prometheus轮询每工作负载成本分配并抓取成本指标。云端清单价无需凭据已自建 Kubecost/OpenCost 时可设cost.engine.url直接读取resourceSpecs.enabledtrue拉取完整 K8s 对象规格标签、注解、环境变量、状态供 Dashboard 展示完整参数清单以 Chart 的 values.yaml 为准1200 余行注释即文档覆盖 service mesh 抓取、控制平面 endpoint、资源规格采集间隔、调试 sidecar 等。升级helm repo update helm upgrade oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --reuse-values--reuse-values会保留你现有的配置新增的--set覆盖叠加在其上。重要--reuse-values不会合并 Chart 的新默认值。Helm 会逐字复用你之前渲染过的值——因此新 Chart 版本中新增的任何顶层字段如profiling.*、ebpf.features.*在你的既有 release 上会保持未设置模板会渲染成“已禁用”的状态。Helm 3.14——改用--reset-then-reuse-values。它会为未被你覆盖的键重新读取 Chart 默认值helm upgrade oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --reset-then-reuse-valuesHelm 3.13 或更早——放弃--reuse-values显式带上你原来的--set标志或-f values.yaml。新 Chart 默认值会对所有未覆盖项生效。如果升级后新功能的 Pod如kubernetes-agent-profiling-*没有出现几乎可以断定就是这个原因。helm get values release能显示 Helm 实际持有的值——输出中缺失的字段意味着默认值没有被合并进来。卸载helm uninstall oneuptime-agent --namespace oneuptime-kubernetes-agent kubectl delete namespace oneuptime-kubernetes-agent故障排查安装报错 “hostPath volumes are not allowed”你的集群屏蔽了 hostPath。切换为 API 模式 presethelm upgrade oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --reuse-values \ --set presetgke-autopilot # 或 eks-fargateOneUptime 里看不到日志检查 Agent Podkubectl get pods -n oneuptime-kubernetes-agent kubectl logs -n oneuptime-kubernetes-agent -l app.kubernetes.io/part-ofoneuptime --tail200API 模式下日志 tailer Pod 在 13133 端口暴露/healthz——用kubectl port-forward访问可看到导出状态的快照该健康检查同时充当 liveness/readiness 探针见 deployment-logs-api.yaml。eBPF DaemonSet PodCrashLoopBackOff或启动失败查看 OBI Pod 日志kubectl logs -n oneuptime-kubernetes-agent -l componentebpf-instrument --tail200常见原因内核太旧或缺少 BTF。OBI 需要 Linux 5.8 且带 BTF。在节点上用uname -r确认。无法升级就关闭 eBPF--set ebpf.enabledfalse。特权 Pod 被屏蔽。部分集群即使在 Autopilot/Fargate 之外也拒绝特权 Pod。关闭 eBPF 即可。Dashboard 里没有 traces 但 OBI 在跑。设--set ebpf.printTracestrue并检查 OBI 的 stdout——若能看到 span问题在 OTLP 投递检查OTEL_EXPORTER_OTLP_ENDPOINT以及你的 OneUptime URL/API 密钥若看不到 span则 OBI 监控的流量可能被其无法识别的 TLS 库如静态链接的 TLS 实现完全加密。集群 Pod 太多单日志 tailer 副本扛不住仅 API 模式按 namespace 分片横向扩容每组 namespace 部署一次helm install oneuptime-agent-ns-a oneuptime/kubernetes-agent \ --set presetgke-autopilot \ --set-json namespaceFilters.rules[{action:include,namespaces:[app-a,app-b],scopes:[podLogs]}] \ ...也可以抬高logs.api.replicas——但注意每个副本都会处理所有允许的 namespace要做去重仍需要 namespace 分片。集群显示“Disconnected”且无数据——运行诊断脚本这通常是一个问题而非两个遥测未被接受于是集群永远连不上且零数据。最常见的根因尤其是重装之后是错误或已吊销的摄取密钥——它很难发现因为 OTLP endpoint 即使对坏 token 也回200为避免配置错误的 collector 对服务器发起重试风暴。因此 collector 不记录任何错误而每个字节都被丢弃。Chart 自带的诊断脚本troubleshoot.sh会检查 Pod 健康、解码并校验密钥、测试集群出口并向 OneUptime 询问 token 是否真的被接受——最后打印唯一的根因结论curl -fsSL https://raw.githubusercontent.com/OneUptime/oneuptime/master/HelmChart/Public/kubernetes-agent/troubleshoot.sh \ | bash -s -- -n oneuptime-agent它只读集群状态并跑几个探测不改动任何东西。手工校验密钥200 有效401 未知/已吊销curl -i -H x-oneuptime-token: YOUR_API_KEY $ONEUPTIME_URL/otlp/v1/validate无法kubectl exec进入 Agent Pod这是预期行为而非 bugmetrics-collector Deployment 与日志采集 DaemonSet 运行的是上游 OpenTelemetry Collector 镜像它是distroless基于FROM scratch构建只含 collector 二进制与 CA 证书——没有/bin/sh、没有bash、没有curl。需要 shell 时方式 A推荐无需改动安装用临时调试容器Kubernetes ≥ 1.23例如kubectl debug -it agent-pod --imagenicolaka/netshoot --targetotel-collector -- bash其与 collector 共享网络命名空间可测试完全一致的出口路径。方式 B内置调试 sidecar--set debug.enabledtrue会把nicolaka/netshootsidecar 注入 metrics Deployment 与日志 DaemonSet并开启shareProcessNamespace。用完记得关掉--set debug.enabledfalse因为它给每个 Agent Pod 增加了常驻容器额外资源 攻击面。API 模式的日志 tailer 运行 Node.js 镜像、自带 bash可直接 exec。源码级参考Chart 配置全量定义HelmChart/Public/kubernetes-agent/values.yaml1200 行每个参数均有注释与取舍说明Chart 说明与资源调优建议HelmChart/Public/kubernetes-agent/README.md含按集群规模的 recommended sizing 与各组件默认资源表节点日志/主机指标 DaemonSettemplates/daemonset.yamleBPF 自动插桩 DaemonSettemplates/daemonset-ebpf.yamlAPI 模式日志 tailer Deploymenttemplates/deployment-logs-api.yaml日志富化选择器 ConfigMaptemplates/configmap-ebpf.yaml诊断脚本troubleshoot.shAPI 模式日志 tailer 的实现位于仓库的 KubernetesLogTailer 目录含批量导出、重试、namespace 过滤等逻辑如果你的集群规模较大Chart README 还提供了 small≤10 节点、medium10–50 节点默认值即为此档设计、large50–200 节点与 extra-large200 节点四档资源模板可直接以-f应用并在安装后通过kubectl top pod -n oneuptime-kubernetes-agent观察实际用量、按约 1.5 倍峰值设置 limit。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime Kubernetes Agent 安装与配置全指南：从 Helm 快速部署到 eBPF 自动埋点与持续 CPU 性能剖析
OneUptime Kubernetes Agent 安装与配置全指南从 Helm 快速部署到 eBPF 自动埋点与持续 CPU 性能剖析【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime Kubernetes Agent 是 OneUptime 平台在 Kubernetes 集群内的数据采集组件负责收集集群指标、事件、Pod 日志、应用级 TracesHTTP/gRPC基于 eBPF以及OS 级别节点指标并通过 OpenTelemetry 协议OTLP上报到 OneUptime。本文以项目文档 kubernetes-agent.md 为主体结合 Helm Chart 源码values.yaml 与各模板文件逐项讲解安装、预设选择、两种日志采集模式、eBPF 自动插桩的调优与取舍以及升级、卸载与故障排查的完整操作。读完本文你将能独立完成 Agent 在任意主流 Kubernetes 发行版上的安装、按集群特性选择正确 preset、精细控制日志/追踪/剖析功能的开销并能在出问题时快速定位根因。快速开始一条命令接入集群Agent 以 Helm Chart 形式分发官方 Chart 仓库地址为oneuptime/kubernetes-agent当前 Chart 版本见 Chart.yaml。最小安装只需三步helm repo add oneuptime https://helm-chart.oneuptime.com helm repo update helm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameA_UNIQUE_NAME_FOR_THIS_CLUSTER安装完成后你的集群会在几分钟内出现在 OneUptime 界面中。三个必填参数的含义参数说明oneuptime.url你的 OneUptime 实例地址如https://oneuptime.comoneuptime.apiKey项目 API 密钥在 OneUptime 的Settings → API Keys设置 → API 密钥中创建clusterName该集群的唯一名称会被打标为每条记录的k8s.cluster.name属性从 values.yaml 的注释可以看到clusterName并非普通标签OneUptime 会把k8s.cluster.name折叠进它派生的每个 Kubernetes 实体的身份中它是区分本集群worker-1节点与default命名空间同其他集群的唯一依据。两个未设置clusterName的集群会被静默合并成同一份资产因此渲染时 Chart 会强制校验该值缺失则拒绝安装。为你的集群选择正确的 preset不同 Kubernetes 发行版对宿主访问的限制差异巨大——最关键的差异是工作负载能否挂载hostPath卷。为避免用户逐一阅读安全文档Chart 只暴露一个顶层开关preset它会自动选择兼容的默认值包括日志采集模式与安全上下文。Preset适用场景日志采集方式备注standard默认自建集群、EKS on EC2、GKE Standard、AKS、minikube、kind、k3s通过 hostPath 读取/var/log/pods的 DaemonSet开销最低这些平台上 hostPath 可用gke-autopilotGKE Autopilot基于 Kubernetes API tail 的 DeploymentAutopilot 屏蔽了 hostPath会套用一份足以通过 Autopilot Pod Security Standards 的加固安全上下文eks-fargateEKS Fargate基于 Kubernetes API tail 的 Deployment与gke-autopilot相同Fargate 同时屏蔽 hostPath 与 DaemonSet不确定时保持preset不设置即可会得到standard默认值。如果安装时被一条提及hostPath的 Pod Security 错误拒绝切换到gke-autopilotEKS Fargate 上用eks-fargate重新安装即可。三种场景的安装示例GKE Standard、EKS on EC2、自建集群或 AKShelm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprodGKE Autopilothelm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprod-gke-autopilot \ --set presetgke-autopilotEKS Fargatehelm install oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent --create-namespace \ --set oneuptime.urlhttps://oneuptime.com \ --set oneuptime.apiKeyYOUR_API_KEY \ --set clusterNameprod-eks-fargate \ --set preseteks-fargate两种日志采集模式的区别preset在底层只是设置了logs.mode的值——你也可以直接设置logs.mode来覆盖 preset 的默认值显式值永远优先见 values.yaml 中的logs.mode注释。DaemonSet 模式logs.mode: daemonset每节点运行一个 OpenTelemetry Collector Pod通过 hostPath 卷读取/var/log/pods/下的日志文件并经 OTLP 转发。对应模板 daemonset.yaml 中可以看到该 DaemonSet 以只读方式挂载了宿主的/var/log/pods。优点开销最低随节点数线性扩展完全不增加 Kubernetes API Server 的负载且能正确处理日志轮转。缺点需要 hostPath 和 DaemonSet 调度能力——这两者在 GKE Autopilot 与 EKS Fargate 上均不可用。API 模式logs.mode: api一个单副本 Deployment使用oneuptime/kubernetes-log-tailer镜像通过 Kubernetes API 流式拉取容器日志——与kubectl logs -f使用同一 endpoint。无需 hostPath、无宿主访问、无 DaemonSet。优点可在 GKE Autopilot、EKS Fargate 以及任何屏蔽 hostPath 或强制restrictedPod Security Standard 的集群上运行。缺点每个容器流都是与 kube-apiserver 的一条长连接单副本通常只能承载数千个容器。超大集群需要按 namespace 分片部署多份 release使用namespaceFilters.rules中podLogsscope 的 include 规则。从 deployment-logs-api.yaml 可以看到 API 模式的加固细节容器以非 rootrunAsUser: 1000运行、allowPrivilegeEscalation: false、只读根文件系统、丢弃全部 capabilities并通过livenessProbe/readinessProbe暴露/healthz端口 13133。这正是它能通过 Autopilot 这类严格平台安全审查的原因。该如何选择如果 hostPath 可用用 DaemonSet其余场景用 API 模式。preset会替你选好。也可以完全关闭日志采集--set logs.enabledfalse改用 OpenTelemetry SDK 直接从应用发送日志。此时节点 Collector 仍会继续运行并采集 kubelet / cAdvisor / 主机指标只是停止读取 Pod 日志values.yaml 的logs.enabled注释对此有明确说明。基于 eBPF 的应用 Traces 与 HTTP 请求指标默认开启Chart 会在每个节点上部署一个运行 OpenTelemetry eBPF InstrumentationOBI。OBI 把 eBPF 程序加载进 Linux 内核监控 socket 层流量从而重建每个 Pod 的 HTTP/HTTPS、gRPC 与 SQL/Redis 调用——不需要改代码、不需要 SDK、不需要 sidecar。捕获的流量以 OTLP Traces 与请求/延迟指标的形式直接上报 OneUptime。安装后约一两分钟内你的服务就会出现在Products → Traces产品 → 追踪与服务拓扑图中且每条记录带有k8s.cluster.nameclusterName可按集群过滤。模板中值得注意的实现细节OBI 以privileged: true运行并设置hostPID: true因为它需要特权来加载 eBPF 程序、查看节点上所有进程挂载了bpffs/sys/fs/bpf用于固定 eBPF map日志富化、profile 关联等功能依赖它挂载了tracefs与debugfs供stats特性挂接sock/inet_sock_set_state等内核 tracepoint以产出 TCP RTT、连接失败与重传指标OTEL_EBPF_METRICS_FEATURES由ebpf.features.*渲染而来环境变量与 YAML 配置合并时以环境变量优先因此 values.yaml 中的开关保持权威。何时应该关闭它eBPF默认开启。以下情况应设置--set ebpf.enabledfalse安装在GKE Autopilot或EKS Fargate上。这些平台屏蔽特权 Pod而 OBI 需要特权态才能加载 eBPF 程序。节点内核低于Linux 5.8且无 BTF backport现代发行版——Debian 11、Ubuntu 20.10、Fedora 34、RHEL/Stream 9——都满足RHEL 系经厂商 backport 后 4.18 也可用。应用已通过 OpenTelemetry SDK 上报 Traces不希望出现重复数据。输出哪些信号OBI 会从捕获的流量中提取多个信号族全部默认开启可用--set ebpf.features.keyfalse逐个关闭信号默认作用ebpf.features.httpMetricsonHTTP/gRPC RED 指标——请求速率、延迟直方图、错误计数按服务ebpf.features.spanMetricson基于 Span 属性的指标请求大小、响应大小、按路由/操作拆分的耗时ebpf.features.serviceGraphon服务到服务的边指标调用方 → 被调用方的请求速率 延迟驱动服务拓扑图ebpf.features.hostMetricson每个被插桩进程的 CPU 与内存——省去为基本容量问题单独跑一个 profilerebpf.features.networkMetricsonPod 间 TCP/UDP 流的字节与包计数器带 k8s 元数据可见每个互相通信的 Pod 对包括运行 OBI 无法解析协议的对ebpf.features.networkInterZoneMetricsoff网络指标的跨可用区变体基数翻倍仅在确实使用 zone 调度时开启ebpf.features.tcpStatson节点级 TCP 统计RTT 直方图、失败连接数、重传次数跨服务 Trace 上下文传播默认关闭OBI 还能跨服务边界传播 trace 上下文使 Pod B 侧的 span 与 Pod A 的出口请求链接进同一条 trace——两端应用都无需 SDK 改动。此项默认关闭需通过--set ebpf.contextPropagationtrue显式开启。设置默认说明ebpf.contextPropagationoff在出站流量中注入 W3Ctraceparent使 span 跨服务链接。默认关闭——先阅读下面的警告。无额外内核要求没有任何内核版本会让它失效ebpf.contextPropagationModeheaderstraceparent的注入方式headersHTTP/1.1 请求头影响面最小、tcp通过 Linux Traffic Control 注入 TCP option或all两者。仅在contextPropagation为 true 时读取ebpf.trackRequestHeaderson内核侧请求头追踪使传播在纯 HTTP 服务器非 Go、非 TLS上也能工作仅在contextPropagation为 true 时生效⚠️ 为什么默认关闭。所有传播模式都会改写已在途中的流量纯 HTTP 请求在内核中原地震宽缓冲以塞入额外头部TLS 与裸 TCP 则从 Traffic Control hook 追加 TCP option。如果连接的字节记账没有完全修正流会失去同步——报告的典型症状是经 nginx 等 L7 代理的传输在响应超过约 64KB 时卡在 body 中间而小请求正常因此极像应用故障而非 Agent 故障。Traces、RED 指标与服务拓扑图都不依赖它若要做跨服务串联用 OpenTelemetry SDK 在用户态传播 header不做内核改写是更安全的选择。任何内核版本都不会让该特性“安全失效”。内核 5.17 引入bpf_loop用于网络层头部解析更低版本 OBI 只是回退到有界扫描的程序变体并继续以相同方式改写流量。真正决定是否注入的是CAP_SYS_ADMIN与内核 lockdown 状态——而该 DaemonSet 以特权运行这道门始终是开的tcp/all模式还会额外加载 Traffic Control 程序需要CAP_NET_ADMIN。如果开启传播请假定每个节点上的流量都在被改写。历史上该值曾默认开启true升级时若沿用--reuse-values可能把旧值带过来可用helm get values release -n oneuptime-kubernetes-agent -a | grep -A2 contextPropagation核对实际生效值如为true请显式关闭。日志 ↔ Trace 关联同样默认开启OBI 的日志富化器会拦截被插桩进程的 Pod stdout 写入并做两件事对JSON 格式日志在行内注入trace_id与span_id字段日志中已有值保留。随后 filelog DaemonSet 把这些字段提升到 LogRecord 的原生 trace_id/span_id 槽位因此在 Trace 视图中点击 span 可跳到它的日志点击日志行可跳到父 Trace。对非 JSON 日志原样保留——仍会被采集只是不会自动关联。设置默认说明ebpf.logToTraceCorrelationon启用 OBI 日志富化器与 filelog 管道的 trace_id 提升设为false跳过两者需要注意的事项日志必须是 JSONtrace_id 才能显示。请把 logger 切到 JSON formatter——如structlog、pino、winston、serilog、logback-json、klog 的--logging-formatjson等。stdout 缓冲会破坏关联因为write()系统调用触发在另一条线程上。常见解法Python设置PYTHONUNBUFFERED1非 TTY 下运行时默认块缓冲 stdout。.NET启动时执行Console.SetOut(new StreamWriter(Console.OpenStandardOutput()) { AutoFlush true })。Microsoft.Extensions.Logging 的AddConsole()与 Serilog 的异步 sink 都不行——换成同步控制台 writerSerilog 默认的WriteTo.Console()即可。Greenlet / gevent、Tornado 等自定义异步运行时不在支持范围内。需补充的版本差异项目 Chart README 明确指出ebpf.logToTraceCorrelation在 Chart 中的默认值为falseopt-in。该特性极具侵入性在每个write()上挂 uprobe、进程内改写缓冲区与一类 APM 代理不兼容——LD_PRELOAD 型代理Dynatrace OneAgent、New Relic、AppDynamics、Datadog、Instana会包装 libcwrite()并持有调用方 stdout 缓冲区的指针OBI 日志富化器用 NUL 清零原缓冲区再重发富化行会与 APM 的 write 包装器竞态导致应用进程崩溃.NET 工作负载典型表现为 SIGSEGV / exit 139。启用前请确认 (a) 同 Pod 内没有 LD_PRELOAD 型 APM 代理或已用ebpf.logEnricher.services缩小作用范围(b) 应用向 stdout 输出 JSON。若必须与 APM 共存可将logEnricher.services限定为特定标签如k8s_pod_labels: {apm-agent: none}或特定语言如languages: python,go,nodejs,ruby——注意 OBI 的 log_enricher 只接受正向选择器不支持exclude_services。调优参数设置默认说明ebpf.enabledtrue总开关false时完全跳过 eBPF DaemonSetebpf.image.tagv0.9.0OBI 镜像 tag。OBI 尚未到 1.0升级时请固定到已知良好版本并回归测试ebpf.autoTargetExe*待插桩可执行文件的 glob。缩小范围如*/python,*/java可限定自动插桩ebpf.excludeExePathsshell、kubelet、runc、containerd、otelcol、OBI 自身等逗号分隔的跳过 glob。默认值已排除 shell/coreutils 噪音、集群管道组件、服务网格数据面 sidecarlinkerd2-proxy、envoy 等、CNI 代理、浏览器二进制以及 ClickHouse——后者尤其关键OBI 的 uprobe 会改写其内存文本触发 ClickHouse 启动时自校验失败CORRUPTED_DATA/ Code 246而 OneUptime 自己的遥测存储就是 ClickHouseebpf.logLevelinfodebug、info、warn或error排障时设debugebpf.printTracesfalse除 OTLP 导出外把 span 打印到 OBI 的 stdout——安装时验证是否捕获到流量很有用ebpf.resources.*100m / 256Mirequests、1000m / 1Gilimits高流量集群上调高需要提醒的是实际 Chart 默认值见 values.yaml 的ebpf.resources是100m / 512Mirequests、2000m / 2Gilimits且 OBI 内存随插桩进程数与流量增长——数据库与应用层混布的繁忙节点 1Gi limit 会 OOM 循环短生命周期进程负载如 Playwright/Firefox 探针 Pod会因 uprobe 挂接/解挂让 CPU 打满 1 核甚至拖垮节点容器运行时containerd CRI 调用超时 → Pod 卡在 Init/Terminating因此默认已排除浏览器二进制。若仍 OOM 或 CPU 打满应优先通过autoTargetExe/excludeExePaths缩小范围而非无限抬高资源。检查 OBI 是否运行并看到流量kubectl get pods -n oneuptime-kubernetes-agent -l componentebpf-instrument kubectl logs -n oneuptime-kubernetes-agent -l componentebpf-instrument --tail200持续 CPU 性能剖析默认关闭另一个独立 DaemonSet 运行 OpenTelemetry eBPF Profiler打包为otel/opentelemetry-collector-ebpf-profiler镜像。它按 19Hz 采样各受支持运行时Go、Java、.NET、Python、Ruby、Node.js、PHP、Perl、C/C、Rust的 on-CPU 调用栈并向 OneUptime 发送 OTLP profiles展示在Products → Performance Profiles产品 → 性能剖析中以及从单个 Trace span 链接的火焰图。为什么默认关闭它比 OBI 自动插桩更重每节点 CPU 更多、内存占用更大且并非所有集群都想要常开火焰图。需要更丰富遥测时启用--set profiling.enabledtrue。当 eBPF 自动插桩也开启时ebpf.enabled: true即默认每个 CPU 样本会通过共享的 bpffs map 与 OBI 的 trace 上下文关联——于是火焰图携带 trace_id/span_idOneUptime UI 可以为每个 span 展示专属火焰图。前置要求Linux 内核 5.10比 OBI 需要的 5.8 略新。需要特权 Pod 与 hostPID——与 eBPF 自动插桩 DaemonSet 的限制相同无法运行在 GKE Autopilot、EKS Fargate 或其他锁定环境。调优参数设置默认说明profiling.enabledfalse总开关默认关闭按需开启持续 CPU 火焰图profiling.image.tag0.152.0otel/opentelemetry-collector-ebpf-profiler镜像 tagprofiler 尚未到 1.0请固定到已知良好版本profiling.samplesPerSecond19采样频率Hz。上游默认与常见定时器频率错开以避免意外混叠profiling.offCpuThreshold0(0–1] 时启用 off-CPU 剖析——诊断锁竞争与阻塞 I/O默认关闭因会增加 tracepoint 开销profiling.tracers所有运行时逗号分隔的需加载的语言 tracer 列表profiling.obiProcessContexttrue将样本与 OBI 的 trace 上下文关联实现 trace ↔ profile 链接实现层面的补充见 values.yaml 的profiling段注释profiler 之所以是独立 DaemonSet是因为它直连 OneUptime 导出——集群内负责 k8s 指标/日志/traces 的 Collector 版本otel/opentelemetry-collector-contrib:0.96.0早于 OTLP profiles 信号无法中转。其他数据采集能力Chart 还可以采集以下数据对应 values.yaml 中的各*.enabled开关key.enabled默认作用hostMetricson每节点 OS 指标直接读取/proc与/sys——磁盘 I/O 队列深度、文件系统 inode 占用、NIC 错误计数、paging 统计、load average。运行在日志采集 DaemonSet 内部不增加 Pod。每条system.*序列带k8s.node.name可逐节点分组告警kubeletstats.utilizationMetricson饱和度指标——容器与 Pod 的 CPU/内存按 request/limit 的百分比表示。共 8 条派生指标族驱动“CPU/Memory vs Request”与“vs Limit”监控器。与既有kubeletstatsreceiver 同一次抓取不增加 PodPod 未设 request/limit 时恒为 0kubeletstats.volumeMetricson每 PVC 磁盘用量k8s.volume.available、k8s.volume.capacity驱动“PVC Low Disk Space”监控器。每条 PVC 每 Pod 一条序列——多数集群有界但 stateful 工作负载数千 PVC下较重cadvisoron从每节点 DaemonSet Pod 抓取 kubelet 的/metrics/cadvisor获取kubeletstats不翻译的容器级指标CFS 节流container_cpu_cfs_throttled_seconds_total、container_cpu_cfs_periods_total与 OOM kill 事件container_oom_events_total。receiver 端用 relabel allowlist 丢弃其余指标以控制基数kubeStateMetricsoff从 kube-state-metrics 拉取集群状态指标Pod 阶段Pending / Terminating、容器 waiting 原因CrashLoopBackOff、ImagePullBackOff、资源配额用量。mode: bundled默认为你部署一个小型 KSM Deploymentmode: external通过endpoint抓取既有 KSM。默认关闭因为 bundled 模式给 Chart 增加了 DeploymentauditLogsoff读取宿主的/var/log/kubernetes/audit.log捕获每次 Kubernetes API 请求——谁在几点对哪个资源做了什么。仅限自建集群——托管 K8sEKS、GKE、AKS、DOKS会把审计日志送到云厂商 sinkcsioff自动发现带appcsi-driver或app.kubernetes.io/componentcsi-driver标签的 Pod 并抓取其 Prometheusmetrics端口——卷挂载/卸载延迟、provisioning 失败、IOPScoreDnsoff抓取集群 CoreDNS 服务的:9153/metrics——查询速率、延迟、缓存命中率、错误计数常见的 P99 延迟隐患常用设置总览设置默认说明preset空按standard处理见上文表格oneuptime.url必填你的 OneUptime 实例 URLoneuptime.apiKey必填项目 API 密钥Settings → API KeysclusterName必填本集群唯一名称作为k8s.cluster.name打在每条记录上oneuptime.labels{}可选为 Agent 发出的每条记录自动打项目标签。每个键值对变成oneuptime.label.keyvalue资源属性OneUptime 摄取管道会将其提升为项目标签并附加到主机/服务/遥测记录上标签匹配大小写不敏感UI 里手工创建的标签不会被 Agent 移除namespaceFilters.rules默认从podLogs与ebpfDiscovery排除kube-system针对 podLogs、ebpfDiscovery、metrics、traces 的按作用域 include/exclude 规则。namespace 模式支持*全名匹配如team-*匹配team-a但不匹配my-team-a某个 scope 一旦有 include 规则就只保留匹配的 namespaceexclude 永远最后生效logs.enabledtrue开关日志采集logs.mode由preset推导daemonset、api或disabled显式设置覆盖 presetlogs.api.replicas1日志 tailer Deployment 副本数仅 API 模式filters.logs.minSeverity丢弃低于该严重级别的Pod 日志TRACE/DEBUG/INFO/WARN/ERROR/FATAL空保留全部。只作用于 Pod 日志Kubernetes events 与资源规格不参与过滤它们无严重级别阈值会整条删除。DaemonSet 模式下行无级别标签的 stdout 按 INFO、stderr 按 ERROR 回退API 模式无法区分 stdout/stderr无法识别的行一律保留filters.metrics.include/exclude[]/[]指标名 allowlist / denylist跨全部 receiver。include 非空时只发送匹配指标exclude 叠加在 include 之上、永远优先。matchType可为strict精确名或regexpRE2非锚定、无 lookahead非法正则会让 Collector 启动失败CrashLoopBackOff连日志一起停sampling.traces.percentage100保留的 trace 百分比0–100。基于 trace ID 的哈希而非掷硬币因此整条 trace 同留同弃绝不产生碎片。不影响 eBPF RED 指标它们走 metrics 管道rate/error/latency 依旧精确。但 span 派生监控Span Count、Exception Count会按比例缩小需按同系数重调阈值。0是真实速率而非关闭开关——彻底不想要 trace 应设ebpf.enabledfalse0.5等小数需用--set-json或 values 文件--set会解析为字符串且最小有效值约0.01低于此值量化到 0 桶等同于全丢。日志不做采样无 trace ID 的记录会哈希到同一桶导致全留或全删的数据丢失陷阱sampling.traces.hashSeed22trace-ID 哈希种子。需要对齐取舍的 Collector 必须共享相同 seed 与 percentage——默认全一致多集群 trace 天然完整ebpf.enabledtrue通过 OBI 自动捕获每个 Pod 的 HTTP/gRPC traces见上文profiling.enabledfalse通过 OpenTelemetry eBPF Profiler 做持续 CPU 火焰图见上文hostMetrics.enabledtrue每节点 OS 指标kubeletstats.utilizationMetrics.enabledtrue容器与 Pod 的 CPU/内存饱和度占 request/limit 百分比无额外抓取kubeletstats.volumeMetrics.enabledtrue每 PVC 磁盘用量k8s.volume.available、k8s.volume.capacitycadvisor.enabledtrue抓取本节点 kubelet/metrics/cadvisor的 CFS 节流 OOM kill 计数器allowlist 只留 3 条指标kubeStateMetrics.enabledfalse从 kube-state-metrics 拉取 Pod 阶段、容器 waiting 原因CrashLoopBackOff / ImagePullBackOff、ResourceQuota 用量bundled vs external 见kubeStateMetrics.modeauditLogs.enabledfalseKubernetes 审计日志仅自建集群csi.enabledfalseCSI driver Prometheus 指标coreDns.enabledfalseCoreDNS Prometheus 指标controlPlane.enabledfalse抓取 etcd / api-server / scheduler / controller-manager仅自建集群——托管集群EKS/GKE/AKS通常不暴露这些 endpointcost.enabledfalseKubernetes 成本可观测性一条命令完成安装捆绑 OpenCost 引擎与一个专用迷你 Prometheus轮询每工作负载成本分配并抓取成本指标。云端清单价无需凭据已自建 Kubecost/OpenCost 时可设cost.engine.url直接读取resourceSpecs.enabledtrue拉取完整 K8s 对象规格标签、注解、环境变量、状态供 Dashboard 展示完整参数清单以 Chart 的 values.yaml 为准1200 余行注释即文档覆盖 service mesh 抓取、控制平面 endpoint、资源规格采集间隔、调试 sidecar 等。升级helm repo update helm upgrade oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --reuse-values--reuse-values会保留你现有的配置新增的--set覆盖叠加在其上。重要--reuse-values不会合并 Chart 的新默认值。Helm 会逐字复用你之前渲染过的值——因此新 Chart 版本中新增的任何顶层字段如profiling.*、ebpf.features.*在你的既有 release 上会保持未设置模板会渲染成“已禁用”的状态。Helm 3.14——改用--reset-then-reuse-values。它会为未被你覆盖的键重新读取 Chart 默认值helm upgrade oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --reset-then-reuse-valuesHelm 3.13 或更早——放弃--reuse-values显式带上你原来的--set标志或-f values.yaml。新 Chart 默认值会对所有未覆盖项生效。如果升级后新功能的 Pod如kubernetes-agent-profiling-*没有出现几乎可以断定就是这个原因。helm get values release能显示 Helm 实际持有的值——输出中缺失的字段意味着默认值没有被合并进来。卸载helm uninstall oneuptime-agent --namespace oneuptime-kubernetes-agent kubectl delete namespace oneuptime-kubernetes-agent故障排查安装报错 “hostPath volumes are not allowed”你的集群屏蔽了 hostPath。切换为 API 模式 presethelm upgrade oneuptime-agent oneuptime/kubernetes-agent \ --namespace oneuptime-kubernetes-agent \ --reuse-values \ --set presetgke-autopilot # 或 eks-fargateOneUptime 里看不到日志检查 Agent Podkubectl get pods -n oneuptime-kubernetes-agent kubectl logs -n oneuptime-kubernetes-agent -l app.kubernetes.io/part-ofoneuptime --tail200API 模式下日志 tailer Pod 在 13133 端口暴露/healthz——用kubectl port-forward访问可看到导出状态的快照该健康检查同时充当 liveness/readiness 探针见 deployment-logs-api.yaml。eBPF DaemonSet PodCrashLoopBackOff或启动失败查看 OBI Pod 日志kubectl logs -n oneuptime-kubernetes-agent -l componentebpf-instrument --tail200常见原因内核太旧或缺少 BTF。OBI 需要 Linux 5.8 且带 BTF。在节点上用uname -r确认。无法升级就关闭 eBPF--set ebpf.enabledfalse。特权 Pod 被屏蔽。部分集群即使在 Autopilot/Fargate 之外也拒绝特权 Pod。关闭 eBPF 即可。Dashboard 里没有 traces 但 OBI 在跑。设--set ebpf.printTracestrue并检查 OBI 的 stdout——若能看到 span问题在 OTLP 投递检查OTEL_EXPORTER_OTLP_ENDPOINT以及你的 OneUptime URL/API 密钥若看不到 span则 OBI 监控的流量可能被其无法识别的 TLS 库如静态链接的 TLS 实现完全加密。集群 Pod 太多单日志 tailer 副本扛不住仅 API 模式按 namespace 分片横向扩容每组 namespace 部署一次helm install oneuptime-agent-ns-a oneuptime/kubernetes-agent \ --set presetgke-autopilot \ --set-json namespaceFilters.rules[{action:include,namespaces:[app-a,app-b],scopes:[podLogs]}] \ ...也可以抬高logs.api.replicas——但注意每个副本都会处理所有允许的 namespace要做去重仍需要 namespace 分片。集群显示“Disconnected”且无数据——运行诊断脚本这通常是一个问题而非两个遥测未被接受于是集群永远连不上且零数据。最常见的根因尤其是重装之后是错误或已吊销的摄取密钥——它很难发现因为 OTLP endpoint 即使对坏 token 也回200为避免配置错误的 collector 对服务器发起重试风暴。因此 collector 不记录任何错误而每个字节都被丢弃。Chart 自带的诊断脚本troubleshoot.sh会检查 Pod 健康、解码并校验密钥、测试集群出口并向 OneUptime 询问 token 是否真的被接受——最后打印唯一的根因结论curl -fsSL https://raw.githubusercontent.com/OneUptime/oneuptime/master/HelmChart/Public/kubernetes-agent/troubleshoot.sh \ | bash -s -- -n oneuptime-agent它只读集群状态并跑几个探测不改动任何东西。手工校验密钥200 有效401 未知/已吊销curl -i -H x-oneuptime-token: YOUR_API_KEY $ONEUPTIME_URL/otlp/v1/validate无法kubectl exec进入 Agent Pod这是预期行为而非 bugmetrics-collector Deployment 与日志采集 DaemonSet 运行的是上游 OpenTelemetry Collector 镜像它是distroless基于FROM scratch构建只含 collector 二进制与 CA 证书——没有/bin/sh、没有bash、没有curl。需要 shell 时方式 A推荐无需改动安装用临时调试容器Kubernetes ≥ 1.23例如kubectl debug -it agent-pod --imagenicolaka/netshoot --targetotel-collector -- bash其与 collector 共享网络命名空间可测试完全一致的出口路径。方式 B内置调试 sidecar--set debug.enabledtrue会把nicolaka/netshootsidecar 注入 metrics Deployment 与日志 DaemonSet并开启shareProcessNamespace。用完记得关掉--set debug.enabledfalse因为它给每个 Agent Pod 增加了常驻容器额外资源 攻击面。API 模式的日志 tailer 运行 Node.js 镜像、自带 bash可直接 exec。源码级参考Chart 配置全量定义HelmChart/Public/kubernetes-agent/values.yaml1200 行每个参数均有注释与取舍说明Chart 说明与资源调优建议HelmChart/Public/kubernetes-agent/README.md含按集群规模的 recommended sizing 与各组件默认资源表节点日志/主机指标 DaemonSettemplates/daemonset.yamleBPF 自动插桩 DaemonSettemplates/daemonset-ebpf.yamlAPI 模式日志 tailer Deploymenttemplates/deployment-logs-api.yaml日志富化选择器 ConfigMaptemplates/configmap-ebpf.yaml诊断脚本troubleshoot.shAPI 模式日志 tailer 的实现位于仓库的 KubernetesLogTailer 目录含批量导出、重试、namespace 过滤等逻辑如果你的集群规模较大Chart README 还提供了 small≤10 节点、medium10–50 节点默认值即为此档设计、large50–200 节点与 extra-large200 节点四档资源模板可直接以-f应用并在安装后通过kubectl top pod -n oneuptime-kubernetes-agent观察实际用量、按约 1.5 倍峰值设置 limit。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考