Pinpoint 3.1.1 介绍与选型指南

目标：面向正在为 Java 为主的分布式系统选型应用性能监控（APM）平台的架构师与运维工程师，系统介绍 Pinpoint（Naver 开源 APM）的定位、核心架构、功能特性与部署形态，并给出与 CAT 监控、SkyWalking、Zipkin、Jaeger 的量化选型对比。本文为认知与选型篇，全部信息来自官方仓库（GitHub pinpoint-apm/pinpoint）、官方 README 兼容矩阵与 shields.io 徽章数据的公开溯源，来源与查询日期在各节随文标注（统一查询日期：2026-10-23）；部署、配置、命令类实操内容见本专栏后续各篇（Compose 部署 / 配置参数详解 / CLI 命令详解）。

一、环境信息

本章说明本文的取证方式与信息来源，保证读者可按相同路径复核每一条结论。本文为认知篇，不含本地实测，所有数据均通过公开渠道联网溯源并逐条标注来源与查询日期。

• 溯源对象主仓库：https://github.com/pinpoint-apm/pinpoint（Naver Corp. 维护，Apache License 2.0）
• 官方文档站：https://pinpoint-apm.gitbook.io/pinpoint
• 官方 Docker 仓库：https://github.com/pinpoint-apm/pinpoint-docker（**已于 2026 年归档、不再维护**，README 明确建议生产使用 pinpoint-apm/pinpoint-kubernetes；其 docker-compose.yml 保留作参考，Docker Hub 镜像仍随新版本持续发布——本文所有版本结论均以 Docker Hub 实际发布 tag 为准）
• 版本取证：GitHub Releases 页列出的最新稳定版为 v3.1.1，发布于 2026-10-02（来源：github.com/pinpoint-apm/pinpoint/releases 与 releases/tag/v3.1.1 页面 datetime="2026-10-02T06:04:27Z"；主仓库 README 同样标注 "Latest Release (2026/10/02)"）
• 星数取证：shields.io 徽章 JSON（img.shields.io/github/stars/pinpoint-apm/pinpoint.json）返回 stars=14k、forks=3.7k（查询日期 2026-10-23）
• 统一查询日期：2026-10-23

二、软件概述

2.1 定位与历史

Pinpoint 是 NAVER 公司开源的大规模分布式系统 APM（Application Performance Management，应用性能管理）平台，受 Google Dapper 论文启发，通过跨分布式应用的全链路追踪帮助使用者分析系统整体结构与组件间调用关系。官方 README 给出的能力清单（来源：主仓库 README，查询日期 2026-10-23）：

• 一眼看清应用的调用拓扑（Application Topology）；
• 实时监控应用运行状态；
• 每笔事务的代码级可见性（CallStack）;
• 不改一行代码安装 APM Agent（-javaagent 字节码增强方式）；
• 性能开销极小（官方口径：约 3% 的资源占用增长）。

主开发语言为 Java；除 Java 之外，官方还通过姊妹仓库 pinpoint-apm/pinpoint-c-agent 提供 PHP 与 Python 应用的接入支持（来源：主仓库 README "PHP, PYTHON" 一节）。

2.2 社区与许可证

• 许可证：Apache License, Version 2.0（来源：主仓库 README LICENSE 一节，Copyright 2018 NAVER Corp.）；
• 社区规模：GitHub stars 14k、forks 3.7k（shields.io，2026-10-23）；官方维护中文社区（QQ 群与钉钉群，见主仓库 README Community 一节）；
• 版本节奏：从兼容矩阵表（下文第七章）可见 2.x 时代保持约每季度一个 minor 版本，3.x 系列自 2024-05-31（v3.0.0）起持续推进，最新 v3.1.1 发布于 2026-10-02，属活跃维护状态；
• 生态周边：官方还维护 pinpoint-kubernetes（K8s 部署）、pinpoint-c-agent（PHP/Python）等仓库。

2.3 版本谱系与 3.1.1 新特性

v3.1.x 系列的主要新特性（来源：GitHub Releases v3.1.0/v3.1.1 Release Notes，查询日期 2026-10-23）：

• applicationName 上限扩展到 254 字符：需在 Agent 启动参数增加 -Dpinpoint.modules.uid.version=v3，与 3.1.0+ Collector 兼容；此前上限 24 字符，长结构化标识（如 team.service.env.region）不再被迫缩写；
• ServerMap V3：服务拓扑图重构，新增 MapAppSelf/MapAgentSelf/MapAppOut/MapAppIn/MapAppHost 五张表，大拓扑首屏渲染更快、HBase 读放大更低；
• Span 批量传输：SpanBatchGrpcDataSender（SendSpanList unary RPC）替代长驻 gRPC 双向流，profiler.transport.grpc.span.sender.type=BATCH 自 3.1.0 起为默认值，跨 L7 代理与 Collector 滚动发布时更稳；
• OpenTelemetry 指标接收：Collector 支持 OTLP 指标接入（metric 模块，对应镜像 3.1.1-metric）；
• v3.1.1 为 3.1 系列补丁版，发布于 2026-10-02。

