Pinpoint 3.1.1 配置参数详解

目标：系统梳理 Pinpoint 3.1.1 四类进程（Collector 数据收集器、Web 控制台、HBase 存储、Agent 探针）的全部核心配置参数——所在位置、默认值、修改方式与生效验证手段，并给出一套可直接落地的入门生产模板。文中每个参数值与每段回显均来自 Ubuntu 22.04.4 LTS 实测环境（Docker Compose 部署形态，部署过程见本专栏《Pinpoint 3.1.1 Docker Compose 部署指南》）。

一、环境信息

本章列出本文取证所用的环境，参数含义部分另注明官方默认值。

• 操作系统：Ubuntu 22.04.4 LTS（x86_64，12 vCPU / 31GB 内存实测机）
• 部署形态：Docker Compose（Docker 29.8.1 + Compose v5.5.1），项目名 pinpoint-311-stack，网络 pinpoint-311-net（10.89.70.0/24）
• Pinpoint 版本：3.1.1（pinpointdocker 官方镜像）
• 组件版本：HBase 2.2.6（HBase 服务内置，Java 8 运行）、ZooKeeper 3.4.13、MySQL 8.0（实测 8.0.46）、Redis 7.0.14
• Java 运行时：Web 与 Collector 为 Java 17 应用（jib 打包，JRE 环境）；HBase 为 JDK 8；示例应用挂 JDK 8 的 Tomcat 8
• 服务端口：8148 → Web 控制台、8149 → HBase Master UI、8150 → 示例应用、8151 → MySQL
• 部署目录：/opt/pinpoint（compose 文件与 MySQL 初始化脚本所在）
• 统一取证日期：2026-10-23

二、前置条件

阅读与复现本文操作前，需要满足以下条件：

1. 已按 《Pinpoint 3.1.1 Docker Compose 部署指南》第四章完成部署，且全套服务处于 Up 状态；
2. Agent→Collector→HBase→Web 链路已贯通，能查到已注册应用（验证命令与实测回显）：

curl -s http://localhost:8148/api/applications

[{"applicationName":"quickapp","serviceType":"TOMCAT","code":1010}]

3. 了解 compose 文件里各服务名（pinpoint-web、pinpoint-collector、pinpoint-hbase、pinpoint-agent、pinpoint-quickstart 等），本文的容器内操作统一用 docker compose exec <服务名> … 执行。

三、参数查看与修改方式

Pinpoint 3.1.1 没有单一配置文件——参数分散在「环境变量注入、properties 配置文件、Agent 探针配置、HBase 建表脚本」四个载体里。本章先讲清楚每一类参数在哪、怎么看、怎么改、怎么确认生效。

3.1 参数的四个载体

Web/Collector 的环境变量遵循 Spring Boot 的宽松绑定（relaxed binding）规则：ADMIN_PASSWORD → admin.password、CONFIG_SENDUSAGE → config.sendUsage、SPRING_DATA_REDIS_HOST → spring.data.redis.host，即「点分小写属性名」去掉点号、转大写、用下划线连接。

容器内已注入的环境变量实测（pinpoint-web）：

docker compose exec pinpoint-web env | grep -E '^(ADMIN_PASSWORD|CONFIG_SENDUSAGE|CONFIG_SHOW_APPLICATIONSTAT|JAVA_TOOL_OPTIONS|SPRING_PROFILES_ACTIVE)='

实测回显：

CONFIG_SENDUSAGE=false
ADMIN_PASSWORD=q1w2e3r4
SPRING_PROFILES_ACTIVE=release
JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m
CONFIG_SHOW_APPLICATIONSTAT=true

3.2 修改方式 A：compose 环境变量（推荐）

编辑 /opt/pinpoint/docker-compose.yml 中对应服务的 environment: 段，然后重建该服务：

cd /opt/pinpoint && docker compose up -d pinpoint-web

