使用 pyroscope-monitoring Helm Chart 监控 Grafana Pyroscope基于 otel-lgtm 与 k8s-monitoring 的一站式可观测性方案【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope本指南以仓库内 pyroscope-monitoring 官方 Helm Chart 文档为核心讲解如何用otel-lgtm镜像 k8s-monitoring子 Chart 快速搭建 Grafana Pyroscope 的指标采集、日志与追踪观测环境并自动预置 4 张 Pyroscope 专属 Grafana 仪表盘。读完本文你将掌握该 Chart 的安装方法、仪表盘体系、Native/Classic 直方图切换原理以及全部 Values 参数的含义与调优方法并能基于仓库源码理解其模板与生成机制。Chart 概览与适用场景pyroscope-monitoring是 Grafana Pyroscope 仓库operations目录下提供的一个Helm Chartv2 格式版本 0.1.1其定位非常明确用它来监控 Grafana Pyroscope 后端自身的健康状态。与监控应用业务的方案不同它观测的是 Pyroscope 分布式组件的运行指标、日志与链路追踪。根据 Chart.yaml 中的描述A Helm chart for monitoring Grafana Pyroscope. This helm chart uses otel-lgtm to monitor the health of the Grafana Pyroscope backend.该 Chart 的技术底座是otel-lgtmLGTM Loki Grafana Tempo Mimir/Prometheus将指标、日志、追踪三大可观测性数据统一收纳在一个 Deployment 中并在此基础上叠加k8s-monitoring别名monitoring版本 3.8.8子 Chart 负责 Kubernetes 集群级指标、事件与 Pod 日志的采集。⚠️注意官方原文警告This monitoring setup isnot production gradeand is intended fordevelopment and testing purposes only.——该监控方案不适用于生产环境仅面向开发与测试场景。这是因为其数据存储均使用emptyDir临时卷重启即丢失且采用单副本部署。架构与工作原理otel-lgtm k8s-monitoring从 values.yaml 与 deployment.yaml 的源码结构可以还原出整个监控链路一个 Deployment 承载全部可观测性组件默认使用grafana/otel-lgtm:0.11.10镜像单副本replicaCount: 1运行内部同时提供 Grafana3000、OTel gRPC4317、OTel HTTP4318、Prometheus9090、Loki3100五个端口见 service.yaml 与 values.yaml 中的service.ports。k8s-monitoring 子 Chart 负责采集通过monitoring别名引入k8s-monitoring3.8.8在其global段开启 Prometheus 协议抓取与 Native Histogram 采集并启用clusterMetrics集群指标如 kube-state-metrics、clusterEventsKubernetes 事件、podLogsPod 日志、annotationAutodiscovery注解自动发现与applicationObservability含 Jaeger 接收器。三路数据出口destinationsotlp-gatewayOTLP HTTP 协议写入http://pyroscope-monitoring:4318承载traces追踪loki写入http://pyroscope-monitoring:3100/loki/api/v1/push承载logs日志prometheus写入http://pyroscope-monitoring:9090/api/v1/write承载metrics指标并开启sendNativeHistograms: true。values.yaml 中这两处注释很有价值Unable to keep container/namespace/job/cluster as indexed labelLoki 标签限制与Was not able to get native histograms to work with otlp-gateway原生直方图只能走 Prometheus 协议不能走 OTLP gateway这也是为什么指标必须单独走 Prometheus 写路径的原因。静态 Service 名称保证子 Chart 可达service.deployStaticName: true会让模板额外创建一个名字固定为pyroscope-monitoring的 Service见 service.yaml因为 k8s-monitoring 子 Chart 的 destinations 配置硬编码引用了该名称。从源码结构看即使通过nameOverride/fullnameOverride修改了 Chart 名称该固定 Service 仍会保留。此外仓库还附带了独立的演示清单 lgtm.yaml用最朴素的方式一个 Service 一个 Deployment手动部署grafana/otel-lgtm:latest用于 demo/测试场景可作为理解 Chart 内部部署形态的最小参考。快速开始安装 ChartChart 本身是标准 Helm v2 格式并声明了对k8s-monitoring3.8.8 的依赖见 Chart.yaml仓库地址为https://grafana.github.io/helm-charts依赖条件为monitoring.enabled。安装前需先拉取依赖helm repo add grafana https://grafana.github.io/helm-charts helm dependency build operations/monitoring/helm/pyroscope-monitoring随后标准安装即可release 名称可自定义如pyroscope-monitoringhelm install pyroscope-monitoring operations/monitoring/helm/pyroscope-monitoring \ --namespace default --create-namespace安装完成后可通过kubectl port-forward svc/pyroscope-monitoring 3000:3000访问内置 Grafana。deployStaticName生成的固定 Service 端口与主 Service 完全一致二者都可作为访问入口。若只是想快速体验 otel-lgtm 本身也可直接应用 lgtm.yamlkubectl apply -f operations/monitoring/helm/pyroscope-monitoring/lgtm.yaml仪表盘Pyroscope 文件夹下的 4 张预置看板Chart 会在 Grafana 的Pyroscope 文件夹下自动预置 4 张仪表盘列表见 README.md 与 _dashboards.tpl 中的$dashboards定义仪表盘说明operational通用运维指标看板覆盖 Pyroscope 集群的全局运行概况Bird eyes view of Pyroscope clusters见 _dashboard_operational.yamlv2-metastoreMetastore 相关指标看板仅在使用 v2 存储层时相关v2-read-path读路径性能看板聚焦 v2 存储层v2-write-path写路径性能看板聚焦 v2 存储层实现机制上每张仪表盘的模板定义在templates/_dashboard_*.yaml中如 _dashboard_operational.yaml由 _dashboards.tpl 中的pyroscope-monitoring.dashboards-configmap模板统一渲染进一个名为fullname-dashboards的 ConfigMap见 dashboards.yaml以grafana-dashboards.yaml声明 Grafana provisioning providertype: file、allowUiUpdates: true并归属到folder: Pyroscope每个仪表盘的 JSON 通过fromYamlmustToRawJson生成若模板渲染出错会直接fail_dashboards.tpl保证渲染失败时安装立即报错而不是交付损坏的看板Deployment 的 Pod 注解上会写入dashboards/hash所有看板内容的 sha256 摘要见 deployment.yaml看板内容变化会触发 Pod 滚动重启实现配置热同步。这些看板可直接在 Grafana 中修改allowUiUpdates: true但注意重新部署 Chart 时模板会重新渲染手工修改会被覆盖。持久的修改应改模板或通过dashboards.links等 Values 注入。Native 与 Classic 直方图dashboards.nativeHistograms 切换Pyroscope 的指标大量使用直方图如写入字节数、压缩耗时等。该 Chart 通过一个开关控制 PromQL 查询风格这是官方文档特别强调的核心配置README.mddashboards.nativeHistograms: true默认使用原生直方图函数histogram_sum、histogram_count、histogram_quantile、histogram_avg。前提条件是 Prometheus 抓取配置中开启scrape_native_histograms: true。dashboards.nativeHistograms: false回退到经典直方图后缀查询_bucket、_sum、_count。一个典型示例是tenantQuery多租户指标汇总查询见 values.yaml它用 Helmtpl按开关渲染两种风格dashboards: tenantQuery: | sum by (tenant, slug, org_name, environment) ( {{- if .Values.dashboards.nativeHistograms }} histogram_sum(rate(pyroscope_distributor_received_decompressed_bytes{cluster~$cluster,namespace~$namespace}[$__rate_interval])) {{- else }} rate(pyroscope_distributor_received_decompressed_bytes_sum{cluster~$cluster,namespace~$namespace}[$__rate_interval]) {{- end }} )这个查询基于 distributor 暴露的pyroscope_distributor_received_decompressed_bytes指标按tenant / slug / org_name / environment维度聚合各租户的接收流量是理解看板数据来源的好入口对应指标定义可参考 distributor/metrics.go。对应的落地文件是生成物而非手写物原生直方图版本提交在 operations/monitoring/dashboards/经典版本提交在 operations/monitoring/dashboards-classic-histogram/官方明确要求不要直接编辑这些 JSON它们由make helm/check自动生成。Values 参数详解以下是官方 README 中的完整参数表原表继承自 values.yaml由 helm-docs 生成随后给出分组深度讲解KeyTypeDefaultDescriptionaffinityobject{}dashboards.cadvisorSelectorstringjob~\(.*/)?cadvisor\dashboards.cloudBackendGatewayboolfalsedashboards.cloudBackendGatewaySelectorstringcontainer~\cortex-gw(-internal)?\dashboards.clusterstringpyroscope-devdashboards.eventsSelectorstringjob~\loki\\.source\\.kubernetes_events\|integrations/kubernetes/eventhandler\dashboards.ingestNamespaceSelectorstringnamespace~\$namespace\dashboards.ingestSelectorstringcontainer~\pyroscope\|distributor\|query-frontend\dashboards.kubeStateMetricsSelectorstringjob~\(.*/)?kube-state-metrics\dashboards.namespacestringdefaultdashboards.namespaceRegexstring.*dashboards.namespaceRegexPerDashboardobject{}dashboards.nativeHistogramsbooltruedashboards.tenantQuerystringsum by (tenant, slug, org_name, environment) (\n {{- if .Values.dashboards.nativeHistograms }}\n histogram_sum(rate(pyroscope_distributor_received_decompressed_bytes{cluster~\$cluster\,namespace~\$namespace\}[$__rate_interval]))\n {{- else }}\n rate(pyroscope_distributor_received_decompressed_bytes_sum{cluster~\$cluster\,namespace~\$namespace\}[$__rate_interval])\n {{- end }}\n)\nfullnameOverridestringimage.pullPolicystringIfNotPresentimage.repositorystringgrafana/otel-lgtmimage.tagstring0.11.10imagePullSecretslist[]nameOverridestringnodeSelectorobject{}podAnnotationsobject{}podLabelsobject{}podSecurityContextobject{}replicaCountint1resourcesobject{}securityContextobject{}service.deployStaticNamebooltrueservice.typestringClusterIPtolerationslist[]镜像与部署基础参数image.repository/image.tag/image.pullPolicyotel-lgtm 镜像仓库、标签与拉取策略。默认grafana/otel-lgtm:0.11.10、IfNotPresent。镜像内同时包含 Grafana、Prometheus、Loki、Tempo 与 Pyroscope 相关组件这是单 Deployment 承载全部观测组件的基础。replicaCount默认1。由于日志/指标/看板数据全部写入emptyDir多副本无法共享数据开发测试场景下维持单副本即可。resources/nodeSelector/affinity/tolerations标准调度与资源参数默认均为空。官方建议不主动设置资源限制以兼容 Minikube 等小资源环境见 values.yaml 的注释需要时再按需放开 CPU/内存 requests 与 limits。imagePullSecrets/podAnnotations/podLabels/podSecurityContext/securityContext/nameOverride/fullnameOverride镜像拉取密钥、Pod 注解/标签、安全上下文与命名覆盖均为标准 Helm 惯例参数。内置环境变量与存储卷envignored不进入生成文档预置两个环境变量——GF_PLUGINS_PREINSTALLgrafana-exploretraces-app预装 Explore Traces 插件GF_DASHBOARDS_DEFAULT_HOME_DASHBOARD_PATH将 Grafana 首页指向 otel-lgtm 自带的operational.json保证打开 Grafana 即见看板。volumes/volumeMountsignored为 Tempo、Loki、Grafana、Prometheus、Pyroscope 各自挂载emptyDir临时卷/data/tempo、/data/loki、/data/grafana、/data/prometheus、/data/pyroscope另外把看板 ConfigMap 挂载到/otel-lgtm/grafana/conf/provisioning/dashboards、把规则 ConfigMap 以subPath方式挂载为/otel-lgtm/prometheus.yaml并整体挂载到/prometheus-rules供 Prometheusrule_files读取。这是数据不持久、不适合生产环境的直接原因。Service 参数service.type默认ClusterIP可改为NodePort/LoadBalancer以暴露 Grafana 等端口。service.deployStaticName默认true。为true时额外创建一个名称固定为pyroscope-monitoring的 Service因为 k8s-monitoring 子 Chart 的 destinations 硬编码依赖该名称http://pyroscope-monitoring:4318等。若你显式以pyroscope-monitoring作为 release 名主 Service 恰好也叫这个名字则不会重复创建见 service.yaml 中的判等条件。service.portsignored固定开放 grafana(3000)、otel-grpc(4317)、otel-http(4318)、prometheus(9090)、loki(3100) 五个端口。仪表盘自定义参数dashboards.*这是 Chart 最具 Pyroscope 特色的配置组全部围绕看板的标签选择器与查询语义展开dashboards.namespace默认default看板默认作用的目标命名空间。dashboards.namespaceRegex默认.*用于过滤可选命名空间的正则多个命名空间场景下可用。dashboards.namespaceRegexPerDashboard默认{}按看板名覆盖命名空间正则键为看板名operational/v2-metastore/v2-read-path/v2-write-path。模板逻辑见 _dashboards.tpl使用dig先查 per-dashboard 覆盖未命中才回退到全局namespaceRegex。dashboards.cluster默认pyroscope-dev看板默认集群名用于cluster~$cluster标签匹配。dashboards.ingestSelector默认container~pyroscope|distributor|query-frontend数据接入ingest容器的标签选择器覆盖 Pyroscope 单二进制、distributor 与 query-frontend 三种容器形态。dashboards.ingestNamespaceSelector默认namespace~$namespace追加到 ingest 查询上的命名空间匹配器设为空字符串可移除见 _dashboards.tpl。dashboards.cloudBackendGateway默认false是否部署了 cloud-backend-gateway即此前的cortex-gw仅存在于 Grafana Cloud 环境。为true时 ingest 选择器改用dashboards.cloudBackendGatewaySelector默认container~cortex-gw(-internal)?详见 _dashboards.tpl 的dashboards-ingest-selector定义。dashboards.cadvisorSelector默认job~(.*/)?cadvisorcAdvisor 指标选择器用于容器 CPU 使用率等节点级指标。dashboards.kubeStateMetricsSelector默认job~(.*/)?kube-state-metricskube-state-metrics 选择器用于 workload/pod 归属关系ReplicaSet、DaemonSet、StatefulSet、Job的推导。dashboards.eventsSelector默认job~loki\\.source\\.kubernetes_events|integrations/kubernetes/eventhandlerKubernetes 事件日志选择器。dashboards.nativeHistograms默认true原生直方图开关见上文专门小节。dashboards.tenantQuery多租户流量汇总查询模板同时被 native/classic 两种风格渲染是理解指标数据模型的范例。dashboards.linksignored看板链接配置links.global提供全局链接默认在Pyroscope Dashboards下拉中提供跳转asDropdown: true、includeVars: true、keepTime: truelinks.perDashboard按看板追加链接。k8s-monitoring 子 Chart 参数monitoring.*monitoring.enabled: true时启用子 ChartChart.yaml 中的condition: monitoring.enabled控制。其关键配置位于 values.yamlmonitoring.globalscrapeProtocols同时启用 PrometheusProto 与多版本 OpenMetrics 文本协议scrapeClassicHistograms: true与scrapeNativeHistograms: true双开保证两种直方图风格的数据都能被抓取——这是看板能在两种模式间无缝切换的采集侧前提。monitoring.destinations三路数据出口OTLP gateway、Loki、Prometheus上文已述。monitoring.clusterMetrics开启集群指标含 opencost 与 kepler均默认关闭。monitoring.clusterEvents/podLogs/annotationAutodiscovery分别开启集群事件、Pod 日志与注解自动发现。monitoring.applicationObservability开启应用可观测性并启用 Jaeger thrift HTTP/Binary/Compact 三种接收协议。monitoring.alloy-metrics固定使用v1.10.2版本的 Alloy 镜像注释说明原因是 v1.11.0 默认禁用 Native Histogram 且无开关可开values.yaml——这是保证原生直方图链路可用的关键版本约束。monitoring.alloy-receiver额外开放 thrift-compact(6831/UDP)、jaeger-binary(6832/UDP)、jaeger-http(14268/TCP) 三个端口供 Jaeger 协议接入。从源码看实现模板、规则与看板生成机制看板与规则的 ConfigMap 装配Chart 将配置拆成两个 ConfigMapfullname-dashboardsdashboards.yaml包含grafana-dashboards.yamlprovisioning 文件与 4 个看板 JSON挂载进 Grafana 的 provisioning 目录由 otel-lgtm 内置的 Grafana 自动加载。fullname-rulesrules.yaml包含三部分内容见 _rules.tplprometheus.yamlPrometheus 主配置——otlp.keep_identifying_resource_attributes: true保留识别性资源属性otlp.promote_resource_attributes将service.name、k8s.namespace.name、k8s.pod.name、k8s.cluster.name等提升为标签storage.tsdb.out_of_order_time_window: 10m允许 10 分钟乱序写入窗口注释解释足以吸收重试与网络延迟rule_files指向/prometheus-rules/*.rules.yaml。k8s-rules-pod-owner.rules.yaml通过kube_pod_owner与kube_replicaset_owner等指标推导 Pod 的 workload 归属deployment/daemonset/statefulset/job生成namespace_workload_pod:kube_pod_owner:relabel记录规则看板据此按 workload 聚合。k8s-rules-pod-container-cpu-usage-seconds-total.rules.yaml基于container_cpu_usage_seconds_total与 cAdvisor 选择器生成node_namespace_pod_container:container_cpu_usage_seconds_total:sum_rate5m与sum_irate记录规则。自动生成流程make helm/check官方 README 明确说明operations/monitoring/dashboards/native与operations/monitoring/dashboards-classic-histogram/classic下的 JSON 均为make helm/check生成不应手工编辑。从 Makefile 可以看到完整流水线helm lintMakefile#L428-L431与helm-docsMakefile#L433-L436基于 README.md.gotmpl 重新生成 READMEhelm dependency update/build拉取 k8s-monitoring 子 Chart对 v1/v2、单二进制/微服务等形态分别执行helm template并用kubeconform做严格校验关键一步helm template pyroscope-monitoring --show-only templates/dashboards.yaml --show-only templates/rules.yaml渲染看板与规则再交由仓库内的 tools/monitoring-chart-extractor 提取成 JSON随后用--set dashboards.nativeHistogramsfalse再渲染一遍将经典风格产物输出到dashboards-classic-histogram/目录。也就是说原生与经典两套看板其实是同一批模板的两次渲染结果这保证了两种模式下看板结构、面板布局完全一致仅 PromQL 风格不同。仓库中的cr.yaml、ct.yaml位于 operations/monitoring/helm/进一步表明该项目使用 chart-testing 对 Chart 做 CI 校验。内部看板模板的转换来源_dashboard_operational.yaml 等模板每个数千行并非手写而是由 convert-dashboard.sh 从 Grafana Cloud 内部环境导出看板转换而来脚本将内部命名空间profiles-ops-002、集群名ops-eu-south-0、cortex-gw/cadvisor/kube-state-metrics 选择器分别替换为{{.Values.dashboards.*}}模板变量使看板可被 Chart 参数化复用。这解释了为何看板中有profiles-ops-002等历史命名痕迹——它们已在转换时被参数替换。看板里还内置了基于 Loki 的 K8s Changes 注解kube-diff-logger容器日志与 Flush Eventshead flush 日志等运维语义。验证与排障Chart 内置了helm test钩子templates/tests/test-metrics.yaml测试 Pod 使用同一 otel-lgtm 镜像中的promtool反复查询kube_node_info系列最多重试 30 次、每次间隔 5 秒确认 Prometheus 已经成功抓取到 kube-state-metrics 数据后才判定通过helm test pyroscope-monitoring常用排障思路看板不出现检查fullname-dashboardsConfigMap 是否就绪、Deployment 注解上的dashboards/hash是否变化触发重启确认 Grafana provisioning 路径/otel-lgtm/grafana/conf/provisioning/dashboards挂载正常。原生直方图查询无数据确认采集侧monitoring.global.scrapeNativeHistograms: true、指标出口走 Prometheus而非 OTLP gateway并确认alloy-metrics镜像为v1.10.2高版本可能默认禁用原生直方图。切换查询风格设置--set dashboards.nativeHistogramsfalse后重新helm upgrade看板将回退到_bucket/_sum/_count经典查询前提是scrapeClassicHistograms: true默认已开。多命名空间/多集群通过dashboards.namespaceRegex、dashboards.cluster以及按看板粒度的dashboards.namespaceRegexPerDashboard调整范围。使用限制与注意事项最后总结本方案的关键边界避免踩坑非生产方案数据存于emptyDirPod 重建即丢单副本无高可用这是官方明确声明的定位开发与测试用途。看板 JSON 为生成物不要直接编辑 operations/monitoring/dashboards/ 与 operations/monitoring/dashboards-classic-histogram/ 下的文件修改请走模板与 Values再通过make helm/check重新生成。静态 Service 名依赖k8s-monitoring 子 Chart 的 destinations 硬编码pyroscope-monitoring主机名请保持service.deployStaticName: true或确保 release 名恰为pyroscope-monitoring。原生直方图链路有版本门槛alloy-metrics镜像被固定在v1.10.2升级需验证原生直方图采集是否仍然生效。v2 相关看板v2-metastore、v2-read-path、v2-write-path三张看板聚焦 Pyroscope v2 存储层若使用经典 v1 存储层则只有operational看板具备直接参考价值仓库中 PYROSCOPE_V2.md 对 v2 架构有更完整说明。【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考