一次生产慢请求，我用Pinpoint全链路追踪把2.3s拆到了数据库

一次生产慢请求，我用Pinpoint全链路追踪把2.3s拆到了数据库

【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint

上周排查一个下单接口，用户反馈"偶尔很卡"。我翻了监控、grep 了半屏日志，只看到网关返回 504，具体卡在哪个下游一无所知。给服务挂上 Pinpoint 的 Agent 后，散点图里那条 2.3s 的异常响应被框了出来，点进去才看清真正吃时间的，是订单服务里一次没走索引的查询。全链路追踪在这种场景下的价值，就是把"慢"从一个模糊感觉，变成一张能一路下钻的调用图。

Pinpoint 是什么，为什么值得挂上去

Pinpoint 是一个面向分布式系统的应用性能监控（APM）工具。它的核心是一个 Java Agent，挂在 JVM 上，不需要你改一行代码，就能在关键组件（Tomcat、JDBC、各类 HTTP 客户端、消息队列）的调用前后自动埋点，把每一次请求的处理路径和耗时采集下来。官方给出的默认配置开销约 3%，所以直接挂到生产一般没有压力。

部署：从存储到 Web 的最小命令链

整套系统分四块：HBase 存数据、Collector 收数据、Web 看数据，再加挂在应用上的 Agent。先拉仓库并构建：

git clone https://gitcode.com/gh_mirrors/pi/pinpoint cd pinpoint ./mvnw install -DskipTests=true

起 HBase 并建好表：

cd hbase-x.x.x ./bin/start-hbase.sh ./bin/hbase shell hbase-create.hbase

再分别拉起 Collector 和 Web，两者都靠 Zookeeper 地址互相定位：

java -jar -Dpinpoint.zookeeper.address=localhost pinpoint-collector-boot-x.x.x.jar java -jar -Dpinpoint.zookeeper.address=localhost pinpoint-web-boot-x.x.x.jar

Agent 最小接入命令

应用侧只加一个-javaagent参数，再给 Agent 起个名字、给应用起个名就行。下面用仓库自带的 quickstart 测试应用演示，换成你自己的 jar 同理：

java -jar -javaagent:pinpoint-agent-x.x.x/pinpoint-bootstrap.jar \ -Dpinpoint.agentId=test-agent -Dpinpoint.applicationName=TESTAPP \ your-application.jar

刷新浏览器里的 Web 页面，TESTAPP 就会出现在 Servermap 上，说明链路已经通。

TraceID 如何贯穿前后端日志

请求一进来，Agent 就生成一个 TraceID 和一个 SpanID，可以理解为"这一单"和"这一单里当前这一步"。关键是它们不会被留在内存里就丢掉，而是随每一次跨服务调用（HTTP 头、RPC 元数据、消息属性）继续往下传，所以下游服务拿到的还是同一个 TraceID。

上面这条调用树，从网关到订单、再到 RocketMQ 的生产消费，整条链都挂在同一个 Transaction 上，靠的就是这个 ID 一路串下来。

落到日志上，Pinpoint 的日志插件（log4j / logback / log4j2）会把当前上下文的 ID 写进 MDC，你只要在 pattern 里加两个占位符，日志就能和调用链对上号：

<PatternLayout pattern="%d [%t] %-5level %logger - %msg PtxId=%X{PtxId} PspanId=%X{PspanId}%n"/>

这样"线上这条报错日志"和"Web 里这条调用栈"能凭 PtxId 直接对上，不用再去人肉拼时间戳。插件源码在 agent-module/plugins/log4j2/。

散点图定位慢请求：框选、下钻、找最慢环节

真正干活的其实就两个动作。

第一步，在目标应用的 Scatter Chart 上，把响应时间偏高的那段框出来。散点的纵轴就是耗时，框一下就能筛出那批慢样本，比在日志里 grep 高效得多。

第二步，从框选结果里挑一条双击，进入调用栈（Call Tree）。整条链按树展开，每一段都标着自己的耗时和 Exec%。我那次的问题，就是订单服务下有一段 SQL 的 Exec% 接近 100%，其余环节都是个位数毫秒——瓶颈一眼看清，接下来要做的只是查这条 SQL 的索引和回表情况。

如果慢还伴随报错，Error Analysis 页能把异常按类型、按时间堆出来，点一条异常直接跳到对应调用栈。思路始终一致：先框，再下钻，再看最慢或最异常的那一段，最后落到 SQL、缓存或代码上给一个具体的优化动作。

进阶：手动埋点与采样率调优

默认插件已覆盖绝大多数中间件，但有些自研异步链路（比如把请求丢进线程池）会断掉 TraceID。这时用 Agent SDK 把线程池包一层，上下文就能续上，示例见 agent-module/agent-sdk/：

ExecutorService exec = TraceExecutors.wrapExecutorService(Executors.newSingleThreadExecutor()); exec.execute(TraceRunnable.wrap(() -> future.complete("done")));

想控制数据量，就调采样率。Agent 配置里profiler.sampling.type=COUNTING时，profiler.sampling.counting.sampling-rate=20表示每 20 个事务采 1 个（约 5%），用-D即可临时覆盖：

-Dprofiler.sampling.counting.sampling-rate=5

高并发服务还可以按 URL 单独设采样，或把低价值的插件用profiler.xxx.enable=false关掉。各插件的开关与版本支持范围，都写在 agent-module/plugins/ 和 doc/modules.md 里，接入前翻一眼能少踩不少坑。

Pinpoint 把一次请求的完整路径画成一张可下钻的调用图，慢在哪里、错在哪里基本都能直接看到。更多部署细节与版本兼容表，见仓库 README 与 doc/modules.md。

【免费下载链接】pinpointAPM, (Application Performance Management) tool for large-scale distributed systems.项目地址: https://gitcode.com/gh_mirrors/pi/pinpoint