环境变量无变化时的实测回显（服务已运行则直接跳过重建）：

 Container pinpoint-311-web Running
 Container pinpoint-311-zoo1 Running
 Container pinpoint-311-hbase Running
 Container pinpoint-311-zoo3 Running
 Container pinpoint-311-mysql Running
 Container pinpoint-311-zoo2 Running
 Container pinpoint-311-redis Running

环境变量有变化时，同样的命令会先 Recreate 再 Start 该服务。优点是改动落在编排文件里、可版本管理、幂等可重放；多副本场景每份都要改。

3.3 修改方式 B：挂载覆盖 properties 文件

需要改环境变量没有映射的深层参数时（如 gRPC 线程池、日志策略），把容器内配置文件拷出、修改后挂载回同路径（只读挂载 :ro）：

cd /opt/pinpoint && mkdir -p conf/web && docker compose cp pinpoint-web:/app/resources/pinpoint-web-root.properties ./conf/web/pinpoint-web-root.properties

实测回显（注意：目标目录必须先建好，docker compose cp 不会自动创建不存在的目录，否则报 invalid output path）：

 pinpoint-311-web Copying pinpoint-311-web:/app/resources/pinpoint-web-root.properties to ./conf/web/pinpoint-web-root.properties
 pinpoint-311-web Copied pinpoint-311-web:/app/resources/pinpoint-web-root.properties to ./conf/web/pinpoint-web-root.properties

拷出的文件开头即能看到关键默认值（实测节选）：

pinpoint.zookeeper.address=localhost

# FIXME - should be removed for proper authentication
admin.password=admin

修改后在 compose 的 pinpoint-web 服务下增加挂载：

    volumes:
      - ./conf/web/pinpoint-web-root.properties:/app/resources/pinpoint-web-root.properties:ro

再 docker compose up -d pinpoint-web 重建。完整操作步骤与挂载点清单见部署指南第八章。

3.4 修改方式 C：Agent 探针配置

Agent 镜像入口脚本 configure-agent.sh 的机制是「环境变量 → sed 写入探针配置文件」：

• 写 profiles/local/pinpoint.config 与 profiles/release/pinpoint.config：profiler.transport.module（GRPC/THRIFT）、profiler.collector.ip、profiler.transport.grpc.collector.ip、profiler.sampling.type、profiler.sampling.counting.sampling-rate、profiler.sampling.percent.sampling-rate、profiler.sampling.new.throughput、profiler.sampling.continue.throughput；
• 写 pinpoint-root.config：profiler.collector.tcp.port（9994）、profiler.collector.stat.port（9995）、profiler.collector.span.port（9996）与 profiler.transport.grpc.{agent,metadata,stat,span}.collector.port（9991/9991/9992/9993）。

因此改 Agent 参数优先走环境变量重建；绕过脚本直接改共享卷里的配置文件也可行，但下次重建 agent 服务时会被脚本覆盖。

3.5 生效验证四件套

改完参数必须验证实际生效值，四类组件各有一个「铁证」：

① Web/Collector JVM 堆（JAVA_TOOL_OPTIONS）——JVM 启动时最先打印 Picked up 行，实测（collector）：

cd /opt/pinpoint && docker compose logs pinpoint-collector 2>&1 | grep -m1 'Picked up'

实测回显：

pinpoint-311-collector  | Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m

② Web 行为参数——启动日志打印完整 ConfigProperties 对象（见 5.2 实测回显），逐项对值。

③ Collector gRPC 监听——启动 banner 打印 collector.receiver.grpc.* 全套值（见 5.1 实测回显）。

④ HBase 堆与 TTL——HBase 容器自带 JDK 8 的 jps，jps -v 能看到实际堆参数（见 5.3）；TTL 用 hbase shell 的 desc 看（见 5.3）。

四、参数总览

按组件汇总核心参数、所在位置与默认值。带「本方案值」的列是部署指南 compose 里的实测取值。

Web（容器内 /app/resources/）：

Collector（容器内 /app/resources/）：