💡 技术拓展：APM 的「Agent 接入方式」不止 Pinpoint 使用的「字节码增强」一种。常见方式对比——

接入方式	原理	代表	取舍
字节码增强	JVM -javaagent 启动时改写字节码，自动插桩框架类库	Pinpoint、SkyWalking	零代码改动，语言受限（仅 JVM 系）
SDK 埋点	业务代码调用 SDK API 显式记录	Zipkin、Jaeger	语言无关但侵入业务代码
OTel 自动插桩	OpenTelemetry Agent/SDK 统一标准	Jaeger/SkyWalking/Sentry 等后端	标准化生态，需按 OTLP 协议接入
消息模型埋点	统一消息树模型，客户端 SDK + Filter/Interceptor	CAT	侵入少但需按框架接入点封装

Pinpoint 3.1 起也支持 OTel 指标接入，属于「字节码增强 + OTel 指标」的混合形态。本文实际讨论的 Pinpoint 以字节码增强为主、OTel 指标为辅。

三、核心架构

3.1 组件与数据流

Pinpoint 采用经典的「探针 → 收集 → 存储 → 展示」四段式架构（来源：官方文档站 Overview 与主仓库 README，查询日期 2026-10-23）：

[Java 应用 + pinpoint-agent] --gRPC(9991/9992/9993)--> [pinpoint-collector] --> [HBase 2.x]
[PHP/Python 应用 + pinpoint-c-agent] --> 同上
[pinpoint-web] <-- 用户浏览器查询
[pinpoint-web/collector] <--> ZooKeeper（集群注册）
[pinpoint-batch] --> MySQL（告警/用户/任务表）
[pinpoint-flink（可选）] <-- collector 实时统计流 --> 应用 Inspector

各组件职责：

3.2 Agent 侧：字节码增强与插件矩阵

Agent 通过 -javaagent:pinpoint-bootstrap.jar 挂载，基于字节码增强在框架类库的出入口自动织入埋点，业务零改动。官方 README "Supported Modules" 一节列出的插件矩阵（查询日期 2026-10-23，节选）：

• 容器/服务器：Tomcat、Jetty、JBoss EAP、WebSphere、WebLogic、Vert.x、Undertow、Akka HTTP；
• 开发框架：Spring、Spring Boot（内嵌 Tomcat/Jetty/Undertow/Reactor Netty）、Spring WebFlux、Spring TX、Spring Cloud Sleuth、RestTemplate、Ktor；
• HTTP 客户端：Apache HttpClient 3/4/5、JDK HttpClient、OkHttp、GoogleHttpClient、Netty 等；
• RPC：Thrift、Apache Dubbo、gRPC、Apache CXF；
• 消息队列：ActiveMQ、RabbitMQ、Kafka、RocketMQ、Pulsar、Paho MQTT；
• 数据库驱动：MySQL、Oracle、MSSQL、PostgreSQL、MariaDB、DB2、ClickHouse、达梦（Dameng）、CUBRID 等；
• 缓存：Jedis、Lettuce、Redisson、Memcached、Arcus、Cassandra、MongoDB、HBase、Elasticsearch；
• ORM/连接池：iBATIS、MyBatis、DBCP/DBCP2、HikariCP、Druid；
• 日志：log4j、Logback、log4j2（可关联 TraceId）；
• 其他：Hystrix、Resilience4j、RxJava、Reactor、Kotlin Coroutines、AWS SDK S3 等。

这份矩阵决定了选型的实际价值：业务栈越贴近上表，Pinpoint 的开箱可用度越高。跨服务调用链识别依赖客户端在 HTTP 头/RPC 元数据中传递 Pinpoint 自己的上下文（TxId），因此 Pinpoint 集群内部天然互通，但与非 Pinpoint 系 APM 不共享传播头（3.1 的 OTel 指标接收不改变这一点）。

3.3 存储侧：HBase 表体系与 TTL

Pinpoint 把「链路明细（Trace）、调用关系统计（Map）、应用索引、Agent 信息、字符串/API 元数据」分别落到 HBase 的不同表（3.1 V3 表见 Release Notes：MapAppSelf、MapAgentSelf、MapAppOut、MapAppIn、MapAppHost 等）。官方 pinpoint-docker 的 .env 给出了各类数据的 TTL 参数（来源：pinpoint-docker 仓库 .env，查询日期 2026-10-23，节选）：

