Spring Boot 集成 CAT 监控：分布式链路追踪与性能监控实战

1. 为什么我要把 CAT 监控塞进 Spring Boot 项目

做后端开发的人都有一个共同的痛点：线上服务出了问题，日志翻半天翻不出所以然，等用户投诉到客服那边才知道接口挂了。尤其是微服务架构铺开之后，一个请求跨了七八个服务，每个服务各自打日志，排查一个问题跟破案一样。我所在的团队维护着一套中等规模的 Spring Boot 服务集群，大概二十多个应用实例，之前一直靠 ELK 加自定义埋点撑着，能用，但每次排查跨服务调用链路的时候，还是得手动去拼日志时间线，效率很低。

后来接触到CAT（Central Application Tracking）这套实时监控系统，它最初是美团点评内部孵化并开源出来的，主打分布式链路追踪、应用性能监控和业务指标采集。跟市面上其他监控方案比，CAT 最大的特点是它把调用链、异常、心跳、业务指标这几样东西统一在一个模型里，客户端埋点轻量，服务端聚合能力强，而且对 Java 生态的适配非常成熟。说白了，你只要在 Spring Boot 项目里引一个 starter，配几行连接信息，就能自动把 HTTP 请求、数据库调用、缓存操作、RPC 调用的耗时和成功率全部上报上去，然后在 CAT 的控制台上看到实时的调用链路拓扑和性能大盘。

这篇文章要聊的就是怎么把 CAT 监控集成到一个标准的 Spring Boot 项目里。我会从整体设计思路讲起，然后拆解核心配置和埋点方式，接着给出完整的实操步骤和参数说明，最后把我踩过的坑和排查经验整理出来。适合已经有 Spring Boot 基础、想给项目加上监控能力的后端开发同学，也适合正在做技术选型、想了解 CAT 到底能干什么的架构方向的朋友。文章里涉及的所有项目名称、服务名、地址都是虚构的，你按自己的实际情况替换就行。

2. 集成方案的整体设计与选型考量

2.1 为什么选 CAT 而不是其他监控方案

监控这个领域可选的方案不少，常见的有 Prometheus 加 Grafana 那一套、SkyWalking、Zipkin、还有商业化的 APM 产品。我在选型的时候主要对比了 CAT、SkyWalking 和 Prometheus 三个方向，最后选 CAT 的原因有这么几个。

第一是实时性。CAT 的服务端是消费端实时聚合的，客户端上报之后基本秒级就能在控制台看到数据，而 Prometheus 那套是拉模式，配合 Grafana 看板刷新有间隔，排查突发问题的时候不够快。第二是调用链的完整性。CAT 的 MessageTree 模型天然支持跨服务传递上下文，一个请求从网关进来，经过服务 A、服务 B、服务 C，整条链路的耗时和状态都能串起来，这个能力对微服务排查太重要了。第三是埋点成本低。CAT 提供了大量的自动埋点组件，Spring Boot 项目引了 starter 之后，HTTP 请求、JDBC、Redis、MyBatis 这些常用组件的埋点基本不用写代码，配置一下就行。

SkyWalking 也很强，尤其是它的无侵入探针模式，但那个方案对 JVM 参数的依赖比较重，而且我们团队之前有过探针版本和 JDK 版本不兼容的惨痛经历，所以这次倾向于客户端 SDK 显式集成的方案，可控性更强。Prometheus 更适合做指标监控和告警，调用链追踪不是它的强项，所以最终定位是 CAT 做链路和性能监控，Prometheus 继续做基础资源指标，两者互补。

2.2 集成架构的分层设计

整个集成方案我分成了三层来设计，这样职责清晰，后续维护也方便。

第一层是依赖层。在 Maven 的 pom 文件里引入 CAT 的客户端依赖，这里要注意版本匹配问题。CAT 客户端和服务端的版本最好保持一致，跨大版本可能会有协议不兼容的情况。我用的是一套比较稳定的版本组合，客户端和服务端都是同一个版本号。

第二层是配置层。CAT 客户端的配置主要分两部分，一部分是连接服务端的基础配置，比如服务端地址、应用名称，这些放在 application 配置文件里；另一部分是埋点相关的配置，比如哪些包需要被拦截、哪些 URL 需要被监控，这些可以通过注解或者配置文件来控制。

第三层是埋点层。这一层是业务代码真正和 CAT 打交道的地方。自动埋点覆盖了大部分场景，但有些业务关键路径需要手动埋点，比如核心的下单流程、支付回调，这些需要显式地打 Transaction 和 Event，才能在 CAT 上看到业务维度的数据。

