monitoring-capture-service

使用 Grafana MCP 监控 capture 服务

capture 服务（rust/capture/）是 PostHog 的 Rust HTTP 摄入端点。 它接收来自 SDK 的事件，应用配额/速率限制，并生产到 Kafka。 五个部署运行同一个二进制文件，但使用不同的 CAPTURE_MODE 配置，每个部署位于各自的 K8s 命名空间中。

本技能教你如何使用 Grafana MCP 工具发现实时指标， 而不是去记忆那些随着代码演进会变化的指标名称。

环境上下文

Grafana MCP 连接到一个单一的 Grafana 实例，其作用域限定于一个环境。 如果用户没有指定，询问他们想要调查哪个环境：

• prod-us — 美国生产环境 (us-east-1)
• prod-eu — 欧盟生产环境 (eu-central-1)

大多数 capture 应用指标（例如 capture_*、http_requests_*、envoy_cluster_*）都是 环境特定的，这取决于你连接的是哪个 Grafana——它们不带有 environment 标签。MSK 和 CloudWatch 指标确实带有 environment 标签，但 仍然限定于所连接的 Grafana 的 AWS 账户。

跨环境比较需要切换 Grafana 实例（在单个会话中无法做到）。

可观测性全景

Capture 涵盖七个遥测域。 每个域都有一个 Grafana 数据源和一个发现入口点。

域	数据源 UID	发现工具	范围过滤器
应用指标 (VictoriaMetrics)	victoriametrics	list_prometheus_metric_names	regex: "capture_.*"
应用指标 (实时)	victoriametrics-realtime	同上	同上（保留期更短，分辨率更高）
日志	P44D702D3E93867EC (Loki-logs)	list_loki_label_names	app=~"capture.*"
性能分析	pyroscope	list_pyroscope_profile_types	service_name="capture-analytics/capture-analytics"
仪表板	不适用	search_dashboards	查询 "capture" 或 "ingestion"
CloudWatch (ElastiCache, MSK)	P034F075C744B399F	query_prometheus	environment="prod-us"
CloudWatch Root (仅 prod-us)	PAAE47F430CFD1449	同上	根账户 AWS 指标（在 prod-eu 中不存在）

稳定的参照点

这些事实很少变化，且难以动态发现。

部署角色

每个 capture 变体都作为 独立的 K8s 部署运行在各自的命名空间中。 主要的作用域标签是 namespace 和 container（不是 role——该标签 包含 Pod 名称，不适用于过滤）。

部署	命名空间	capture_mode	流水线	备注
capture-analytics	capture-analytics	events	主事件	流量最大；路由 /e、/i/v0/e 等
capture-ai	capture-ai	events	AI/大模型事件	路由 /i/v0/ai；OTel 监听端口 4318
capture-replay	capture-replay	recordings	会话录制	路由 /s/；CAPTURE_MODE=recordings
capture-mirrored	capture-mirrored	events	镜像/金丝雀	并非始终运行；指标与 analytics 相同
capture-logs	capture-logs	—	日志摄取	OTel 日志监听端口 4318

所有变体共享同一个 Rust 二进制文件（ghcr.io/posthog/posthog/capture）。

使用 namespace=~"capture-.*" 或 container=~"capture-.*" 限定 capture 指标的作用域。 对于单个流水线，按 namespace 限定作用域（例如 namespace="capture-analytics"）。

Envoy 集群命名

Envoy 指标使用 envoy_cluster_name 来标识上游后端。 模式：posthog_{deployment}_{port}。

与 capture 相关的集群： posthog_capture-analytics_3000、posthog_capture-ai_3000、posthog_capture-replay_3000、 posthog_capture-mirrored_3000、posthog_capture-logs_4318、posthog_capture-logs-canary_4318。

capture-replay 还有一个用于 KEDA 自动扩缩容的 proxy-as-a-service 集群： proxy-as-a-service_capture-replay_3000。

使用以下方式限定作用域：envoy_cluster_name=~"posthog_capture-.*"。

Redis 实例拓扑

Capture 依赖最多三个逻辑 Redis 实例， 外加 Envoy 层的一个外部实例（不在 capture 二进制中）。 它们都不发出 capture_redis_* 指标——Redis 的健康状况通过 capture 侧的 指标和 CloudWatch ElastiCache 指标推断。