这一结构意味着：HBase 是 Pinpoint 唯一的链路存储后端（官方兼容矩阵仅列 HBase 2.x，见第七章），MySQL 只是 web/batch 元数据。想要「换存储后端」的使用者应考虑 SkyWalking 或 Jaeger 而不是 Pinpoint。

四、功能特性

以下特性均来自主仓库 README Overview 一节与官方文档站（查询日期 2026-10-23）：

• ServerMap（服务拓扑图）：把分布式系统按 Agent 间调用关系自动生成拓扑，节点即应用、边即调用方向，节点上叠加请求量/异常率；3.1 的 V3 表重构后大拓扑首屏更快；
• Realtime Active Thread Chart：实时活跃线程曲线，快速定位容器化应用「卡死还是过载」；
• Request/Response Scatter Chart（响应散点图）：请求量与响应时间的散点分布，可框选慢请求下钻；
• CallStack（代码级调用栈）：单笔事务内按层级展开 SQL、外部 HTTP、MQ 调用耗时，代码级定位瓶颈；
• Inspector（检查器）：应用与 Agent 维度的 JVM 内存/GC、CPU、TPS、JVM 参数等（应用/主机指标需 flink 或 metric 模块支撑）；
• URI-Metric / Infrastructure Metric：URI 维度与主机维度指标（2.5.0+，需 Pinot 或 3.1 metric 模块 + OTLP）；
• Alarm（告警）：基于 batch + MySQL 的告警规则（如响应时间、异常数、JVM 健康），支持邮件通知；
• Error-Analysis（错误分析）：异常事务聚合与快照对比；
• OTel 指标接收（3.1+）：Collector 可直接接收 OTLP 指标。

五、快速开始（最小可用示例）

本章给出官方提供的最快体验路径，命令与说明溯源自 pinpoint-docker 仓库 README（查询日期 2026-10-23）。注意：该仓库 README 顶部已标注 "This repository is no longer maintained and has been archived"，官方建议生产使用 pinpoint-kubernetes；但其 docker-compose.yml 与 Docker Hub 镜像仍可用，镜像持续随新版本发布（3.1.1 于 2026-10-02 推送），作为「10 分钟体验」路径依然有效：

git clone https://github.com/pinpoint-apm/pinpoint-docker.git
cd pinpoint-docker
docker-compose pull && docker-compose up -d

官方 README 原文说明：约 10 分钟即可拉起一套完整环境，自带 pinpoint-quickstart 示例应用，可直接在 Web UI 查看演示数据。

最小组件链路（不含 flink/batch 的裁剪版）仅需 7 个角色：zookeeper、pinpoint-hbase、pinpoint-mysql、pinpoint-web、pinpoint-collector、pinpoint-agent（提供 agent 目录）、示例应用（挂 -javaagent）。本系列《Pinpoint 3.1.1 Docker Compose 部署指南》将给出裁剪后可直接落地的 compose 文件与逐项验证回显。

💡 技术拓展：Pinpoint 的「应用聚合维度」由 -Dpinpoint.applicationName（应用名）与 -Dpinpoint.agentId（实例 ID）二元组决定：同一 applicationName 的多个 agent 实例在拓扑中聚为一个节点，agentId 需在 applicationName 范围内唯一。3.1 起 applicationName 最长 254 字符（需 -Dpinpoint.modules.uid.version=v3），agentId 最长 24 字符。

本系列其余三篇（均在同一环境实测，可直接衔接本章的最小体验路径）：

• 《Pinpoint 3.1.1 Docker Compose 部署指南》：从零部署裁剪版全链路环境（镜像选型、首启时序、持久化与排障实录）；
• 《Pinpoint 3.1.1 配置参数详解》：Collector/Web/HBase/Agent 四类进程的参数位置、默认值、生效验证与生产模板；
• 《Pinpoint 3.1.1 常用 CLI 命令与工具详解》：HBase Shell、Compose 启停、Agent 验证与 REST API 的用法与真实回显。

六、适用场景与限制

6.1 适用场景

1. JVM 系微服务全链路监控：Spring Boot/Dubbo/Kafka/MySQL 栈的团队希望零代码接入、拿到拓扑+调用栈+JVM 指标三合一视图；
2. 已有 HBase/大数据运维能力的组织：HBase 运维成本在团队承受范围内，且需要长期（TTL 可到年级别）保留链路数据；
3. 需要代码级排障：CallStack + 散点图组合适合「慢在哪一行/哪一条 SQL」的定位场景；
4. PHP/Python 混合栈：可经 pinpoint-c-agent 一并接入同一拓扑。

