PostHog APM 的 apm-spans-count 工具span 计数预检的完整使用指南【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog本文讲解 PostHog 开源仓库中 APM应用性能监控MCP 工具集里的apm-spans-count工具——一个返回满足过滤条件的 trace span 标量计数的轻量查询入口。它在 PostHog 的 APM 追踪工作流中扮演廉价预检pre-flight角色用于在拉取大量 span 明细之前估算结果集规模、回答有多少条 X span这类问题。读完本文你将掌握该工具的请求格式、全部参数语义日期范围、服务名、OTel 状态码、属性过滤组、与query-apm-spans的协作方式以及它背后的 HogQL 计数实现与防超量扫描保护机制。一、工具定位为什么需要 span 计数apm-spans-count的定义与使用场景记录在 apm-spans-count.md 中它的核心定位是标量计数返回满足过滤条件的 span 数量而不是 span 明细行。官方提示词总结了三个典型使用时机在query-apm-spans之前作为预检先确认过滤条件组合返回的 span 数量在可控范围内避免盲拉大量明细行回答有多少条 X span当用户只关心数量、不需要逐条查看 span 时直接返回一个数字比拉取全量数据再数更高效提交完整查询前验证过滤组合是否有任何命中如果一个过滤组合没有任何匹配count返回0就不必继续执行后续的完整查询。从实现层面看count_query_runner.py 的类文档同样明确Cheap pre-flight before query-apm-spans: lets a caller size the result set before pulling rows. Reuses the shared filter builder so the count matches what the list query would select.在query-apm-spans之前的廉价预检让调用方在拉取行之前先评估结果集规模。复用共享的过滤器构建器确保计数与列表查询所选结果一致。这印证了文档中过滤条件与query-apm-spans完全一致的设计意图——预检的数字就是后续全量查询会返回的数字。二、计数对象是 span不是 trace文档强调了一个容易被忽略的语义区别该工具统计的是 span而不是 trace。一条 trace 往往包含大量 span入口根 span 加上其子孙 span因此匹配的 span 数必然大于匹配的 trace 数。这一点在后端实现中有精确的对应。count_query_runner.py生成的 SQL 为见 count_query_runner.pySELECT count(), uniqExactIf(trace_id, is_root_span 1) FROM posthog.trace_spans WHERE {where}count()统计的是posthog.trace_spans表中所有满足where条件的行数即每个匹配 span 一行对应Spans 视图的行数uniqExactIf(trace_id, is_root_span 1)统计的是根 span 匹配的去重 trace 数——只统计满足条件且is_root_span 1的 trace与Traces 视图的语义保持一致。因此该接口的响应实际包含两个字段见 count_query_runner.pycount匹配的 span 总数traceCount根 span 匹配的独立 trace 数。test_count_query_runner.py 用一个3 条 trace ×1 个根 span 2 个子 span 9 个 span的种子数据验证了这一语义不加过滤时count 9而traceCount 3。更有说服力的是子 span 过滤器测试test_count_query_runner.py当过滤条件为is_root_span False只匹配子 span时响应为{count: 6, traceCount: 0}——6 个子 span 被计数但因为没有任何 trace 的根 span 命中Traces 视图显示 0 条 tracetraceCount必须与之对齐而不能按任意匹配 span去数 trace。三、请求格式所有参数都在 query 内apm-spans-count的请求格式与query-apm-spans一致所有参数必须放在query字段内部顶层字段会被拒绝。最小可用请求示例{ query: { serviceNames: [api], dateRange: { date_from: -1h } } }该工具在 tools.yaml 中被声明为 MCP 工具绑定后端操作tracing_spans_count_create对应POST /api/projects/{project_id}/tracing/spans/count/端点视图实现在 views.py需要tracing:read权限由tracingfeature flag 控制并标注为readOnly: true、idempotent: true只读、幂等可安全重复调用。响应体只包含count一个字段的声明实际还包含traceCount见上文。四、参数详解query.dateRange计数时间窗口时间范围默认最近一小时-1h。date_from范围起点。接受 ISO 8601 时间戳或相对格式-1h、-6h、-1d、-7d、-30ddate_to范围终点格式相同。省略或设为null表示当前时刻。后端的日期范围校验逻辑位于 date_window.py非法日期会抛出ValidationError并返回 HTTP 400而不是静默回退到 now保证计数窗口与调用方预期严格一致。query.serviceNames按服务名过滤按服务名过滤。与query-apm-spans不同未加过滤条件的计数本身是廉价且有价值的——它常被用来在细化过滤器之前先对某个过滤条件做规模评估。可以通过apm-services-list工具声明于 tools.yaml对应操作tracing_spans_service_names_retrieve发现当前项目存在哪些服务名再据此构造serviceNames过滤。query.statusCodes按 OTel span 状态码过滤按OTel span 状态码过滤整数列表不是 HTTP 状态码0Unset未设置1OK成功2Error错误使用[2]即可选择错误 span。例如统计最近一天 api-gateway 服务的错误 span 数{ query: { serviceNames: [api-gateway], statusCodes: [2], dateRange: { date_from: -1d } } }query.filterGroup属性过滤组属性过滤器列表用于进一步收窄计数。其格式与query-apm-spans的过滤器完全一致——每个过滤器指定key、operator、type以及可选的value。三种type的含义可参考 query-apm-spans.mdspan过滤内置 span 字段如trace_id、span_id、duration、name、kind、status_code、is_root_spanspan_attribute过滤 span 级属性如http.method、http.status_codespan_resource_attribute过滤资源级属性如 k8s 标签、部署信息。支持的运算符按值类型区分字符串exact、is_not、icontains、not_icontains、regex、not_regex数值exact、gt、lt存在性无需 valueis_set、is_not_set。value字段按运算符接受字符串、数字或字符串数组is_set/is_not_set需省略value。注意duration类字段的数值以纳秒为单位1 秒 1,000,000,000 纳秒。五、超大扫描保护触发 400 时如何自救文档明确警告如果计数将要扫描的数据量过大例如宽时间范围且不加任何过滤器工具会返回 HTTP 400提示你收窄窗口或补充过滤器。这正是为了保住预检的廉价性——预检本身不该变成一次昂贵的全表扫描。后端的防护有两层见 count_query_runner.pyHogQL 全局设置max_execution_time30查询最多运行 30 秒、max_bytes_to_read10_000_000_000最多读取 10 GB 数据、read_overflow_modethrow超限直接抛错而非截断。注释表明这是与日志计数 runner 对同类表采用的一致上限策略——计数应当快速失败而不是无界扫描错误转换视图层捕获 ClickHouse 的CHQueryErrorTooManyBytes异常返回可操作的 400 响应views.py提示语为This count scans too much data to run as a pre-flight. Narrow the date range or add serviceNames, statusCodes, or filterGroup filters, then retry.因此遇到 400 时的标准自救步骤是收窄dateRange或补充serviceNames/statusCodes/filterGroup过滤器后重试。测试 test_count_query_runner.py 也验证了无服务过滤返回窗口内全部 span与不存在的服务返回 0两个边界行为。六、实战示例示例一统计某服务最近一天的错误 span{ query: { serviceNames: [api-gateway], statusCodes: [2], dateRange: { date_from: -1d } } }示例二拉取明细前先统计匹配某名称的 span 数{ query: { filterGroup: [{ key: name, operator: exact, type: span, value: redis_cluster.discovery }], dateRange: { date_from: -6h } } }如果返回值count很大就应先用excludeAttributes之类的优化手段或进一步收窄dateRange/ 增加serviceNames、statusCodes、filterGroup过滤条件再执行query-apm-spans拉取明细——这正是预检的核心价值闭环。七、与 APM MCP 工具集的分工协作apm-spans-count不是孤立的工具它处于一个完整的 APM 追踪 MCP 工具生态中全部声明于 tools.yamlcategory 为Tracing统一挂在/tracing前缀下。围绕计数的常见协作路径是发现服务先用apm-services-list拿到项目里实际发出过 span 的服务名清单再决定serviceNames填什么发现属性用apm-attributes-list列出可用的 span/资源属性键用apm-attribute-values-list查看某个键下存在的取值避免凭空猜测filterGroup的key/value预检计数用apm-spans-count估算过滤条件下的 span 总量判断是否值得继续拉取明细规模可接受后用query-apm-spans分页拉取 span支持orderBy、rootSpans、flatSpans、prefetchSpans、excludeAttributes、游标after等参数详见 query-apm-spans.md深入单条 trace拿到trace_id后用apm-trace-get查看该 trace 的完整 span 树。除此之外同一工具集中还有apm-spans-aggregatespan 统计聚合、apm-spans-duration-histogram耗时分布直方图、apm-spans-latency-heatmap延迟热力图、apm-spans-sparkline随时间变化的 span 计数、apm-spans-tree聚合调用树、apm-attribute-breakdown按属性值拆分等分析类工具配合apm-spans-count可以完成从有多少到长什么样慢在哪的完整排查链路。八、实现原理小结最后用一张语义对照表收束全文帮助你在调用时快速对齐预期概念说明源码依据count匹配的 span 总数trace_spans表行数count_query_runner.pytraceCount根 span 匹配的独立 trace 数对齐 Traces 视图count_query_runner.py时间窗口半开区间timestamp date_from AND timestamp date_to精确匹配请求窗口count_query_runner.py资源上限30 秒执行时间、10 GB 读取上限、超限抛错count_query_runner.py400 语义CHQueryErrorTooManyBytes→ 提示收窄窗口或加过滤器的可操作 400views.py过滤语义与query-apm-spans完全共享过滤器构建器预检数字即全量查询数字count_query_runner.py掌握apm-spans-count的语义边界span vs trace、OTel 状态码 vs HTTP 状态码与防超量保护机制你就能在 PostHog APM 排查中先用一行数字快速判断问题规模再决定是否以及如何深入拉取明细避免无谓的大查询开销。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考