1. 主 Redis（REDIS_URL 环境变量）

• ElastiCache：posthog-solo（prod-us）或 posthog-prod-redis-encripted（prod-eu；原文如此——实际集群名中有拼写错误）
• 两个环境都为 token 缓存使用只读端点（REDIS_READER_URL）
• 支撑：计费/配额限制（CaptureQuotaLimiter）、会话回放溢出限制器
• Capture 指标：capture_billing_limits_loaded_tokens（按 cache_key）、 capture_quota_limit_exceeded（按 resource）
• 配额资源：events、exceptions、llm_events、recordings、survey_responses
• 缓存键：@posthog/quota-limits/{resource}、@posthog/capture-overflow/replay

2. 全局限流 Redis（GLOBAL_RATE_LIMIT_REDIS_URL，可选）

• ElastiCache：capture-globalratelimit-{env}-redis（prod-us、prod-eu；不含 dev）
• 支撑：按 (token, distinct_id) 的滑动窗口限流器
• 当 URL 未设置时回退到主 Redis
• 可选的只读副本：GLOBAL_RATE_LIMIT_REDIS_READER_URL
• 开关：GLOBAL_RATE_LIMIT_ENABLED（在灰度发布期间某些环境可能关闭）
• 指标：global_rate_limiter_*（直接）、capture_events_rerouted_overflow{reason="rate_limited"}（代理信号）
• global_rate_limiter_window_seconds{scope} 发布每个进程的窗口。capture-analytics 和 capture-ai 共享 AI 字节预算，因此如果它们在这个 gauge 上不一致，说明共享预算已经分裂
• CloudWatch 集群 id：capture-globalratelimit-prod-redis

3. 事件限制 Redis（EVENT_RESTRICTIONS_REDIS_URL）

• ElastiCache：ingestion-prod-redis（两个环境中独立的可写集群）
• 存储由 Django 同步的摄取限制配置
• 当 URL 未设置时回退到主 Redis
• Capture 指标：capture_event_restrictions_redis_fetch（标签：restriction_type、 result，取值为 success/not_found/error/parse_error）、 capture_event_restrictions_stale、capture_event_restrictions_loaded_count

4. Contour 限流 Redis（ratelimit-{env}-redis）——不在 capture 二进制中

• 在 Envoy 入口层、capture 之前实施的按 IP 的 DoS 防护
• 指标：ratelimit_service_*（标签：domain="posthog"）

指标前缀

此处的每个前缀都可以通过 list_prometheus_metric_names 实时发现， 使用 datasourceUid: "victoriametrics" 和 regex: "<prefix>.*"。

前缀	领域	作用域标签
capture_*	应用指标（约 80 个指标）	namespace、container
http_requests_*	HTTP 层（共享）	namespace=~"capture-.*"
capture_kafka_*	Kafka 生产者（17 个指标）	namespace、container
capture_billing_*	已加载的计费/配额令牌	namespace、cache_key
capture_event_restrictions_*	事件限制（6 个指标）	namespace、restriction_type
capture_ai_otel_*	AI/OTel 采集（12 个指标）	namespace="capture-ai"
envoy_cluster_*	L7 代理	envoy_cluster_name=~"posthog_capture-.*"
aws_msk_*	MSK 代理端（JMX）	environment="prod-us" 或 "prod-eu"
ratelimit_service_*	Contour 速率限制	domain="posthog"
overflow_redirect_*	Node.js 摄取溢出（下游）	ingestion_pipeline
kube_* / container_*	K8s 资源	namespace=~"capture-.*"、pod=~"capture-.*"

Kafka 主题

主题捕获写入的目标（可通过 capture_kafka_produce_avg_batch_size_bytes 上的 topic 标签实时发现）。 分区数编码在主题名称中，且因环境而异（EU 的分区通常更少）。

捕获根据流水线写入两个不同的 Kafka 后端系统：

• MSK 摄取集群 — 分析事件（main、overflow、historical、turbo）、热力图、错误跟踪、客户端警告
• WarpStream — 会话回放（warpstream-replay-v2 VC）、日志（warpstream-logs VC）、追踪（warpstream-traces VC）

