很多团队最早发现业务故障的地方，不是服务指标，也不是 Trace。
而是入口日志。
用户访问进来，网关会记录域名、路径、状态码、响应时间、上游地址、客户端 IP、TraceID。一次下单失败、一次支付超时、一次登录异常，通常都会先在网关访问日志里留下痕迹。
但问题是，很多团队只在事故发生后才去搜这些日志。
接口报错了，去搜状态码。
用户投诉了，去搜 trace_id。
响应变慢了，去搜 request_time。
某个路径异常了，去按 request_uri 聚合一下。
这当然能查现场。
但它没有把日志变成持续可观测的入口。
更好的做法是：把网关日志按接口维度做成日志报表，再基于日志报表生成接口层灭火图。
这样一来，每个核心接口都会变成一张卡片。
卡片能看到流量、成功率、响应时间。
异常时会飘红。
可以从卡片下钻到原始日志。
可以继续跳到 Trace、服务卡片、仪表盘和事件。
这篇文章讲的不是“怎么搜日志”。
而是怎么把日志报表变成接口层灭火图，让业务入口真正进入故障发现和排查路径。
为什么接口层适合从日志报表生成
接口层灭火图要回答的问题很简单：
哪些接口正在异常？
比如一个电商系统，值班人最关心的不是某个 CPU 高不高，而是：
下单接口是否正常。
支付接口是否正常。
登录接口是否正常。
商品详情接口是否正常。
优惠券接口是否正常。
支付回调接口是否正常。
这些对象天然来自入口流量。
而入口流量最完整、最稳定的数据源，通常就是网关日志或应用访问日志。
Prometheus 也可以做接口指标。
APM 也可以做接口视角。
但在很多企业里，最先具备完整覆盖的反而是日志。
尤其是网关层。
不管后端服务是否已经统一插桩，不管研发是否已经把业务指标打好，只要请求经过网关，日志里就会有域名、路径、状态码和耗时。
这就是日志报表适合做接口层灭火图的原因。
它站在系统入口看问题。
接口是否有流量。
成功率是否下降。
响应时间是否变慢。
错误码是否集中。
上游服务是否异常。
这些信息已经足够支撑第一层判断。
先把网关日志字段规范好
不要一上来就建报表。
先看日志字段。
日志报表的质量，取决于原始日志是否结构化。
如果网关日志还是一整行纯文本，后面当然也能通过解析规则处理，但建设成本会高很多。更推荐的方式是直接输出 JSON，至少包含这些字段：
时间戳。
域名。
请求路径。
请求方法。
状态码。
请求耗时。
上游状态码。
上游地址。
客户端 IP。
TraceID。
环境。
集群。
字段名不一定要完全一样，但含义要稳定。
比如域名可以叫 domain、host、http_host。接口可以叫 api、request_uri、request。状态码可以叫 status、status_code。
真正重要的是统一。
不要这个网关叫 request_uri，另一个网关叫 url，第三个网关叫 path，最后还要靠人在脑子里翻译。
对接口层灭火图来说，最关键的字段有四类。
第一，接口标识字段。
通常是域名 + 方法 + 路径。
比如 http_host + method + request_uri。
第二，健康计算字段。
至少要有状态码和响应时间。
状态码用来计算错误数和成功率，响应时间用来计算平均耗时、P95、P99。
第三，排障关联字段。
TraceID、上游地址、服务名、实例、集群、环境，这些字段决定后面能不能下钻到 Trace、服务卡片或基础设施对象。
第四，业务影响字段。
渠道、租户、地区、端类型、业务线等字段不一定每个系统都有，但如果有，后续分析影响面会非常有用。
这一步做扎实，后面的日志报表、卡片规则、下钻和 AI 分析都会顺很多。
接口路径要先做归一化
接口层灭火图最容易踩的坑，是动态路径。
比如：
/orders/10001
/orders/10002
/orders/10003
如果直接拿原始路径做维度，系统会生成成千上万个接口对象。
这不是接口层灭火图。
这是高基数灾难。
正确做法是先把动态路径归一化。
比如统一成：
/orders/{order_id}
/users/{user_id}/profile
/products/{sku_id}
如果网关或应用本身能输出 route template，这是最好的。
比如框架里本来就知道这个请求命中了 /orders/{id} 这个路由，就应该把这个模板作为接口字段输出。
如果暂时没有 route template，也可以在日志处理或日志报表的数据加工阶段做映射。
把数字 ID、UUID、手机号、订单号这类动态片段替换掉。
否则接口卡片会迅速膨胀，日志报表会遇到高基数问题，灭火图也会变得不可维护。
接口层灭火图需要的是“业务接口对象”，不是“每一个具体 URL 实例”。
这句话很关键。
创建日志主题：把入口日志收进来
字段确认后，先在 Flashcat 里创建日志主题。
日志主题可以理解为一组结构一致的日志集合。
对于接口层灭火图，最常见的是网关访问日志主题。
比如：
nginx-access。
api-gateway-access。
ingress-access。
spring-cloud-gateway-access。
日志可以来自 Elasticsearch、Doris、ClickHouse、SLS、CLS、TLS、LTS、OpenSearch、VictoriaLogs 等后端。
主题建好后，要先确认几件事。
时间字段是否正确。
如果时间字段不对，报表窗口就会错位。事故发生在 14:00，报表却把数据算到 13:58 或 14:03，后面分析会很别扭。
字段类型是否可聚合。
日志报表的维度字段必须能做聚合。比如在 Elasticsearch 里，一些字段需要 keyword 类型；在云日志服务里，字段可能需要开启统计。
响应时间是否是数值。
如果 request_time 是字符串，后面做平均值、分位值会麻烦。
TraceID 是否能被检索。
这决定从接口异常下钻到日志原文后，能不能继续关联 Trace。
这一步不要省。
很多时候，接口层灭火图不好用，不是灭火图配置错了，而是日志主题里的字段基础不稳。
创建接口维度日志报表
日志主题准备好后，就可以创建日志报表。
入口在：
日志分析 -> 日志报表 -> 报表管理。
报表的核心配置有三类。
第一，维度组合。
接口层建议从最小可用组合开始：
domain + method + api。
如果你的字段名是 http_host + request_method + request_uri，也可以。
不要第一版就把租户、渠道、地区、客户端版本都加进去。
维度越多，基数越高。
接口层灭火图第一版的目标，是把核心接口对象建出来，不是把所有分析维度都放进卡片。
第二，过滤条件。
通常要过滤掉静态资源、健康检查、爬虫、内部探测接口。
比如：
/favicon.ico。
/static/*。
/metrics。
/health。
/ready。
这些路径对系统运行有意义，但不一定适合出现在业务接口层灭火图里。
第三，观测值。
建议直接使用黄金指标模板。
它可以周期性计算请求数、错误数、成功率、响应延迟，支持平均值和分位值。
对接口层来说，这几个指标够用了。
请求数判断流量是否异常。
成功率判断接口是否失败。
响应时间判断接口是否变慢。
错误数判断异常是否集中。
这就是接口层灭火图最需要的健康信号。
时间窗口和延迟计算要贴近日志落库情况
日志报表是周期性计算的。
默认时间窗口通常是 60 秒，也就是每分钟聚合一次。
这个窗口适合大多数接口健康观测。
但如果你的日志落库有延迟，就要配置延迟计算。
比如当前时间是 09:00:10，系统要计算 08:59:00 到 09:00:00 的数据。但如果网关日志要到 09:01:00 才写入日志库，报表就会漏数据。
这时需要让报表多等一会儿再算。
延迟计算不是小细节。
如果不处理，灭火图可能出现两个问题。
第一，接口卡片短暂灰色。
不是接口没流量，而是报表还没算到数据。
第二，成功率和流量被算低。
数据延迟导致窗口内日志不完整，卡片就可能误判。
所以第一版上线后，要观察几个小时。
看报表数据是否稳定。
看卡片是否出现周期性灰色。
看流量曲线是否有规律性断点。
如果有，就优先检查时间窗口和延迟计算。
高基数保护要常态开启
接口维度非常容易产生高基数。
动态路径是一类。
错误地把用户 ID、订单号、session、trace_id 放进维度组合，是另一类。
日志报表文档里专门提到高基数保护：当标签组合数量过多时，系统会丢弃超出部分的日志记录，防止数据库和计算资源被拖垮。
这不是可选项。
接口层日志报表建议常态开启高基数保护。
但更重要的是从设计上避免高基数。
不要把 trace_id 放进报表维度。
不要把 user_id 放进接口卡片路径。
不要把完整 URL query string 当成接口字段。
不要把订单号、手机号、UUID 当成接口层标签。
这些字段适合排查时在日志里检索，不适合作为持续聚合维度。
日志报表应该聚合稳定对象。
灭火图应该展示稳定对象。
这两个原则保持一致，接口层才会长期可维护。
用日志报表生成接口卡片
日志报表稳定后，就可以在灭火图里创建卡片规则。
卡片规则的数据来源选择日志分析或日志报表。
筛选条件用来选出需要生成卡片的接口维度。
卡片路径建议和系统分层保持一致。
比如：
接口 -> 电商系统 -> $domain -> $method $api
如果业务系统很多，也可以加一层业务线或系统名：
接口 -> $system -> $domain -> $method $api
但不要把路径设计得太深。
值班人要能在首页快速看懂影响面。
卡片名称建议使用接口的业务表达。
如果第一版只能用 $method $api，也可以先跑起来。
后续再通过卡片重命名或字段映射，把关键接口改成更容易理解的名字。
比如：
POST /api/order/create 可以显示为“下单接口”。
POST /api/payment/callback 可以显示为“支付回调”。
POST /api/login 可以显示为“登录接口”。
机器字段适合生成，业务名称适合值班。
两者最好兼顾。
接口卡片的健康指标怎么配
接口卡片不要塞太多指标。
第一版建议三类。
请求量。
它回答“这个接口有没有流量”。
对于核心接口，流量突然归零本身就是异常。
成功率。
它回答“这个接口是不是在失败”。
通常可以用 2xx / 3xx 作为成功，4xx / 5xx 是否都算错误，要结合业务判断。比如有些 4xx 是用户参数错误，不一定代表系统故障；但如果 4xx 突然激增，也可能说明前端发布或接口兼容出了问题。
响应时间。
它回答“这个接口是不是变慢”。
建议至少看 P95 或 P99，而不是只看平均值。平均值会掩盖长尾问题。
异常条件也要保守。
比如成功率低于 95% 飘红，P99 超过 3 秒飘红，请求量低于历史基线飘红。
但不要把所有接口套同一个阈值。
低频接口和高频接口不一样。
查询接口和支付接口不一样。
同步接口和异步回调不一样。
内部接口和用户入口不一样。
第一版可以先用统一规则跑起来。
跑几天后，再对核心接口设置更精细的阈值。
下钻要先打通日志原文
接口卡片生成后，第一条下钻应该是日志原文。
从卡片进入日志检索时，要自动带上时间范围、域名、方法、接口路径。
比如卡片标签里有：
domain=mall.example.com
method=POST
api=/orders/{id}
下钻到日志时，查询条件应该自动注入这些值。
用户不应该再手工复制接口路径去搜。
这一步看似简单，但它决定灭火图是否真的能进入故障现场。
接口卡片飘红后，值班人第一反应应该是点进去看日志，而不是重新打开日志系统从头构造查询。
日志下钻里还要保留 TraceID。
如果日志原文里有 trace_id，就可以从具体错误日志继续跳到 Trace。
这条链路很自然：
接口卡片飘红。
下钻到接口相关日志。
找到典型错误或慢请求。
拿 trace_id 查看调用链。
定位慢 Span 或异常下游。
这就是从 Logs 到 Traces 的排障路径。
再补 Trace、服务卡片和事件下钻
日志下钻打通后，再补其他路径。
第一，Trace 下钻。
如果日志报表维度里能关联 service、operation，或者日志原文里有 trace_id，就应该配置到链路分析的跳转。
接口卡片不一定总能直接定位到单条 Trace，但它至少应该能带着接口、时间范围进入 Trace 查询。
第二，服务卡片下钻。
接口通常由某个后端服务承接。
如果网关日志里有 upstream、service 或 route 信息，可以把接口卡片和对应服务卡片关联起来。
当接口飘红时，值班人可以从接口层进入微服务层，看是不是承接服务也飘红。
第三，事件下钻。
接口异常经常和发布、配置变更、网关规则调整、限流策略变更有关。
如果事件墙已经接入发布和变更事件，接口卡片应该能进入同一时间范围的事件视图。
第四，仪表盘下钻。
一些核心接口可能有专门的大盘，比如支付成功率、下单漏斗、网关 upstream 状态。
这类大盘也可以挂到卡片上，但它应该是补充，不应该取代日志和 Trace 下钻。
接口层灭火图的重点不是展示更多图。
重点是从异常对象出发，沿着正确路径找到证据。
如何用 FlashAI 辅助生成报表和卡片
如果日志字段比较规范，FlashAI 可以帮助加速建设。
比如在日志主题已经创建后，可以先让 FlashAI 分析日志字段：
请分析日志主题 nginx-access 的日志，识别适合生成接口维度报表的字段组合，
重点关注 domain、method、api、status_code、request_time、trace_id。
请先给出建议，不要直接创建。
确认字段后，再让它生成报表：
请基于日志主题 nginx-access 创建接口维度日志报表，
维度为 domain + method + api，
使用黄金指标模板计算请求数、错误数、成功率和 P99 响应时间，
过滤静态资源、健康检查和 metrics 接口。
报表跑稳定后，再生成卡片规则：
请基于 nginx-access 的接口维度报表，
在 spacex 空间灭火图中创建接口层卡片规则，
卡片路径为 接口 -> 电商系统 -> $domain -> $method $api，
并为卡片配置请求数、成功率、P99 响应时间三个健康指标。
最后再补下钻：
请为空间 spacex 中接口层卡片创建日志下钻规则，
从卡片标签 domain、method、api 注入到 nginx-access 日志查询条件中。
AI 的价值不是替你做决定。
它适合帮你分析字段、生成初稿、批量配置。
但接口维度、过滤规则、阈值和业务命名，仍然要由熟悉系统的人确认。
验收接口层灭火图，看这六件事
接口层灭火图建好后，不要只看有没有卡片。
要按故障现场验收。
第一，核心接口是否完整。
下单、支付、登录、查询、回调、退款、库存扣减这些关键入口是否都有卡片。
第二，是否有噪音接口。
静态资源、健康检查、无意义内部接口、动态 URL 是否混进来了。
第三，红绿是否可信。
过去几天真实异常时，卡片有没有飘红。正常时，是否长期保持绿色。
第四，下钻是否准确。
从卡片进入日志时，是否自动带上时间范围和接口字段。查询结果是否只包含该接口相关日志。
第五，是否能继续串 Trace。
日志中是否有 trace_id。典型错误日志能否继续跳到对应调用链。
第六，告警是否能直接回到接口卡片。
接口卡片飘红后，告警消息里是否包含接口名、异常指标、趋势截图和灭火图入口。
这些都通过了，接口层灭火图才算进入可用状态。
否则它只是生成了一批卡片。
最后要让入口故障更早被看见
日志报表生成接口层灭火图的价值，不是把日志换个页面展示。
它真正解决的是故障入口问题。
过去，接口异常可能是这样被发现的：
用户投诉。
客服反馈。
业务群里有人说下不了单。
SRE 再去网关日志里搜。
研发再去查 Trace。
这条链路太慢。
接口层灭火图应该把它变成：
接口卡片飘红。
看到哪个入口受影响。
从卡片下钻到日志原文。
用 TraceID 继续进入调用链。
关联服务卡片、事件和数据库分析。
必要时触发 FlashAI 做初步根因分析。
这才是日志报表的真正价值。
它不是报表。
它是把入口日志变成系统健康对象的机制。
如果你的网关日志已经接入 Flashcat，但还只是用来检索，下一步就应该选一个核心系统，把接口维度报表跑起来，再生成接口层灭火图。
先覆盖 20 个最关键接口。
让它们能看流量、成功率、P99，能飘红，能下钻日志和 Trace。
只要这条路径跑通，日志就不再只是事故后的搜索框，而会变成故障发现的第一入口。