6.2 限制与注意

1. 强依赖 HBase 2.x：链路数据只有 HBase 一种存储后端（官方兼容矩阵），没有 MySQL/ES 轻量替代；HBase 本身需要额外运维（ZooKeeper、region 上线等待、GC 调优）；
2. 资源占用偏重：官方 pinpoint-docker 全家桶含 13 个角色（3×ZooKeeper+flink×2+…），小内存机器跑不动；本系列实测采用 7 角色裁剪链路（详见部署篇的资源核算）；
3. Java 版本窗口：3.1.x 服务端（collector/web/batch）要求 Java 17，Agent 可挂 Java 8–25 应用（主仓库 README 兼容矩阵，2026-10-23）；
4. Agent-Collector 版本强耦合：3.1.x agent 只能配 3.1.x collector（README 兼容表 "Agent Version × Collector 3.1.x → 3.1.x=yes、3.0.x=no"），升级需同步两端；
5. 官方 docker-compose 仓库已归档：新生产部署官方指向 pinpoint-kubernetes；Compose 路径虽可用（镜像仍在发布），但需自行承担维护更新；
6. 指标模块镜像分叉：OTel 指标/URI 指标需要 -metric 变体镜像与 Pinot/Kafka 或 OTLP 通道，默认链路不含。

七、同类选型对比

本章按统一口径量化对比 5 款主流开源 APM/链路追踪系统。星数/版本/最近提交取自 shields.io 徽章 JSON 与 GitHub Releases 页面（统一查询日期 2026-10-23）；存储与接入方式取自各项目官方 README/文档站。

7.1 量化对比总表

7.2 兼容矩阵量化（Pinpoint 官方 README，2026-10-23）

运行时 Java 版本兼容（原文表格）：

HBase 兼容：3.0.x 与 3.1.x 仅支持 HBase 2.x（2.3.x–2.5.x 经 hbase2-module 可选 2.x，更早版本可用 1.x）。Agent-Collector 兼容：3.1.x agent 仅兼容 3.1.x collector。

7.3 与本站 CAT 监控专栏的对照说明

CAT 与 Pinpoint 同属「老牌、重量级、自带拓扑与告警」的 Java 系 APM，差异主要在存储与接入模型：CAT 的消息模型把客户端/服务端埋点收敛为统一消息树，存储只依赖 MySQL（运维成本低），但接入需按框架封装 Filter；Pinpoint 以字节码增强换零代码接入，代价是强绑定 HBase。两者国内社区都活跃（CAT 19k stars，Pinpoint 有官方中文社区群）。详细的 CAT 架构与选型结论见站内专栏 《CAT 监控 3.1.0 介绍与选型指南》。

7.4 选型建议

按「如果……则……」给出可操作建议：

1. 如果团队是 JVM 微服务栈、追求零代码接入 + 代码级调用栈 + 自动拓扑，且已有（或愿意运维）HBase，则选 Pinpoint——它的插件矩阵覆盖面在同类中数一数二；
2. 如果只想要 MySQL 一个存储、愿意接受少量 Filter 埋点代码、团队在点评/CAT 生态内，则选 CAT；
3. 如果要求 OTel 原生、指标-日志-链路一体化、存储可插拔（含国产 BanyanDB），则选 SkyWalking（社区最活跃，25k stars）；
4. 如果只要轻量调用链查询、自己已有埋点体系或 OTel SDK，则选 Zipkin（简单）或 Jaeger（CNCF、云原生集成深）；
5. 如果服务端只有一台小内存机器，则优先避开 Pinpoint 全家桶（HBase 本身就重），Zipkin 内存模式或 SkyWalking 内嵌 BanyanDB 更合适。

一句话总结：Pinpoint 的核心卖点是「零代码 + 代码级视图 + 自动拓扑」三合一，核心代价是 HBase 单一存储与组件链路偏重；把它放进有 HBase 运维能力的 JVM 团队，性价比最高。

八、参考链接

• 主仓库：https://github.com/pinpoint-apm/pinpoint
• Releases：https://github.com/pinpoint-apm/pinpoint/releases/tag/v3.1.1
• 官方文档站：https://pinpoint-apm.gitbook.io/pinpoint
• 官方 Docker 仓库（已归档，参考用）：https://github.com/pinpoint-apm/pinpoint-docker
• 官方 Kubernetes 仓库：https://github.com/pinpoint-apm/pinpoint-kubernetes
• PHP/Python Agent：https://github.com/pinpoint-apm/pinpoint-c-agent
• Docker Hub 镜像：https://hub.docker.com/r/pinpointdocker/pinpoint-hbase
• 站内专栏：《CAT 监控 3.1.0 介绍与选型指南》