主题 (prod-us / prod-eu)	后端	流水线
ingestion-analytics-main-1024 / -512	MSK	主事件
ingestion-analytics-overflow-128	MSK	溢出（受速率限制 / 高流量令牌）
ingestion-analytics-historical-128	MSK	历史回填事件
ingestion-analytics-turbo-1024	MSK	通用 turbo（仅 prod-us）
ingestion-heatmaps-main-128	MSK	热力图
ingestion-errortracking-main-128	MSK	错误跟踪
ingestion-errortracking-overflow-32	MSK	错误跟踪溢出
ingestion-clientwarnings-main-16 / -32	MSK	客户端警告
ingestion-sessionreplay-main-512 / -256	WarpStream	会话回放
ingestion-sessionreplay-overflow-64 / -32	WarpStream	会话回放溢出
ingestion-logs	WarpStream	日志摄取
ingestion-traces	WarpStream	追踪摄取
ingestion-analytics-main-dlq (+ 每个流水线的 DLQ 主题)	MSK	死信队列

Pyroscope 服务

服务名称	部署
capture-analytics/capture-analytics	主捕获
capture-ai/capture-ai	AI 捕获
capture-replay/capture-replay	回放捕获
capture-mirrored/capture-mirrored	镜像 / 金丝雀（运行时）
capture-logs/capture-logs	日志捕获

剖析类型：process_cpu:cpu:nanoseconds:cpu:nanoseconds、 wall:wall:nanoseconds:wall:nanoseconds、 memory:inuse_space:bytes:inuse_space:bytes、 memory:inuse_objects:count:inuse_space:bytes。

Grafana 仪表盘

UID	标题	用途
capture	Capture	跨 capture 部署的总览 — 从这里开始
capture-v1-details	V1 详情	v1 管道的逐面板详情（/i/v1/analytics/events）
ddfkdj56ds11xce	Legacy 详情	旧版 v0 管道的逐面板详情（/e/、/batch/、/i/v0/e/）
ingestion-health	Ingestion - 健康	跨服务的数据摄入健康度
ingestion-analytics	Ingestion - 分析	下游分析管道，按 lane 划分
ingestion-pipelines	Ingestion - 管道	端到端管道吞吐量与延迟
ingestion-reliability	Ingestion - 可靠性	已摄入事件趋势、处理延迟 SLO、Pod 重启次数
ingestion-sessionreplay	Ingestion - 会话回放	会话回放数据摄入
contour	Contour Ingress	Envoy L7 代理（设置 envoy_cluster_name=posthog_capture-analytics_3000）
AWSRedis	AWS ElastiCache Redis	每个集群的 CloudWatch Redis 指标（筛选 cacheclusterId）

两个详情看板位于 Capture/Ingestion/ 下，并且彼此互相链接，同时也链接到总览看板。两个管道共用的机制相关部分（全局速率限制器、事件限制、Hyper 服务器、Contour、计费/配额）会出现在两个详情看板上，因此使用你当前所在的任意一个即可。

有一个看板你可以通过 search_dashboards 找到，但不应依赖它：capture-3000-envoy-codes 是一个个人的、仅限 US 的 Envoy 调查看板（未同步到 EU）。

发现工作流

Prometheus / VictoriaMetrics

1. list_prometheus_metric_names — datasourceUid: "victoriametrics"、regex: "capture_.*"，用于枚举应用指标
2. 选择一个指标，然后针对它执行 list_prometheus_label_names — 查看可用的维度
3. list_prometheus_label_values — 发现某个标签的实际值 （例如在 capture_events_dropped_total 上的 labelName: "cause"）
4. 使用 PromQL 执行 query_prometheus — 始终按 namespace（或 container）限定范围，并设置时间范围

Loki（日志）

1. list_loki_label_names — datasourceUid: "P44D702D3E93867EC"（Loki-logs；不要使用主 Loki P8E80F9AEF21F6940，它会间歇性返回 502）
2. 对 app 或 namespace 执行 list_loki_label_values — 查找 capture 容器
3. query_loki_logs — 例如 {app=~"capture.*"} |= "error"

Pyroscope（性能分析）

1. list_pyroscope_profile_types — data_source_uid: "pyroscope"
2. fetch_pyroscope_profile — matchers: '{service_name="capture-analytics/capture-analytics"}'、 profile_type: "process_cpu:cpu:nanoseconds:cpu:nanoseconds"

仪表盘

1. search_dashboards — 查询 "capture" 或 "ingestion"
2. get_dashboard_by_uid — 使用已知的 UID（例如 "capture"）获取面板详情
3. get_dashboard_panel_queries — 从现有面板中提取 PromQL