这样分层的好处是，依赖和配置的改动不影响业务代码，业务代码里的埋点也可以按需增删，不会牵一发动全身。

2.3 需要提前想清楚的几个问题

在动手之前，有几个问题必须先想清楚，不然集成到一半会返工。

服务端部署在哪里。CAT 服务端需要独立部署，它本身是个 Java Web 应用，依赖 MySQL 存储配置和报表数据。如果团队还没有 CAT 服务端，得先把它搭起来。我假设你已经有了一个可用的 CAT 服务端，地址类似http://cat-server.internal:8080这种。

应用名称怎么定。CAT 里每个应用有一个唯一的 app name，这个名称会出现在所有报表和调用链里。命名规范建议统一，比如用项目名-模块名的格式，避免出现test、demo这种无意义的名字，不然报表里一堆 test 根本分不清谁是谁。

采样率怎么设。CAT 客户端默认是全量上报，高并发场景下对网络和服务端压力不小。如果 QPS 很高，需要配置采样率，比如只上报 10% 的请求。但采样率设太低又会导致问题排查时找不到对应的调用链，这个平衡要根据实际流量来定。

和现有日志系统的关系。CAT 不是用来替代日志的，它是日志的补充。CAT 告诉你哪个接口慢了、哪个调用失败了，具体为什么失败还得去看日志。所以集成 CAT 的同时，日志规范也要跟上，最好在日志里把 CAT 的 traceId 打出来，这样两边能关联上。

3. 核心配置与埋点方式的细节拆解

3.1 Maven 依赖的引入与版本匹配

CAT 的客户端依赖主要是一个cat-client包，Spring Boot 项目里通常还会引入一个整合包来简化配置。依赖的引入方式有两种，一种是通过 Maven 中央仓库拉取，另一种是公司内部私服。不管哪种方式，核心是版本要对齐。

<dependency> <groupId>com.dianping.cat</groupId> <artifactId>cat-client</artifactId> <version>3.0.0</version> </dependency>

这里有个细节要注意，CAT 客户端的版本号和服务端的版本号最好一致。我曾经遇到过客户端 3.0 配服务端 2.0 的情况，结果上报的数据服务端解析不了，控制台上什么都看不到，排查了半天才发现是版本问题。所以引入依赖之前，先确认服务端的版本，然后客户端用同样的版本。

另外，如果项目里用了 Spring Boot 的 starter 机制，可以找找有没有对应的 cat-spring-boot-starter，有的话配置会更简洁。但如果没有官方 starter，手动配置也完全没问题，CAT 客户端的初始化逻辑本身就不复杂。

3.2 客户端核心配置项详解

CAT 客户端的配置主要集中在一个叫client.xml的文件里，这个文件需要放在 classpath 下，通常是src/main/resources/META-INF/cat/client.xml。这个路径是 CAT 客户端默认查找配置的位置，放错了就读不到。

<?xml version="1.0" encoding="utf-8"?> <config mode="client"> <servers> <server ip="10.0.0.1" port="2280" http-port="8080"/> <server ip="10.0.0.2" port="2280" http-port="8080"/> </servers> </config>

这里的ip和port是 CAT 服务端的地址，2280是服务端接收上报数据的默认端口，http-port是控制台访问端口。配置多个 server 是为了高可用，客户端会轮询上报，一个挂了会自动切到另一个。

除了client.xml，应用名称的配置在app.properties里，这个文件同样放在META-INF/cat/目录下。

app.name=order-service

这个app.name就是前面说的应用唯一标识，一定要起得有意义。我见过有人直接写springboot-app，结果三个项目都叫这个名字，报表数据全混在一起了，根本没法看。

3.3 自动埋点的覆盖范围与原理

CAT 客户端的自动埋点能力是它的一大卖点。在 Spring Boot 项目里，只要依赖引入正确，以下几类操作会自动被监控到。

HTTP 请求。通过 Servlet Filter 拦截所有进入应用的 HTTP 请求，记录 URL、响应时间、状态码、请求参数大小等信息。这个 Filter 是 CAT 客户端自带的，不需要手动注册，Spring Boot 启动时会自动装配。

数据库调用。通过 JDBC 驱动层的拦截，记录每条 SQL 的执行时间、是否成功、慢 SQL 等。这里要注意，CAT 对连接池有要求，如果用 Druid 或者 HikariCP，需要确认 CAT 的拦截器能正确挂载。我实测下来 HikariCP 兼容性最好，Druid 需要额外配置。

缓存操作。对 Redis 的调用会被自动拦截，记录命令类型、耗时、key 的数量等。但要注意，CAT 默认只记录命令级别的信息，不记录具体的 key 值，这是出于安全和性能的考虑。