HBase（环境变量 + 容器内 /opt/hbase/hbase-2.2.6/conf/）：

Agent（/pinpoint-agent/ 目录）：

💡 技术拓展：Agent 的「采样模型」有三种可选，直接决定数据量与排障粒度的平衡——

模型	参数	原理	适用场景
COUNTING	profiler.sampling.type=COUNTING	每 N 笔事务采 1 笔（rate=1 即全量）	中小流量、要完整链路
PERCENT	profiler.sampling.type=PERCENT	按百分比随机采样	大流量、按比例控量
THROUGHPUT	profiler.sampling.type=THROUGHPUT	按每秒吞吐阈值动态丢采样	高峰期保底限流

本文实测环境用 COUNTING + rate=1（全量）便于验证；生产建议见第六章模板。

五、核心参数分类详解

5.1 Collector 参数

Collector 是「Agent 上报的 gRPC 服务端 + HBase 写入端」。启动 banner 会打印全套接收配置，实测回显：

cd /opt/pinpoint && docker compose logs pinpoint-collector 2>&1 | grep -m4 'collector.receiver.grpc'

实测回显：

pinpoint-311-collector  |  ::                    collector.receiver.grpc.agent.enable ::                                true
pinpoint-311-collector  |  ::            collector.receiver.grpc.agent.bindaddress.ip ::                             0.0.0.0
pinpoint-311-collector  |  ::           collector.receiver.grpc.agent.bindaddress.port ::                                 9991
pinpoint-311-collector  |  ::           collector.receiver.grpc.agent.ssl.enable ::                                false

（1）gRPC 接收三通道：Agent 通道 9991（Agent 心跳/元数据同走此口）、统计通道 9992、Span 通道 9993，三个 receiver 全部 bindaddress 0.0.0.0。跨机接入真实应用时，只需在防火墙放行这三个 TCP 端口，无需改 bindaddress。SSL 三端口 9441/9442/9443 默认不启用。

（2）集群注册：CLUSTER_ENABLE=true + PINPOINT_ZOOKEEPER_ADDRESS=zoo1 让 collector 与 web 在同一个 ZooKeeper 上注册，Web 的实时 Active Thread 图依赖这条链路。多 ZooKeeper 节点用逗号分隔（本方案 compose 只写了 zoo1，ZooKeeper 集群内部自带完整 quorum，客户端只需可达任一入口）。

（3）FLINK_CLUSTER_ENABLE=false：本方案未部署 flink 实时流聚合，此项必须显式关掉，否则 collector 启动时尝试连接不存在的 flink 集群，拖慢启动且刷连接失败日志。

（4）存储与元数据：链路数据写 HBase（连接参数在 hbase-root.properties，默认适配镜像内 HBase 2.2.6，无需改动）；用户/告警等元数据走 SPRING_DATASOURCE_HIKARI_* 指向的 MySQL；SPRING_DATA_REDIS_* 指向 Redis 缓存。三者地址都跟随 compose 服务名，仅在拆分部署时需要改。

（5）JVM 堆：JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m。Collector 是整条链路最吃内存的进程（实测常驻约 784MB），512MB 堆起步是够用的下限档位；修改位置就在 compose 的 environment:，验证看 3.5 ① 的 Picked up 回显。

5.2 Web 参数

Web 是「HBase 查询端 + 控制台」。最有信息量的验证手段是启动日志里的 ConfigProperties 对象，它把主要行为参数的实际生效值一次打全。实测回显：

cd /opt/pinpoint && docker compose logs pinpoint-web 2>&1 | grep -m1 'ConfigProperties{'

实测回显（一行截取）：

