可观测性指标监控告警APM后端链路追踪【免费下载链接】catCAT 作为服务端项目基础组件提供了 Java, C/C, Node.js, Python, Go 等多语言客户端已经在美团点评的基础架构中间件框架MVC框架RPC框架数据库框架缓存框架等消息队列配置系统等深度集成为美团点评各业务线提供系统丰富的性能指标、健康状况、实时告警等。项目地址https://gitcode.com/gh_mirrors/ca/cat点击查看免费下载CATCentral Application Tracking是由美团点评开源的分布式监控系统其各语言客户端Java、C/C、Node.js、Python、Go 等在启动并上报埋点数据之前都需要在本地完成一套统一的落地准备创建两个约定目录、放置一份服务端地址配置文件。这篇指南以仓库中的 preparations.zh-CN.md 为骨架结合多语言客户端源码与 Docker/Helm 部署脚本完整讲解 CAT 客户端初始化前必须完成的准备工作以及这些路径约定背后的实现原理。读完本文你将能独立为任意一台业务机器完成 CAT 客户端的前置环境配置并理解 CAT_HOME、client.xml、client_cache.xml 等关键机制的工作方式。准备工作总览三步完成 CAT 客户端本地初始化CAT 客户端在初始化时会读取本地磁盘上的目录与配置文件作为连接服务端的唯一依据。按照官方文档初始化前需要完成三个步骤创建/data/appdatas/cat目录并确保具备读写权限创建/data/applogs/cat目录可选但强烈建议用于存放运行时日志在/data/appdatas/cat下创建client.xml填入 CAT 服务端地址。这三步看似简单却直接决定客户端能否找到服务端、能否持久化路由信息、能否输出可诊断的日志。下面逐项展开。第一步创建 /data/appdatas/cat 目录CAT 将/data/appdatas/cat约定为客户端配置与数据的主目录所有关键文件都存放于此。创建命令如下mkdir -p /data/appdatas/cat创建后务必确认读写权限CAT 客户端进程需要在该目录下读取配置、写入路由缓存文件ls -ld /data/appdatas/cat官方英文文档preparations.md特别强调该目录需要具备读写权限≥ 0644。权限不足时客户端在读取client.xml或写入路由缓存时会出现异常导致无法正常连接服务端。CAT_HOME为什么默认值是 /data/appdatas/cat/data/appdatas/cat并非硬编码在每一个调用点而是通过CAT_HOME环境变量统一管理的。在 Java 客户端中Cat.getCatHome() 的定义为public static String getCatHome() { return Properties.forString().fromEnv().fromSystem().getProperty(CAT_HOME, /data/appdatas/cat/); }也就是说配置查找顺序为环境变量 → 系统属性 → 默认值当环境变量或 JVM 系统属性-DCAT_HOME...未设置时客户端一律回落到/data/appdatas/cat/。这意味着默认部署下只需严格按文档创建/data/appdatas/cat即可若出于目录规划需要可通过CAT_HOME整体迁移配置目录例如将 CAT_HOME 指向/opt/cat则client.xml的查找路径会同步变为/opt/cat/client.xml对标准多机部署建议所有机器保持一致的 CAT_HOME避免配置管理混乱。C 客户端同样遵守这一约定。lib/c/src/ccat/client_config.h 中可以看到// #define DEFAULT_XML_FILE /data/appdatas/cat/client.xml // 通过指定环境变量CAT_HOME来修改此路径 #define DEFAULT_CAT_HOME /data/appdatas/cat/ // #define DEFAULT_DATA_DIR /data/appdatas/cat/由此可以推断C/C 客户端的默认配置路径同样是CAT_HOME环境变量 /data/appdatas/cat/默认值多语言客户端在此处保持了完全一致的约定。第二步创建 /data/appdatas/cat 的兄弟目录 /data/applogs/cat强烈建议/data/applogs/cat是 CAT 客户端运行时日志的存放目录官方文档将其标注为可选但明确说明这对调试将提供很大帮助。mkdir -p /data/applogs/cat同样需要读写权限因为客户端会在该目录下追加写入日志文件。日志文件长什么样cat_client_yyyyMMdd.log从 Java 客户端源码 CatLogger.java 可以确认日志的实际落盘细节private static final String DEFAULT_BASE_DIR /data/applogs/cat; ... private File getFilePath(String path) throws IOException { File file new File(path); String baseDir Properties.forString().fromSystem().fromEnv().getProperty(CAT_HOME, DEFAULT_BASE_DIR); if (baseDir ! null) { file new File(baseDir, path); } return file.getCanonicalFile(); }日志文件按天滚动命名格式为cat_client_yyyyMMdd.log例如cat_client_20260920.log。当连接异常、配置解析失败、上报失败时错误信息都会写入该日志是排查 CAT 客户端问题的一手资料。需要留意的一个细节日志目录的默认值同样取自CAT_HOME属性环境变量CAT_HOME或系统属性缺省时才回落为/data/applogs/cat。如果第一步中自定义了 CAT_HOME日志路径也会随之改变——因此在自定义 CAT_HOME 时应同时确保日志目录有对应权限。第三步创建 client.xml 并填写服务端地址这是准备工作的核心。在/data/appdatas/cat下创建client.xml内容如下?xml version1.0 encodingutf-8? config xmlns:xsihttp://www.w3.org/2001/XMLSchema xsi:noNamespaceSchemaLocationconfig.xsd servers server ipcat server ip address port2280 http-port8080 / /servers /config不要忘记把cat server IP address替换成你自己的服务器地址字段语义与端口约定client.xml 是客户端连接服务端的唯一地址来源其核心字段含义如下字段说明默认值 / 约束servers/serverCAT 服务端节点列表可配置多台做负载均衡与容灾至少一台ip服务端 IP 地址替换为你的 CAT 服务器地址必填portCAT 服务端接收客户端数据的端口默认 2280官方建议不要修改http-portCAT 服务端 Tomcat 的 HTTP 端口默认 8080建议使用默认多台服务端的配置示例如下摘自 lib/java/README.zh-CN.md?xml version1.0 encodingutf-8? config modeclient servers server ip10.1.1.1 port2280 http-port8080/ server ip10.1.1.2 port2280 http-port8080/ server ip10.1.1.3 port2280 http-port8080/ /servers /config官方对端口的约束非常明确2280 是默认的 CAT 服务端接受数据的端口不允许修改http-port 是 Tomcat 启动的端口默认是 8080建议使用默认端口。源码层面同样印证了这一默认值。在 Server.java 中private int port 2280; private int httpPort 8080;服务端 Docker 部署也将 2280 作为对外暴露的接收端口见 docker-compose.yml 中的2280:2280映射。client.xml 在启动流程中的实际作用从源码调用链看client.xml 并不是一个装饰性文件而是客户端初始化的输入源头。ApplicationEnvironment.loadClientConfig 的加载顺序为若client_cache.xml路由缓存存在且未开启 devMode优先读取缓存否则读取client.xml两者都不存在时回退到远程拉取loadRemoteClientConfig请求http://{CAT_HOST}/cat/s/launch。其中CLIENT_FILE client.xml、CACHE_FILE client_cache.xml、配置目录通过Cat.getCatHome()取得见 ApplicationEnvironment.java。加载到的ClientConfig会设置上业务 domain应用标识供后续消息树打点使用。也就是说一份正确的 client.xml 是客户端稳定连上服务端的第一块基石而 client_cache.xml 是客户端在运行时根据服务端下发结果写入的路由缓存文件——若路由出现错误删除 client_cache.xml 后重启服务即可重新拉取见 lib/java/README.zh-CN.md。权限与常见错误确认/data/appdatas/cat/client.xml可读且进程用户具备写入目录权限用于写 client_cache.xml若client.xml缺失客户端会尝试远程拉取路由配置在无法访问服务端的情况下将抛出异常并提示contact cat support team for help见 ApplicationEnvironment.java 对应的源码逻辑若日志目录不存在运行时诊断信息无处落盘排查问题会非常困难因此强烈建议创建/data/applogs/cat。完整的初始化检查清单完成以上三步后可以用下面的清单做一次自检# 1. 配置目录存在且可写 ls -ld /data/appdatas/cat # 2. 日志目录存在且可写建议 ls -ld /data/applogs/cat # 3. 配置文件存在且 IP 已替换 cat /data/appdatas/cat/client.xml # 4.可选确认 CAT_HOME 未做非常规覆盖 echo $CAT_HOME各项就绪后即可进入客户端初始化与打点阶段Java 客户端需在src/main/resources/META-INF/app.properties中配置app.name{appkey}appkey 仅允许英文字母、数字、下划线与中划线Java 版 cat client 现在会自动懒加载无需手动初始化详见 lib/java/README.zh-CN.md。容器化部署中的目录映射在 Docker/Kubernetes 部署场景下同样的目录约定通过挂载或持久卷实现Docker 方式将宿主机的 client.xml 挂载到容器内/data/appdatas/cat/client.xml并暴露 2280 端口参见 docker-compose.ymlKubernetes 方式通过 ConfigMap 生成 client.xml 并挂载至/data/appdatas/cat/client.xml见 Helm 模板 configmap-cat-client-xml.yaml 与 values.yaml。无论以何种方式部署容器内 CAT 客户端读取的仍然是/data/appdatas/cat/client.xml这一约定路径目录准备逻辑与裸机部署完全一致。总结CAT 客户端的初始化准备只有三步创建/data/appdatas/cat、创建/data/applogs/cat强烈建议、配置client.xml。背后是 CAT_HOME 统一管理的路径约定默认/data/appdatas/cat/日志默认/data/applogs/cat、2280/8080 双端口约定以及 client.xml → client_cache.xml → 远程拉取的配置加载链。理解这套约定无论使用 Java、C/C 还是其他语言客户端无论裸机部署还是容器化部署都能快速完成客户端上线并在出现问题时从运行日志与路由缓存入手高效定位。赞分享可观测性指标监控告警APM后端链路追踪【免费下载链接】catCAT 作为服务端项目基础组件提供了 Java, C/C, Node.js, Python, Go 等多语言客户端已经在美团点评的基础架构中间件框架MVC框架RPC框架数据库框架缓存框架等消息队列配置系统等深度集成为美团点评各业务线提供系统丰富的性能指标、健康状况、实时告警等。项目地址https://gitcode.com/gh_mirrors/ca/cat点击查看免费下载相关推荐CAT C 客户端cppcatAPI 完整指南Transaction、Event、Metric 埋点与初始化配置CAT C 客户端cppcatAPI 完整指南Transaction、Event、Metric 埋点与初始化配置 CATCentral Applic可观测性指标监控告警APM后端链路追踪CAT Python 客户端pycat / cat-sdk接入指南安装、初始化与 Transaction / Event / Metric 埋点实战CAT Python 客户端pycat / cat sdk接入指南安装、初始化与 Transaction / Event / Metric 埋点实战 py可观测性指标监控告警APM后端链路追踪CAT C 客户端ccatAPI 完全指南初始化、埋点与消息上报CAT C 客户端ccatAPI 完全指南初始化、埋点与消息上报 导读 本文以 CAT 开源监控系统中 C 语言客户端 ccat 的官方 API 文档可观测性指标监控告警APM后端链路追踪创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考