RPC 调用。如果项目里用了 Dubbo、Feign 这类 RPC 框架，CAT 也有对应的拦截器，能自动把调用链串起来。Feign 的拦截器需要手动注册一下，这个后面实操部分会讲。

自动埋点的原理说白了就是 AOP 加字节码增强，CAT 客户端在类加载阶段把拦截逻辑织入到目标类里，对业务代码完全透明。这也是为什么引入依赖之后基本不用改代码就能看到数据的原因。

3.4 手动埋点的适用场景与 API 用法

自动埋点虽然方便，但有些业务场景它覆盖不到，这时候就需要手动埋点。典型的需要手动埋点的场景有这么几个。

核心业务链路。比如下单流程，从参数校验、库存扣减、订单创建到支付发起，这一整条链路如果只在 HTTP 层面监控，粒度太粗了，看不出具体哪一步慢。这时候可以在每个关键步骤前后打 Transaction，把耗时拆开。

异步任务。定时任务、消息消费这些不在 HTTP 请求上下文里的操作，自动埋点覆盖不到，需要手动创建 Transaction。

业务指标。比如下单成功率、支付转化率这些业务维度的数据，CAT 提供了 Event 类型的埋点，可以自定义指标名称和数值。

手动埋点的核心 API 是Transaction和Event，用法大概是这样。