pinpoint-311-web  | 10-23 00:44:35.912 [           main] INFO  c.n.p.w.c.ConfigProperties               -- ConfigProperties{sendUsage=false, editUserInfo=true, showActiveThread=true, showActiveThreadDump=true, enableActiveThreadDump=true, enableServerMapRealTime=false, openSource=true, securityGuideUrl='null', showApplicationStat=true, showStackTraceOnError=true, showSystemMetric=false, showUrlStat=false, showExceptionTrace=false, showOtlpMetric=false, showInspector=false, showHeatmap=false, webSocketAllowedOrigins=, webhookEnable=true, serverMapPeriodMax=2, serverMapPeriodInterval=[5m, 20m, 1h, 3h, 6h, 12h, 1d, 2d], inspectorPeriodMax=42, inspectorPeriodInterval=[5m, 20m, 1h, 3h, 6h, 12h, 1d, 2d, 1w, 3w, 6w]}

逐项解读（对照镜像内 pinpoint-web-root.properties 的默认值）：

（1）管理口令：admin.password 默认 admin，compose 用 ADMIN_PASSWORD=q1w2e3r4 覆盖。但它是否真正拦截请求取决于登录模块是否安装——实测 PINPOINT_MODULES_WEB_LOGIN 环境变量在 3.1.1 官方 compose 镜像中未生效（详见 7.3），生产务必前置反向代理做认证。

（2）查询窗口：拓扑窗口上限 serverMapPeriodMax=2（天），可选档位到 2d；Inspector 窗口上限 42 天。前端超过档位的查询会被拒绝或截断，API 直调时同样受此约束。

（3）配置集：SPRING_PROFILES_ACTIVE=release 决定读取 profiles/release/ 下的 hbase.properties 与 pinpoint-web.properties；local 是官方本地调试档位，生产固定 release。

5.3 HBase 存储参数

HBase 容器把「装软件、起集群、建表」封装在入口脚本 /usr/local/bin/initialize-hbase.sh 里，链路为：start-hbase.sh（起 HMaster/HRegionServer）→ configure-hbase.sh（把 15 个 *_TTL 环境变量逐表 sed 进 hbase-create.hbase/hbase-update-ttl.hbase）→ check-table.sh（用 exists 'AgentId' 判断表是否存在，不存在则 sleep 15 后执行 hbase shell hbase-create.hbase 建 22 张表）。

（1）JVM 堆：HBASE_HEAPSIZE

HBASE_HEAPSIZE=512m 由容器内 hbase-env.sh 换算成 -Xmx512m 注入 HMaster 与 HRegionServer。实测验证（HBase 容器自带 JDK 8 的 jps）：

cd /opt/pinpoint && docker compose exec pinpoint-hbase jps -v

实测回显：

164 HRegionServer -Dproc_regionserver -XX:OnOutOfMemoryError=kill -9 %p -Xmx512m -XX:+UseConcMarkSweepGC -XX:PermSize=128m -XX:MaxPermSize=128m -Dhbase.log.dir=/opt/hbase/hbase-2.2.6/logs -Dhbase.log.file=hbase--regionserver-81e9a8749ae7.log -Dhbase.home.dir=/opt/hbase/hbase-2.2.6 -Dhbase.id.str= -Dhbase.root.logger=INFO,RFA -Dhbase.security.logger=INFO,RFAS
88 HMaster -Dproc_master -XX:OnOutOfMemoryError=kill -9 %p -Xmx512m -XX:+UseConcMarkSweepGC -XX:PermSize=128m -XX:MaxPermSize=128m -Dhbase.log.dir=/opt/hbase/hbase-2.2.6/logs -Dhbase.log.file=hbase--master-81e9a8749ae7.log -Dhbase.home.dir=/opt/hbase/hbase-2.2.6 -Dhbase.id.str= -Dhbase.root.logger=INFO,RFA -Dhbase.security.logger=INFO,RFAS
15224 Jps -Dapplication.home=/usr/local/openjdk-8 -Xms8m

两个进程都实锤 -Xmx512m。改堆就改 compose 里的 HBASE_HEAPSIZE，重建 hbase 服务后用同一命令复查。

（2）TTL 参数总表（15 个环境变量）

