排查ThreadLocal内存泄漏需主动识别key==null但value强引用大对象的“幽灵条目”，通过jmap筛查堆结构、MAT分析Entry链路、jstack锁定长期线程，并结合日志与Prometheus监控常态化防控。
排查 ThreadLocal 忘记 remove() 引发的内存泄漏，关键不是等 OOM 才行动，而是借助监控工具主动识别“幽灵条目”——即 ThreadLocalMap.Entry 中 key == null 但 value 仍强引用大对象的残留状态。这类泄漏在线程池复用场景下尤为隐蔽且危险。
用 jmap 定位可疑堆内结构
先快速筛查堆中是否已出现典型泄漏痕迹：
- 执行
jmap -histo:live <pid> | grep -E "(Entry|YourContextClass|byte\[\])"，观察ThreadLocalMap$Entry实例数量是否异常高，或自定义上下文类（如UserContext、TraceContext）实例数持续增长 - 若怀疑严重，立即抓取堆快照：
jmap -dump:format=b,file=heap.hprof <pid>，后续用 MAT 分析
用 MAT 分析“幽灵条目”链路
在 Eclipse MAT 中打开 heap.hprof 后重点做三件事：
- 运行 Leak Suspects Report，查看是否提示 “One instance of ‘java.lang.Thread’ loaded by ‘<system class loader>’ is holding a reference to …” 并指向
ThreadLocalMap → Entry → value - 打开 Dominator Tree，筛选出线程名含
http-nio-、commonPool-worker-或自定义线程池名的java.lang.Thread实例，逐个展开其threadLocals字段，检查table数组中是否存在大量key = null但value非空（尤其是byte[]、HashMap、ArrayList等大对象）的Entry - 对某个可疑
value右键 → Path to GC Roots → 勾选 exclude weak/soft references，确认路径终点确实是某个长期存活线程的ThreadLocalMap，而非业务代码直接持有
用 jstack 结合日志锁定泄漏线程与代码点
堆分析只能告诉你“谁占着”，还需确认“谁写的”：
立即学习“Java免费学习笔记（深入）”；
- 执行
jstack <pid>，找出长时间运行（比如存活数小时）、频繁调度的线程，如http-nio-8080-exec-7、ForkJoinPool.commonPool-worker-3 - 在这些线程可能执行的路径上加诊断日志：在
set()前判断当前值是否非空，例如：if (contextTL.get() != null) log.warn("Context already set in thread {}", Thread.currentThread().getName());
若该日志高频触发，说明前序任务未清理就覆盖写入，旧value已实质泄漏 - 对线程池可临时重写
afterExecute()，统一打印threadLocal.get() != null的情况，快速定位漏删的提交点（如Runnable或Callable实现类）
用 Prometheus + Micrometer 监控长期趋势
生产环境需常态化观测，避免事后救火：
- 通过 Micrometer 注册自定义指标，统计每个关键
ThreadLocal的get()/remove()调用次数差值，或直接暴露threadLocal.get() != null的布尔状态 - 配合 Prometheus 查询：
count by (thread_name) (threadlocal_value_present{app="myapp"} == 1)，看哪些线程长期保持非空值 - 结合 Grafana 设置告警：当某类线程中非空
ThreadLocal实例数 5 分钟内增长超阈值（如 +50），立即通知