Redis / ElastiCache

• Capture 侧：在 VictoriaMetrics 中发现 capture_billing_*、capture_event_restrictions_*、 capture_quota_* 指标
• 基础设施：用于 ElastiCache 的 CloudWatch 数据源 P034F075C744B399F （CPU、内存、连接数、延迟）。 集群 ID：capture-globalratelimit-prod-redis、posthog-solo（prod-us 主集群）

关键指标领域

需要关注的内容分类。使用上面的前缀实时发现具体指标。

HTTP 层 —— 请求速率、延迟分布（p50/p99）、活跃连接数、 按状态码划分的错误率。指标：http_requests_*，按 namespace 限定范围，capture_active_connections。

事件生命周期 —— 从接收到摄入再到丢弃/改道的漏斗。 capture_events_received_total -> capture_events_ingested_total -> capture_events_dropped_total。 丢弃事件上的 cause 标签有 20+ 个值（实时发现）。自 golden-chart 迁移以来的关键新增：event_restriction_drop、event_too_big、otel_quota_drop、oversize_event、 ai_opt_in、gathering、invalid_session、no_session_id、no_snapshot。 改道：capture_events_rerouted_overflow，带 reason 标签 （rate_limited、force_limited、event_restriction）。 另外：capture_events_rerouted_custom_topic，用于主题重定向限制。

Kafka producer —— broker 连通性（capture_kafka_any_brokers_down、 capture_kafka_broker_connected）、队列饱和度（_queue_depth / _queue_depth_limit）、 produce RTT（capture_kafka_produce_rtt_latency_us，按 quantile 和 broker 划分）、 投递错误（capture_kafka_produce_errors_total）。

计费与配额 —— capture_billing_limits_loaded_tokens，按 cache_key 划分； capture_quota_limit_exceeded，按 resource 划分（events、exceptions、llm_events、recordings、survey_responses）。

事件限制 —— capture_event_restrictions_*，用于 Redis 获取健康度、 陈旧度、已加载数量、按 restriction_type 划分的已应用限制 （drop_event、force_overflow、redirect_to_topic、skip_person_processing）。

Envoy proxy —— 上游延迟、响应码（2xx/4xx/5xx）、连接健康度、 熔断器（_open gauge）、后端成员数（健康 vs 总数）、 超时、重试。始终过滤：envoy_cluster_name=~"posthog_capture-.*"。 对于 capture-replay，还要检查 proxy-as-a-service_capture-replay_3000。

Contour 速率限制 —— ratelimit_service_*，用于按 IP 的 DoS 防护。 ratelimit_service_rate_limit_over_limit = 正在被限流的 IP。

MSK broker 侧 —— aws_msk_* JMX 指标，用于 capture-analytics、capture-ai 及其他由 MSK 支撑的主题。 关键信号：节流时间、网络处理器空闲百分比、内存池耗尽、请求队列大小。 两个环境都有一个专用的 ingestion MSK 集群，与 events 集群分离 （prod-us：c21；prod-eu：posthog-prod-eu-ingestion-2026-05-04）。

WarpStream —— warpstream_agent_* 指标，用于 capture-replay、capture-logs 和 traces。 这些流水线写入集群内的 WarpStream agent，而非 MSK。 关键信号：warpstream_agent_control_plane_operation_counter（按 operation 划分）、 warpstream_agent_file_cache_client_fetch_local_or_remote_counter（缓存命中/未命中比率）。 仪表盘：warpstream（Agent Overview）、dbfj5c31spa1ogf（MSK vs WarpStream — Active Produce Topics）。 仅限美国的个人仪表盘（未同步到 EU）：ws-coarse-lag-explore（Coarse Lag）、8e93b023-…（CH Consumer Lag）。 按 VC 划分的 KMinion 实例：kminion-warpstream-replay、kminion-warpstream-logs、kminion-warpstream-traces。

K8s 资源 —— container_* 和 kube_*，用于 CPU、内存、重启、HPA 状态。 范围：namespace=~"capture-.*"、pod=~"capture-.*"。

排查手册

参见 references/investigation-playbooks.md， 了解针对常见问题的分步工作流： 健康检查、事件丢失、延迟、Kafka 背压、速率限制、Redis 以及跨环境对比。