实建表的 TTL 可以用 desc 逐一核对，实测（hbase shell 内执行 desc 'AgentInfo'；注意表名必须带引号，不带引号会报 NameError: uninitialized constant AgentInfo）：

Table AgentInfo is ENABLED
AgentInfo
COLUMN FAMILIES DESCRIPTION
{NAME => 'Info', VERSIONS => '1', EVICT_BLOCKS_ON_CLOSE => 'false', NEW_VERSION_BEHAVIOR => 'false', KEEP_DELETED_CELLS => 'FALSE', CACHE_DATA_ON_WRITE => 'false', DATA_BLOCK_ENCODING => 'PREFIX', TTL => '31536000 SECONDS (365 DAYS)', MIN_VERSIONS => '0', REPLICATION_SCOPE => '0', BLOOMFILTER => 'ROW', CACHE_INDEX_ON_WRITE => 'false', IN_MEMORY => 'false', CACHE_BLOOMS_ON_WRITE => 'false', PREFETCH_BLOCKS_ON_OPEN => 'false', COMPRESSION => 'NONE', BLOCKCACHE => 'true', BLOCKSIZE => '65536'}

（3）TTL 的生效时机与事后修改（实测排障）

TTL 环境变量只在建表那一刻生效。首启后想缩短/延长保留期，需要进 HBase shell alter。实测发现一个语法陷阱——不带列族名的 alter 会被静默忽略：

hbase(main):001:0> alter 'AgentEvent', {TTL => '6048000'}
Unknown argument ignored: TTL
Updating all regions with the new schema...
1/1 regions updated.
Done.
Took 2.5537 seconds

desc 复查 TTL 仍是 5184000 SECONDS (60 DAYS)——语法必须带列族名（Pinpoint 表的列族各不相同，AgentEvent 是 E）。正确写法实测：

hbase(main):002:0> alter 'AgentEvent', {NAME => 'E', TTL => '6048000'}
Updating all regions with the new schema...
1/1 regions updated.
Done.
Took 2.1043 seconds

hbase(main):003:0> desc 'AgentEvent'
Table AgentEvent is ENABLED
AgentEvent
COLUMN FAMILIES DESCRIPTION
{NAME => 'E', VERSIONS => '1', EVICT_BLOCKS_ON_CLOSE => 'false', NEW_VERSION_BEHAVIOR => 'false', KEEP_DELETED_CELLS => 'FALSE', CACHE_DATA_ON_WRITE => 'false', DATA_BLOCK_ENCODING => 'PREFIX', TTL => '6048000 SECONDS (70 DAYS)', MIN_VERSIONS => '0', REPLICATION_SCOPE => '0', BLOOMFILTER => 'ROW', CACHE_INDEX_ON_WRITE => 'false', IN_MEMORY => 'false', CACHE_BLOOMS_ON_WRITE => 'false', PREFETCH_BLOCKS_ON_OPEN => 'false', COMPRESSION => 'NONE', BLOCKCACHE => 'true', BLOCKSIZE => '65536'}

TTL => '6048000 SECONDS (70 DAYS)' 修改成功。各表的列族名可先 desc '表名' 查看或看建表脚本（实测：AgentInfo 是 Info、TraceV2 是 S）。

（4）数据目录：HBase rootdir 为容器内 /home/pinpoint/hbase（对应命名卷 pinpoint-311-stack_hbase_data），软件目录是 /opt/hbase/hbase-2.2.6（HBASE_HOME），两者不要混淆——持久化与备份针对前者。

5.4 Agent 参数

Agent 侧配置分两层：探针配置文件（由 agent 容器的 configure-agent.sh 生成）与应用侧启动参数（-javaagent + -Dpinpoint.*）。

（1）传输与端口（pinpoint-root.config）

GRPC 模式下四个通道端口的实际落盘值，实测（通过挂载了探针目录的示例应用读取）：

cd /opt/pinpoint && docker compose exec pinpoint-quickstart grep -E '^profiler\.transport\.grpc\.(agent|metadata|stat|span)\.collector\.port' /pinpoint-agent/pinpoint-root.config