Transaction t = Cat.newTransaction("OrderFlow", "createOrder"); try { // 业务逻辑 t.setStatus(Transaction.SUCCESS); } catch (Exception e) { t.setStatus(e); Cat.logError(e); throw e; } finally { t.complete(); }

这里有几个关键点。Transaction的 type 和 name 要起得有意义，type 一般是业务模块名，name 是具体操作名。setStatus用来标记成功或失败，失败的时候把异常传进去，CAT 会自动记录异常堆栈。complete必须放在 finally 里，不然 Transaction 不会结束，调用链上会一直挂着。

注意：手动埋点的 Transaction 一定要保证 complete 被调用，否则会导致内存泄漏。我见过有人把 complete 写在 try 块里，结果异常一抛就跳过了，Transaction 对象一直堆在内存里，最后 OOM。

4. 完整实操流程与关键环节实现

4.1 服务端连通性验证

在集成客户端之前，先确认服务端是通的。最简单的办法是用 curl 或者浏览器访问一下 CAT 控制台的地址，能看到登录页或者首页就说明服务端正常。然后确认 2280 端口是开放的，这个端口是客户端上报数据的通道，如果被防火墙挡了，客户端会一直报连接超时。

telnet cat-server.internal 2280

如果 telnet 不通，先找运维确认网络策略。这一步看起来简单，但我遇到过好几次集成失败最后发现是网络不通的情况，所以建议放在第一步做。

4.2 客户端依赖与配置文件落地

服务端确认没问题之后，开始改项目。第一步是加依赖，前面已经给了 Maven 的配置。加完之后执行一下mvn dependency:tree，确认 cat-client 被正确引入，没有版本冲突。

第二步是创建配置文件。在src/main/resources/META-INF/cat/目录下创建两个文件，一个是client.xml，一个是app.properties。目录不存在的话手动建一下，注意大小写，CAT 客户端对路径是大小写敏感的。

client.xml里填服务端地址，app.properties里填应用名称。这两个文件的内容前面都给了模板，照着改就行。

第三步是确认 Spring Boot 的启动类上不需要加额外注解。CAT 客户端的初始化是通过 SPI 机制自动完成的，只要依赖在 classpath 里，配置文件路径正确，应用启动时就会自动初始化。启动日志里会有一行CAT client initialized之类的输出，看到这行就说明初始化成功了。

4.3 自动埋点效果验证

配置完成之后，启动应用，随便调几个接口，然后去 CAT 控制台看数据。控制台的入口一般在http://cat-server.internal:8080，登录之后找到对应的应用名称，点进去看 Transaction 报表。

如果能看到刚才调用的接口记录，说明自动埋点生效了。这里要注意，CAT 的数据上报有延迟，一般是几秒到十几秒，刚调完接口马上刷新可能看不到，等一会儿再刷。

验证的时候重点看几个东西。一是 Transaction 的 type 和 name 是否符合预期，HTTP 请求的 type 一般是URL，name 是具体的路径。二是看调用链是否完整，点开一条 Transaction，应该能看到它下面的子调用，比如数据库查询、Redis 操作等。三是看有没有异常记录，如果接口报错了，CAT 上应该能看到对应的 Error 报表。

4.4 手动埋点接入核心业务

自动埋点验证通过之后，开始给核心业务加手动埋点。我以订单创建流程为例，讲一下具体的接入方式。

订单创建的主流程大概分四步：参数校验、库存扣减、订单落库、发送消息。这四步里，库存扣减和订单落库是耗时大头，需要重点监控。

public OrderResult createOrder(OrderRequest request) { Transaction t = Cat.newTransaction("Order", "createOrder"); try { // 参数校验 Transaction validateT = Cat.newTransaction("Order", "validate"); try { validate(request); validateT.setStatus(Transaction.SUCCESS); } catch (Exception e) { validateT.setStatus(e); throw e; } finally { validateT.complete(); } // 库存扣减 Transaction stockT = Cat.newTransaction("Order", "deductStock"); try { stockService.deduct(request.getSkuId(), request.getQuantity()); stockT.setStatus(Transaction.SUCCESS); } catch (Exception e) { stockT.setStatus(e); throw e; } finally { stockT.complete(); } // 订单落库 Transaction saveT = Cat.newTransaction("Order", "saveOrder"); try { orderMapper.insert(order); saveT.setStatus(Transaction.SUCCESS); } catch (Exception e) { saveT.setStatus(e); throw e; } finally { saveT.complete(); } t.setStatus(Transaction.SUCCESS); return result; } catch (Exception e) { t.setStatus(e); Cat.logError(e); throw e; } finally { t.complete(); } }

这样埋点之后，CAT 上就能看到createOrder这个 Transaction 下面挂着validate、deductStock、saveOrder三个子 Transaction，每个的耗时一目了然。如果某天库存扣减突然变慢，直接看调用链就能定位到。

4.5 业务指标埋点与告警配置

除了链路监控，CAT 还支持业务指标埋点。比如我想监控下单成功率，可以这样打点。

// 下单成功 Cat.logEvent("Order", "createSuccess"); // 下单失败 Cat.logEvent("Order", "createFail", "ERROR", errorMsg);

logEvent的第一个参数是 type，第二个是 name，第三个是状态，第四个是附加信息。这些 Event 会在 CAT 的 Event 报表里按小时聚合，能看到每个时间段的下单成功和失败次数。

有了这些数据之后，可以在 CAT 控制台上配置告警规则。比如下单失败率超过 5% 就发告警，CAT 支持邮件和 HTTP 回调两种告警方式。告警配置在控制台的告警管理页面，按应用和指标来配，配好之后触发条件就会自动通知。

4.6 与现有日志系统的关联

CAT 的 Transaction 有一个 traceId，这个 ID 在整条调用链上是唯一的。为了把 CAT 和日志关联起来，可以在日志的 MDC 里把 traceId 放进去，这样每条日志都会带上 traceId，排查问题的时候用 traceId 一搜，CAT 的调用链和日志就串起来了。

Transaction t = Cat.getProducer(); String traceId = t.getTraceId(); MDC.put("traceId", traceId);

然后在 logback 的 pattern 里加上%X{traceId}，日志输出就会带上这个 ID。这个技巧在实际排查中非常有用，尤其是跨服务的问题，拿着 traceId 去各个服务的日志里搜，整条链路就清晰了。

5. 常见问题与排查技巧实录

5.1 控制台看不到数据怎么办

这是集成 CAT 最常见的问题，原因可能有这么几种。

网络不通。先确认客户端到服务端 2280 端口是否可达，用 telnet 测一下。如果网络不通，客户端会一直重试，日志里会有连接超时的报错。

应用名称配置错误。检查app.properties里的app.name是否和服务端上注册的应用名称一致。CAT 客户端上报数据时会带上应用名称，如果名称对不上，数据会归到别的应用下面，或者直接丢弃。

配置文件路径错误。确认client.xml和app.properties是否在META-INF/cat/目录下。这个路径是 CAT 客户端硬编码的，放错了就读不到。可以用getResource的方式在代码里验证一下文件是否能被加载到。

版本不匹配。客户端和服务端版本差异过大时，协议可能不兼容。检查两边的版本号，尽量保持一致。

排查的时候可以打开 CAT 客户端的调试日志，在 logback 里把com.dianping.cat的日志级别调到 DEBUG，能看到详细的上报过程和错误信息。

5.2 调用链断裂的排查思路

调用链断裂是指一个请求跨了多个服务，但 CAT 上只看到其中一部分，中间断了。这个问题通常出在上下文传递上。

CAT 的调用链依赖一个叫MessageTree的上下文对象，这个对象在跨服务调用时需要显式传递。HTTP 调用的话，CAT 会自动把上下文放到请求头里，服务端再从请求头里取出来。但如果用的是自定义的 RPC 框架，或者异步线程池，上下文就可能丢失。

排查的时候先确认跨服务调用的方式。如果是 HTTP，检查请求头里有没有CAT_ROOT和CAT_CHILD这两个头。如果是 RPC，检查框架的拦截器有没有正确传递上下文。如果是异步线程，需要用Cat.getManager().getThreadLocalMessageTree()手动传递上下文。

MessageTree tree = Cat.getManager().getThreadLocalMessageTree(); executor.submit(() -> { Cat.getManager().setThreadLocalMessageTree(tree); // 异步逻辑 });

5.3 高并发下的性能影响与调优

CAT 客户端本身对性能的影响很小，但在极高并发下，上报数据的网络开销和序列化开销还是需要考虑的。我实测下来，单机 QPS 在几千以内，CAT 客户端带来的额外延迟在毫秒级别，基本可以忽略。但如果 QPS 上万，就需要做一些调优。

开启采样。在client.xml里可以配置采样率，比如只上报 10% 的请求。采样率的配置项是sample，值是一个小数，0.1 表示 10%。

<config mode="client"> <sample>0.1</sample> <servers> <server ip="10.0.0.1" port="2280" http-port="8080"/> </servers> </config>

调整上报线程数。CAT 客户端默认用一个后台线程池来上报数据，如果队列积压严重，可以适当增加线程数。这个配置在client.xml里通过pool-size来设置。

关闭不必要的埋点。如果某些组件的埋点对业务价值不大，可以在配置里关掉，减少开销。比如不需要监控 Redis 的话，可以把 Redis 的拦截器禁用。

5.4 常见问题速查表

5.5 几个容易忽略的实操心得

第一，Transaction 的嵌套不要太深。CAT 对调用链的深度有限制，嵌套太深的话，超出部分会被截断。一般建议嵌套不超过 10 层，业务埋点尽量扁平化。

第二，Event 的 type 和 name 要规划好。Event 是按 type 和 name 聚合的，如果命名太随意，报表里会有一堆零散的指标，根本没法看。建议提前规划好命名规范，比如 type 用业务模块名，name 用具体动作名。

第三，CAT 的报表数据有保留期限。默认情况下，CAT 的原始数据保留 7 天，聚合数据保留更久。如果需要长期留存，要配置数据归档策略，或者定期导出报表。

第四，客户端初始化失败不会阻塞应用启动。CAT 客户端初始化失败时，默认只是打日志，不会让应用启动失败。这个设计有好有坏，好处是监控挂了不影响业务，坏处是如果没注意日志，可能监控一直没生效都不知道。建议在应用启动后加一个健康检查，确认 CAT 客户端状态正常。

第五，多环境要区分应用名。开发、测试、生产环境的 CAT 应用名最好加上环境后缀，比如order-service-dev、order-service-prod，不然各环境的数据混在一起，报表就没法看了。

6. 监控数据怎么用起来

集成完成只是第一步，数据上报上去之后，关键是怎么用。我平时主要看几个报表。

Transaction 报表。看接口的响应时间分布、成功率、QPS。重点关注 P99 和 P95 的耗时，这两个指标能反映长尾请求的情况。如果 P99 突然飙升，说明有慢请求，点进去看调用链定位。

Event 报表。看业务指标的趋势，比如下单量、支付成功率。这些指标可以和业务数据做交叉验证，如果 CAT 上的下单量和数据库里的订单量对不上，说明埋点有问题。

Problem 报表。CAT 会自动把异常和慢请求归到 Problem 报表里，这个报表是排查问题的入口。每天上班第一件事就是看 Problem 报表，有没有新增的异常，有没有突然变慢的接口。

调用链拓扑。CAT 能根据调用关系自动生成服务依赖拓扑图，这个图对理解系统架构很有帮助。新同学入职的时候，让他先看这个图，比看文档快多了。

监控这个东西，集成只是开始，真正产生价值是在日常的排查和优化中。我自己的习惯是每周花半小时过一遍 CAT 的报表，看看有没有异常趋势，提前发现潜在问题。这个习惯帮我避免了好几次线上故障，比出了问题再救火强多了。

最后分享一个小技巧：CAT 的 Transaction 支持打标签，可以在埋点的时候把一些关键业务参数作为标签打上去，比如订单 ID、用户 ID。这样在排查具体某个订单的问题时，可以直接用标签搜索，快速定位到对应的调用链。这个功能在排查客诉问题的时候特别好用，不用再大海捞针一样翻日志了。