Pinpoint APM 是韩国 Naver 公司开源的一款分布式应用性能监控工具，核心能力是自动记录跨服务调用链，把一次用户请求在多个微服务之间的流转过程还原出来。它基于 Google Dapper 论文的设计思想，通过 Java Agent 在类加载阶段对字节码做增强，从而在方法入口和出口埋入采集逻辑，业务代码完全不需要改动。采集到的数据经过 Collector 汇总后写入 HBase，最终由 Web UI 提供事务地图、调用栈、响应时间分布等可视化界面。
一、Pinpoint APM 的核心架构与数据流
Pinpoint 的架构可以拆成四个角色：Agent、Collector、Web UI 和 HBase。Agent 以 javaagent 方式挂载到业务 JVM 上，负责在方法调用前后记录 Span 和事件；Collector 接收 Agent 上报的数据并做批量写入；HBase 承担海量调用链数据的持久化，支持按 traceId 快速检索；Web UI 读取 HBase 后渲染出拓扑图和调用树。这种分层设计把采集、传输、存储、展示解耦，单点故障不会直接拖垮整套监控。
在数据模型上，Pinpoint 借鉴了 Dapper 的 Trace 和 Span 概念。一次完整的分布式事务叫作 Trace，它由一个或多个 Span 组成；每个 Span 代表一次具体的 RPC 或方法调用，包含起始时间、耗时、服务名、接口名、错误信息等。Agent 会给每个 Span 生成唯一的 spanId 和 parentSpanId，并通过 HTTP 头或 RPC 协议透传 traceId，这样下游服务产生的 Span 就能和上游串成一条完整链路。即使请求跨线程、跨消息队列，Pinpoint 也能通过异步上下文传播保持链路连续。
数据流上，Agent 默认通过 UDP 将 Span 数据发送到 Collector 的 9995 端口，统计信息通过 9996 端口上报。Collector 将数据批量写入 HBase，默认表结构按应用名和逆序时间分片，便于快速扫描最近数据。Web UI 通过 HBase 查询某个 traceId 的全部 Span，再根据父子关系重建调用树。这个链路从采集到可查询通常只有几秒延迟，适合实时排障。
如果需要理解每个组件能力，可以看下面这张简化关系：
- Agent：字节码增强、调用采集、本地缓冲
- Collector：协议解析、批量聚合、HBase 写入
- HBase：海量存储、按 traceId 索引、TTL 过期
- Web UI：事务检索、拓扑展示、告警配置
这套架构的优点是吞吐量高，但 HBase 的运维成本也不低，后面会单独讨论。
二、接入 Java 应用的完整步骤
Pinpoint 的接入成本主要在 Agent 配置，而不是业务代码改造。首先从官方仓库下载 pinpoint-agent 包，解压后得到 pinpoint-bootstrap.jar、pinpoint.config 以及插件目录。接着在业务 JVM 的启动脚本中加上 -javaagent 参数，并通过 -D 指定应用名和 Agent ID。应用名用于在 UI 中聚合同类实例，Agent ID 必须是同一应用下的唯一标识，例如订单服务的第 1 个节点。
java -javaagent:C:\pinpoint-agent\pinpoint-bootstrap.jar \
-Dpinpoint.agentId=order-service-01 \
-Dpinpoint.applicationName=order-service \
-Dpinpoint.config=C:\pinpoint-agent\pinpoint.config \
-jar order-service.jar
上面示例是 Windows 路径，Linux 下只需把盘符改成 /opt/pinpoint-agent/pinpoint-bootstrap.jar。注意 -javaagent 必须放在 -jar 之前，否则 JVM 会忽略代理参数。启动后可以观察 Agent 日志，确认 Collector 连接成功。默认情况下，Agent 会从 pinpoint.config 读取 profiler.collector.ip 和端口，如果 Collector 不在本机，需要先修改配置。
在 pinpoint.config 中，有几个关键项需要根据环境调整：
profiler.collector.ip=127.0.0.1 profiler.collector.tcp.port=9994 profiler.collector.stat.port=9995 profiler.collector.span.port=9996 profiler.sampling.counting.sampling-rate=20 profiler.sampling.type=COUNTING
profiler.sampling.counting.sampling-rate 表示每 20 个请求采样 1 个，生产环境不建议全量采集，否则高并发下 Agent 会消耗大量 CPU 和网络带宽。对于核心链路或测试环境，可以设置为 1 表示全量。修改配置后需要重启业务进程才会生效。
除了 Java 应用，Pinpoint 也支持 PHP 扩展和部分其他语言，但 Java 生态插件最完善，能识别 Spring、Dubbo、Redis、MySQL、Kafka、RabbitMQ 等常见框架。接入后无需写埋点代码，Pinpoint 会自动识别这些组件并生成对应 Span，例如一次 MyBatis 查询会被记录成 SQL 执行 Span，包含绑定参数、执行耗时和返回行数。
三、利用事务地图与调用栈定位性能瓶颈
当系统出现慢请求时，第一步通常是在 Web UI 的事务列表里按响应时间倒序，找到耗时最高的 traceId。进入事务详情后，Pinpoint 会展示完整调用树，每个节点标出自身耗时、跨服务耗时和异常状态。如果某个 Span 的颜色偏红，说明它在整个链路中占比很高，可以直接展开查看该方法内部调用了哪些子方法、SQL 或缓存操作。
Pinpoint 最实用的两个视图是事务地图和调用时间线。事务地图把一次请求涉及的服务和数据库画成有向图，箭头粗细或颜色表示调用频率与延迟，一眼能看出是哪个下游依赖变慢。时间线则把所有 Span 按时间轴铺开，横向对比能发现串行调用和并行调用的差异。例如下单接口先查库存再查优惠券，如果两者串行执行导致总耗时叠加，优化方案就是改成并行调用，而 Pinpoint 的时间线能让这类问题立刻暴露。
SQL 追踪是另一高频场景。Pinpoint 会记录预处理语句、绑定参数和执行耗时，对于慢 SQL 可以直接在 UI 里看到完整 SQL 文本。需要特别留意的是，绑定的敏感参数可能包含手机号、身份证号，生产环境应开启 SQL 脱敏配置，避免监控系统成为数据泄露入口。同时，Pinpoint 也能采集异常堆栈，事务详情里会显示异常类型、消息和发生位置，定位线上偶发异常比翻日志快得多。
实际排查时建议形成固定路径：先看事务地图找瓶颈服务，再看调用树找瓶颈方法，最后看 SQL 或缓存调用找根因。比如支付接口超时，事务地图显示支付服务调用银行网关耗时 3.8 秒，而支付服务自身逻辑只有 40 毫秒；进入银行网关 Span 后发现两次重试各耗时 1.9 秒，就能确定是下游银行接口响应慢，而不是自己代码问题。这种证据链在跨团队协查时非常有说服力。
四、Pinpoint 与其他 APM 工具的对比及生产调优
开源 APM 领域常见的还有 SkyWalking、Zipkin、CAT。Zipkin 接入轻量但可视化较弱，需要配合其他 UI；CAT 偏向日志监控和报表，调用链追踪不如 Pinpoint 细致；SkyWalking 架构更现代，支持多种语言和存储后端，社区活跃度也更高。Pinpoint 的优势在于 Java 技术栈的调用链还原能力非常强，UI 直观，尤其是事务地图和字节码增强的插件覆盖面广。劣势是 HBase 强依赖带来较高运维成本，且多语言支持不如 SkyWalking。
从性能开销看，Pinpoint 的 Agent 会带来一定 CPU 和内存损耗，通常全量采样下约 5% 到 10%，采样率调到 20 后会降到 1% 左右。大流量服务建议只对入口请求做全量，内部服务适当降低采样，避免 HBase 写入成为瓶颈。HBase 表需要合理设置 TTL，例如保留 7 天即可，防止存储无限膨胀。如果调用链数据量很大，还可以为 Collector 增加节点，通过水平扩展提升写入能力。
生产环境部署时，建议把 Collector 和 HBase 独立部署，不要和业务服务混部。Web UI 可以只读 HBase，不直接与 Agent 通信，因此可以跨网段部署。告警方面，Pinpoint 提供了基础规则，但通常需要结合 Prometheus 或邮件网关做二次开发。监控系统本身也需要被监控，可以用脚本定期检查 Collector 端口和 HBase RegionServer 状态，避免出现业务没问题但监控挂了的盲区。
最后需要明确一点：APM 解决的是性能可观测性，它不能替代日志系统。Pinpoint 适合追踪慢请求和异常调用，但业务上下文、日志明细仍然要依赖 ELK 或 Loki。两者配合才能形成完整排障链路：先在 APM 中锁定 traceId，再拿 traceId 去日志系统检索关联日志。很多团队在接入 Pinpoint 后才发现调用链缺失，往往是因为没有统一 traceId 透传规范，所以接入前最好先约定网关生成 traceId 的规则。
Pinpoint APM分布式追踪全链路监控修改时间：2026-09-20 19:36:07