实测回显：

profiler.transport.grpc.agent.collector.port=9991
profiler.transport.grpc.metadata.collector.port=9991
profiler.transport.grpc.stat.collector.port=9992
profiler.transport.grpc.span.collector.port=9993

与 collector 的三个监听端口对齐：agent/metadata 都走 9991，stat 走 9992，span 走 9993。Thrift 时代的 profiler.collector.tcp/stat/span.port（9994/9995/9996）在 GRPC 模式下不参与通信，保留默认即可。

（2）采样参数（profiles/release/pinpoint.config）

实测落盘值（带行号）：

cd /opt/pinpoint && docker compose exec pinpoint-quickstart grep -nE '^profiler\.(transport\.module|sampling\.(type|counting\.sampling-rate|percent\.sampling-rate|new\.throughput|continue\.throughput))' /pinpoint-agent/profiles/release/pinpoint.config

实测回显：

19:profiler.transport.module=GRPC
56:profiler.sampling.type=COUNTING
62:profiler.sampling.counting.sampling-rate=1
69:profiler.sampling.percent.sampling-rate=100
73:profiler.sampling.new.throughput=0
75:profiler.sampling.continue.throughput=0

• sampling.type=COUNTING + counting.sampling-rate=1：每 1 笔采 1 笔，即全量采样（验证环境用）；
• percent.sampling-rate=100：PERCENT 模型的采样率，当前未启用；
• new/continue.throughput=0：吞吐模型的两个阈值，0 表示不启用。

生产调整建议见第六章模板：改 compose 里 PROFILER_SAMPLING_TYPE 与对应 rate 变量，重建 agent 与应用后用同一 grep 复查落盘值。

（3）应用侧启动参数

示例应用的完整 JVM 参数实测（ps aux 截取）：

/opt/java/openjdk/bin/java -Djava.util.logging.config.file=/usr/local/tomcat/conf/logging.properties -Xms256m -Xmx512m -javaagent:/pinpoint-agent/pinpoint-bootstrap.jar -Dpinpoint.agentId=app-in-docker -Dpinpoint.applicationName=quickapp -Dpinpoint.profiler.profiles.active=release ... org.apache.catalina.startup.Bootstrap start

三个关键 -D 参数：

💡 说明：Agent 的 serviceType（如 TOMCAT:1010、SPRING_BOOT:1210）不由参数指定，由探针按运行环境自动识别并上报，查询端必须以 /api/applications 返回的类型为准（实测陷阱：跑在独立 Tomcat 里的 Spring 风格应用注册为 TOMCAT，详见部署指南第十一章）。

六、生产配置模板

适用场景：8GB 内存 / NVMe SSD / 接入 10 个以内 JVM 应用、以拓扑排障与调用栈分析为主的入门生产环境。JVM 堆统一控制在 512MB 档位（本文实测上限档），机器内存充裕时可在同一位置线性上调并按 3.5 的四件套复查。

Web（compose environment:）：

      - SPRING_PROFILES_ACTIVE=release
      - PINPOINT_ZOOKEEPER_ADDRESS=zoo1
      - CLUSTER_ENABLE=true
      - ADMIN_PASSWORD=q1w2e3r4
      - CONFIG_SENDUSAGE=false
      - CONFIG_SHOW_APPLICATIONSTAT=true
      - LOGGING_LEVEL_ROOT=INFO
      - JDBC_DRIVERCLASSNAME=com.mysql.jdbc.Driver
      - JDBC_URL=jdbc:mysql://pinpoint-mysql:3306/pinpoint?characterEncoding=UTF-8
      - JDBC_USERNAME=admin
      - JDBC_PASSWORD=q1w2e3r4
      - SPRING_DATASOURCE_HIKARI_JDBCURL=jdbc:mysql://pinpoint-mysql:3306/pinpoint?characterEncoding=UTF-8
      - SPRING_DATASOURCE_HIKARI_USERNAME=admin
      - SPRING_DATASOURCE_HIKARI_PASSWORD=q1w2e3r4
      - SPRING_DATA_REDIS_HOST=pinpoint-311-redis
      - SPRING_DATA_REDIS_PORT=6379
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

