CAT Java客户端完全指南Transaction、Event、Metric埋点API详解【免费下载链接】catCAT 作为服务端项目基础组件提供了 Java, C/C, Node.js, Python, Go 等多语言客户端已经在美团点评的基础架构中间件框架MVC框架RPC框架数据库框架缓存框架等消息队列配置系统等深度集成为美团点评各业务线提供系统丰富的性能指标、健康状况、实时告警等。项目地址: https://gitcode.com/gh_mirrors/ca/catCAT Java客户端是接入 CAT 实时监控平台的核心入口。本文面向新手用最少代码讲清三大埋点 API——Cat.newTransaction()、Cat.logEvent()、Cat.logMetricForCount()带你快速完成应用的性能指标、健康状况与实时告警接入。一、动手前Java 客户端安装与初始化CAT 新版 Java 客户端位于 lib/java/ 模块支持 JDK 1.6Maven 引入即可dependency groupIdcom.dianping.cat/groupId artifactIdcat-client/artifactId version${cat.version}/version /dependency初始化只需两件事无需手动调用客户端是懒加载的在项目中创建src/main/resources/META-INF/app.properties内容为一行app.name{你的应用名}仅允许英文、数字、下划线、中划线配置 CAT 服务端地址文件$CAT_HOME/client.xml默认路径/data/appdatas/cat/client.xml声明各消费机 IP 与端口TCP 固定 2280。详细步骤可参考 lib/java/README.md。客户端核心入口类是 Cat.java所有静态 API 都由它代理到内部的MessageProducer。二、先看懂 CAT 消息模型Transaction、Event、Metric、HeartbeatCAT 定义了四种消息模型选对模型是埋点的第一步消息类型记录什么典型场景Transaction一段代码的执行时间可失败URL 请求、SQL 查询、RPC/HTTP 调用Event某个时刻发生的次数异常出现、用户注册、业务成功/失败Metric某个指标的变化值销售额、库存、耗时累计Heartbeat分钟级 CPU、IO 等客户端自动上报机器健康状况 判断口诀会失败、有时长 → Transaction只发生、瞬时 → Event是数值 → Metric。所有消息会构建成一棵消息树只有 Transaction 可以作为树节点其余消息都是叶子见 Transaction.java 注释。三、Transaction 埋点追踪耗时与成功率Transaction 是 CAT 最核心的埋点。官方推荐用try-catch-finally包裹防止忘记结束Transaction t Cat.newTransaction(URL, pageName); try { yourBusiness(); t.setStatus(Transaction.SUCCESS); } catch (Exception e) { t.setStatus(e); Cat.logError(e); } finally { t.complete(); }常用修饰 API定义见 Transaction.javaaddData(kv)补充业务维度多次调用自动用拼接setStatus()0表示成功其他值为错误码complete()结束事务必须调用否则会产生损坏的消息树和内存泄漏setDurationInMillis()/setDurationStart()修正耗时统计起点二者同用无意义。type 和 name 怎么定官方给了一张埋点决策图已有合适的 type 就复用name 不要泛滥先查报表核实Message.java 列出了 URL、Service、SQL、Cache、Error 等标准类型如果一段耗时已经结束如批处理回溯可直接用 Cat.newCompletedTransactionWithDuration() 一步到位无需手动 complete。四、Event 埋点记录瞬时事件与异常Event 用于某一时刻发生了某事入口是 Cat.logEvent()// 最简单的成功事件 Cat.logEvent(URL.Server, serverIp); // 带状态与业务数据 Cat.logEvent(URL.Server, serverIp, failed, ip10.1.1.1);异常埋点三件套API用途Cat.logError(e)记录异常堆栈type 按Error/RuntimeException/Exception自动归类Cat.logError(msg, e)在堆栈顶部追加自定义错误信息Cat.logErrorWithCategory()覆盖默认的错误分类名便于自定义聚合维度try { 1 / 0; } catch (Exception e) { Cat.logError(e); }五、Metric 埋点计数与耗时聚合上报Metric 不关心单次调用只关心数值统计由 MetricTagAggregator 每秒在本地聚合一次后上报——同一秒内调用 3 次计数只会上报一条汇总值吞吐压力极小// 计数型Counter累加求和 Cat.logMetricForCount(metric.key); Cat.logMetricForCount(metric.key, 3); // 耗时型Duration上报均值 Cat.logMetricForDuration(metric.key, 5);API 定义见 Cat.logMetricForCount() 与 Cat.logMetricForDuration()。两者还支持传入MapString, String tags按维度拆分聚合。在 CAT 报表中你会看到类似下面这样的分钟级 Value 曲线含基线值对比六、埋点避坑清单忘记complete()→ 消息树损坏 内存泄漏务必放finally块同一事务里既设duration又设durationStart→ 无意义二选一即可type/name 泛滥→ 监控报表维度爆炸先查现有报表再新增高频路径逐条上报→ 用 Metric 或Cat.logBatchEvent()批量聚合降低网络开销需要关闭监控→ 设置环境变量CAT_ENABLEDfalse或调用 Cat.disable()。七、与日志框架和 Web 的零成本集成除了手动埋点CAT 提供了开箱即用的集成方案位于 integration/ 目录日志联动logback 场景配置 CatLogbackAppenderERROR 日志自动转为 Cat Eventlog4j / log4j2 也有对应 AppenderURL 监控传统 Web 应用注册 CatFilter见 integration/URL/CatFilter.javaSpring Boot 应用则引入 integration/spring-boot/CatFilterConfigure.javaAOP 埋点用注解替代侵入式代码参考 integration/spring-aop/。客户端采集的数据经 TCP 发往消费机后即可在管理端看到全景监控总结需求API关键点调用链路耗时Cat.newTransaction(type, name)try-finally complete()业务事件/异常Cat.logEvent()/Cat.logError()name 带业务维度数值统计Cat.logMetricForCount/Duration()每秒本地聚合支持 tags掌握以上三大 API 后你的 Java 应用就具备了从链路追踪 → 异常定位 → 指标告警的完整可观测能力。更多细节可查阅 lib/java/README.zh-CN.md。【免费下载链接】catCAT 作为服务端项目基础组件提供了 Java, C/C, Node.js, Python, Go 等多语言客户端已经在美团点评的基础架构中间件框架MVC框架RPC框架数据库框架缓存框架等消息队列配置系统等深度集成为美团点评各业务线提供系统丰富的性能指标、健康状况、实时告警等。项目地址: https://gitcode.com/gh_mirrors/ca/cat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CAT Java客户端完全指南：Transaction、Event、Metric埋点API详解
CAT Java客户端完全指南Transaction、Event、Metric埋点API详解【免费下载链接】catCAT 作为服务端项目基础组件提供了 Java, C/C, Node.js, Python, Go 等多语言客户端已经在美团点评的基础架构中间件框架MVC框架RPC框架数据库框架缓存框架等消息队列配置系统等深度集成为美团点评各业务线提供系统丰富的性能指标、健康状况、实时告警等。项目地址: https://gitcode.com/gh_mirrors/ca/catCAT Java客户端是接入 CAT 实时监控平台的核心入口。本文面向新手用最少代码讲清三大埋点 API——Cat.newTransaction()、Cat.logEvent()、Cat.logMetricForCount()带你快速完成应用的性能指标、健康状况与实时告警接入。一、动手前Java 客户端安装与初始化CAT 新版 Java 客户端位于 lib/java/ 模块支持 JDK 1.6Maven 引入即可dependency groupIdcom.dianping.cat/groupId artifactIdcat-client/artifactId version${cat.version}/version /dependency初始化只需两件事无需手动调用客户端是懒加载的在项目中创建src/main/resources/META-INF/app.properties内容为一行app.name{你的应用名}仅允许英文、数字、下划线、中划线配置 CAT 服务端地址文件$CAT_HOME/client.xml默认路径/data/appdatas/cat/client.xml声明各消费机 IP 与端口TCP 固定 2280。详细步骤可参考 lib/java/README.md。客户端核心入口类是 Cat.java所有静态 API 都由它代理到内部的MessageProducer。二、先看懂 CAT 消息模型Transaction、Event、Metric、HeartbeatCAT 定义了四种消息模型选对模型是埋点的第一步消息类型记录什么典型场景Transaction一段代码的执行时间可失败URL 请求、SQL 查询、RPC/HTTP 调用Event某个时刻发生的次数异常出现、用户注册、业务成功/失败Metric某个指标的变化值销售额、库存、耗时累计Heartbeat分钟级 CPU、IO 等客户端自动上报机器健康状况 判断口诀会失败、有时长 → Transaction只发生、瞬时 → Event是数值 → Metric。所有消息会构建成一棵消息树只有 Transaction 可以作为树节点其余消息都是叶子见 Transaction.java 注释。三、Transaction 埋点追踪耗时与成功率Transaction 是 CAT 最核心的埋点。官方推荐用try-catch-finally包裹防止忘记结束Transaction t Cat.newTransaction(URL, pageName); try { yourBusiness(); t.setStatus(Transaction.SUCCESS); } catch (Exception e) { t.setStatus(e); Cat.logError(e); } finally { t.complete(); }常用修饰 API定义见 Transaction.javaaddData(kv)补充业务维度多次调用自动用拼接setStatus()0表示成功其他值为错误码complete()结束事务必须调用否则会产生损坏的消息树和内存泄漏setDurationInMillis()/setDurationStart()修正耗时统计起点二者同用无意义。type 和 name 怎么定官方给了一张埋点决策图已有合适的 type 就复用name 不要泛滥先查报表核实Message.java 列出了 URL、Service、SQL、Cache、Error 等标准类型如果一段耗时已经结束如批处理回溯可直接用 Cat.newCompletedTransactionWithDuration() 一步到位无需手动 complete。四、Event 埋点记录瞬时事件与异常Event 用于某一时刻发生了某事入口是 Cat.logEvent()// 最简单的成功事件 Cat.logEvent(URL.Server, serverIp); // 带状态与业务数据 Cat.logEvent(URL.Server, serverIp, failed, ip10.1.1.1);异常埋点三件套API用途Cat.logError(e)记录异常堆栈type 按Error/RuntimeException/Exception自动归类Cat.logError(msg, e)在堆栈顶部追加自定义错误信息Cat.logErrorWithCategory()覆盖默认的错误分类名便于自定义聚合维度try { 1 / 0; } catch (Exception e) { Cat.logError(e); }五、Metric 埋点计数与耗时聚合上报Metric 不关心单次调用只关心数值统计由 MetricTagAggregator 每秒在本地聚合一次后上报——同一秒内调用 3 次计数只会上报一条汇总值吞吐压力极小// 计数型Counter累加求和 Cat.logMetricForCount(metric.key); Cat.logMetricForCount(metric.key, 3); // 耗时型Duration上报均值 Cat.logMetricForDuration(metric.key, 5);API 定义见 Cat.logMetricForCount() 与 Cat.logMetricForDuration()。两者还支持传入MapString, String tags按维度拆分聚合。在 CAT 报表中你会看到类似下面这样的分钟级 Value 曲线含基线值对比六、埋点避坑清单忘记complete()→ 消息树损坏 内存泄漏务必放finally块同一事务里既设duration又设durationStart→ 无意义二选一即可type/name 泛滥→ 监控报表维度爆炸先查现有报表再新增高频路径逐条上报→ 用 Metric 或Cat.logBatchEvent()批量聚合降低网络开销需要关闭监控→ 设置环境变量CAT_ENABLEDfalse或调用 Cat.disable()。七、与日志框架和 Web 的零成本集成除了手动埋点CAT 提供了开箱即用的集成方案位于 integration/ 目录日志联动logback 场景配置 CatLogbackAppenderERROR 日志自动转为 Cat Eventlog4j / log4j2 也有对应 AppenderURL 监控传统 Web 应用注册 CatFilter见 integration/URL/CatFilter.javaSpring Boot 应用则引入 integration/spring-boot/CatFilterConfigure.javaAOP 埋点用注解替代侵入式代码参考 integration/spring-aop/。客户端采集的数据经 TCP 发往消费机后即可在管理端看到全景监控总结需求API关键点调用链路耗时Cat.newTransaction(type, name)try-finally complete()业务事件/异常Cat.logEvent()/Cat.logError()name 带业务维度数值统计Cat.logMetricForCount/Duration()每秒本地聚合支持 tags掌握以上三大 API 后你的 Java 应用就具备了从链路追踪 → 异常定位 → 指标告警的完整可观测能力。更多细节可查阅 lib/java/README.zh-CN.md。【免费下载链接】catCAT 作为服务端项目基础组件提供了 Java, C/C, Node.js, Python, Go 等多语言客户端已经在美团点评的基础架构中间件框架MVC框架RPC框架数据库框架缓存框架等消息队列配置系统等深度集成为美团点评各业务线提供系统丰富的性能指标、健康状况、实时告警等。项目地址: https://gitcode.com/gh_mirrors/ca/cat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