Collector（compose environment:）：

      - SPRING_PROFILES_ACTIVE=release
      - PINPOINT_ZOOKEEPER_ADDRESS=zoo1
      - CLUSTER_ENABLE=true
      - LOGGING_LEVEL_ROOT=INFO
      - FLINK_CLUSTER_ENABLE=false
      - SPRING_DATASOURCE_HIKARI_JDBCURL=jdbc:mysql://pinpoint-mysql:3306/pinpoint?characterEncoding=UTF-8
      - SPRING_DATASOURCE_HIKARI_USERNAME=admin
      - SPRING_DATASOURCE_HIKARI_PASSWORD=q1w2e3r4
      - SPRING_DATA_REDIS_HOST=pinpoint-311-redis
      - SPRING_DATA_REDIS_PORT=6379
      - JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m

HBase（compose environment:，TTL 按默认档，磁盘紧张时缩统计类表）：

      - HBASE_HEAPSIZE=512m
      - AGENTINFO_TTL=31536000
      - APPINDEX_TTL=31536000
      - APIMETADATA_TTL=31536000
      - TRACEV2_TTL=5184000
      - APPTRACEINDEX_TTL=5184000
      - APPMAPSTATCALLERV2_TTL=5184000
      - APPMAPSTATCALLEV2_TTL=5184000
      - APPMAPSTATSELFV2_TTL=5184000
      - AGENTSTATV2_TTL=5184000
      - AGENTEVENT_TTL=5184000
      - AGENTLIFECYCLE_TTL=5184000
      - APPSTATAGGRE_TTL=5184000
      - HOSTAPPMAPV2_TTL=5184000
      - STRINGMETADATA_TTL=15552000
      - SQLMETADATA_TTL=15552000

Agent（compose environment:，与默认档的差异：采样降为每 10 笔采 1 笔）：

      - SPRING_PROFILES=release
      - COLLECTOR_IP=pinpoint-311-collector
      - PROFILER_TRANSPORT_MODULE=GRPC
      - PROFILER_TRANSPORT_AGENT_COLLECTOR_PORT=9991
      - PROFILER_TRANSPORT_METADATA_COLLECTOR_PORT=9991
      - PROFILER_TRANSPORT_STAT_COLLECTOR_PORT=9992
      - PROFILER_TRANSPORT_SPAN_COLLECTOR_PORT=9993
      - PROFILER_SAMPLING_TYPE=COUNTING
      - PROFILER_SAMPLING_COUNTING_SAMPLING_RATE=10
      - PROFILER_SAMPLING_PERCENT_SAMPLING_RATE=100
      - PROFILER_SAMPLING_NEW_THROUGHPUT=0
      - PROFILER_SAMPLING_CONTINUE_THROUGHPUT=0
      - AGENT_DEBUG_LEVEL=INFO

模板要点：

1. 采样 COUNTING + rate=10 在拓扑与趋势分析基本无损的前提下把存储写入量降到约十分之一；需要完整调用栈取证的排障窗口，可临时改回 1 并重建；
2. TTL 保持官方默认档（明细 60 天 / 元数据 180–365 天）；磁盘紧张优先缩 TRACEV2_TTL 与三张 APPMAPSTAT*_TTL（明细与拓扑统计是大头）；
3. 所有口令类值（ADMIN_PASSWORD、JDBC_PASSWORD）在本模板中沿用示例值 q1w2e3r4，落地时替换为自己的强口令；
4. 应用后重新过一遍 3.5 的「生效验证四件套」：Picked up（JVM 堆）、ConfigProperties{（Web 行为）、collector.receiver.grpc（监听）、jps -v（HBase 堆）。

七、常见问题

7.1 改了 TTL 环境变量，数据保留期没变

原因与结论：TTL 只在建表时经 configure-hbase.sh 写进建表脚本，check-table.sh 见到表已存在就会跳过建表。首启后改 TTL 环境变量对老表无效。两条路：进 HBase shell 用带列族名的 alter '表名', {NAME => '列族', TTL => '秒数'} 逐表修改（实测验证见 5.3（3），不带 NAME 会被 Unknown argument ignored 静默忽略）；或删掉 pinpoint-311-stack_hbase_data 卷重建（数据清零，慎用）。

7.2 JAVA_TOOL_OPTIONS 改了，怎么确认真的生效

结论：JVM 进程启动时会在标准输出最前面打印 Picked up JAVA_TOOL_OPTIONS: <值>。用 docker compose logs <服务名> 2>&1 | grep -m1 'Picked up' 核对（实测回显见 3.5 ①）。注意该行只在进程启动时打印一次，改完必须重建服务再看。

7.3 ADMIN_PASSWORD 设置了，为什么控制台没有登录页拦截

结论：实测（镜像内自带 pinpoint-basic-login-3.1.1.jar，GET /login 返回 200）给 compose 加 PINPOINT_MODULES_WEB_LOGIN=basic-login 并重建后，启动日志没有任何登录模块安装记录（对照会打印 Install WebhookModule 的 Webhook 模块），POST /login 返回 405。即 3.1.1 官方 compose 镜像的登录开关未生效，admin.password 不会转化为真正的认证拦截。生产务必在 Pinpoint 前置 Nginx 反向代理做 Basic Auth 或 IP 白名单。

7.4 SPRING_PROFILES_ACTIVE 的 local 和 release 差在哪

结论：镜像内 /app/resources/profiles/ 下有两套子目录（local、release），各含 hbase.properties 与 pinpoint-web.properties（collector 同理）。release 是生产/部署档位，local 是官方本地调试档位（连本机 HBase 等）。固定 release 即可；Agent 侧对应的是 SPRING_PROFILES=release，决定 configure-agent.sh 写哪套 profiles/*/pinpoint.config。

7.5 拓扑/Inspector 查大时间范围报错或被截断

结论：Web 启动日志实测 serverMapPeriodMax=2（天）、档位 [5m, 20m, 1h, 3h, 6h, 12h, 1d, 2d]，Inspector 窗口上限 42 天。超窗查询分段进行；这是产品内置限制，不改代码改不了。

7.6 启动日志大量 JDK17 反射告警

现象：

java.lang.reflect.InaccessibleObjectException: Unable to make static boolean java.nio.Bits.unaligned() accessible: module java.base does not "opens java.nio" to unnamed module

结论：3.1.x 服务端跑在 Java 17 上，老依赖反射调用触发的模块系统告警，实测不影响功能。要消除可在 JAVA_TOOL_OPTIONS 追加 --add-opens java.base/java.nio=ALL-UNNAMED。

7.7 应用注册出来的 serviceType 和预期不一致

结论：serviceType 由探针按运行环境自动识别，不由应用名或框架决定。实测跑在独立 Tomcat 8 里的 Spring 风格示例应用注册为 TOMCAT(1010) 而非 SPRING_BOOT(1210)。一切查询（控制台下拉框、API 参数）以 curl -s http://localhost:8148/api/applications 返回的类型为准；传错类型会查到空拓扑。

八、参考链接

• 本站系列：《Pinpoint 3.1.1 介绍与选型指南》（定位、架构、新特性与选型对比）
• 本站系列：《Pinpoint 3.1.1 Docker Compose 部署指南》（从零部署、环境变量注入与运维命令）
• 主仓库：https://github.com/pinpoint-apm/pinpoint
• 官方文档站：https://pinpoint-apm.gitbook.io/pinpoint
• 官方 Docker 仓库（compose 与 .env 参考）：https://github.com/pinpoint-apm/pinpoint-docker