Files
java-word-pdf/docs/MEM_USAGE_UPGRADE.md
T
Pjandro 1c8f6e1516
PR checks / web (pull_request) Successful in 48s
PR checks / java (pull_request) Successful in 1m19s
Main: tests, deploy, autotests / java (push) Successful in 3m11s
Main: tests, deploy, autotests / web (push) Successful in 1m29s
Main: tests, deploy, autotests / images-app (push) Successful in 2m21s
Main: tests, deploy, autotests / images-web (push) Successful in 2m43s
Main: tests, deploy, autotests / deploy (push) Successful in 1m52s
Main: tests, deploy, autotests / autotests (push) Successful in 58s
Main: tests, deploy, autotests / rollback (push) Has been skipped
docs: MEM_USAGE_UPGRADE.md — аудит памяти конвейера
- Методология харнеса (peak/used/GC-лог/JFR/VmHWM) и его ограничения;
- baseline suite×20+big, профиль аллокаций: доли приложения ≤0,44%, остальное — JAXB/XSLT/FOP;
- кандидаты A–E с замерными гейтами: все отклонены (A — измерением, B/C/E — долей ниже гейта);
- матрица флагов f1–f5: рекомендация проду -Xmx768m/G1 + mem_limit 1g вместо 2G/3G.
2026-11-17 05:46:10 +03:00

17 KiB
Raw Blame History

Потребление памяти при конвертации doc/docx → pdf: аудит и результаты апгрейда (2026-11)

Харнес: MemoryBench (wordpdf-core/src/test/java/ru/pjandro/wordpdf/MemoryBench.java, test-scope) + membench.sh + ./mise.sh run mem-bench. Числа ниже получены на них; методология и ограничения — §1.

1. Методология измерения

JVM: temurin 17.0.21, флаги харнеса -Xms64m -Xmx2g -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError

  • JFR settings=profile + -Xlog:gc*=info,gc+heap=debug. Машина — рабочая станция (amd64), не прод-контейнер.

Метрики на конвертацию (TSV-строки вывода харнеса):

Метрика Как снята Смысл
peak MemoryPoolMXBean.getPeakUsage() по хип-пулам с reset() перед каждой конвертацией высокая вода кучи за конвертацию (включает невозвращённый мусор young-поколения — это мера запроса памяти, не live-сета)
used сумма getUsage().getUsed() сразу после конвертации куча «как есть» до ближайшего GC
allocated-estimate GC-лог: выметенный Eden + humongous между паузами честная оценка аллокаций (JFR-веса для этого не годятся — см. ограничения)
max-live-after-gc GC-лог: максимум M->M(after) по паузам живая куча после GC (включает конвертацию, идущую в момент паузы)
VmHWM /proc/self/status пик резидентной памяти процесса (куча + Metaspace + стеки + JFR-буферы)
top-frames/app-sites агрегация jdk.ObjectAllocationSample из JFR профиль аллокаций (относительная доля; веса — оценка сэмплера)

Сценарии: suite — все 25 фикстур samples/ (13 .docx + 12 .doc) циклами; big — синтетический документ: document.xml фикстуры ru-plain.docx с повтором секции ×400 (≈1,6 МБ XML после распаковки, ≈6000 строк контента, PDF ≈50 КБ/конвертация — много контента при малом in-put, именно он и нагружает конвейер, а не байты входа).

Ограничения (важно для повторного прочтения чисел):

  • шум ±30% на фикстуру между прогонами (старт нового JVM на сценарий, G1 растягивает young по ходу прогона); сравнимы только суммарные/медианные агрегаты одного метода на одном железе;
  • peak включает мусор: документ с большим churn даёт большой peak при малом live-сете;
  • веса JFR ObjectAllocationSample (profile, period=20ms) — оценка сэмплера; абсолют — только GC-лог;
  • фикстуры малы (вход ≤182 КБ, PDF в среднем 385 КБ): кандидаты, экономящие единицы мегабайт, на них неотличимы от шума — это учитывалось в гейтах (§4).

Воспроизведение: MB_LABEL=run ./mise.sh run mem-bench --scenario all --loops 20 | tee target/mem-run.txt; матрица флагов — через env MB_JAVA_OPTS (флаги идут после дефолтных и переопределяют их).

2. Baseline (до правок)

MB_LABEL=before ./mise.sh run mem-bench --scenario all --loops 20 (JVM 17.0.21, пик 2026-11-17):

Фикстура n peak p50, МБ peak max, МБ used avg, МБ
chart-types.docx 20 641 934 398
charts-smartart.doc 20 457 630 321
charts-smartart.docx 20 471 751 299
doc-formats.doc 20 261 783 326
en-plain.doc 20 302 819 273
en-plain.docx 20 278 855 298
exotic-glyphs.doc 20 328 907 325
exotic-glyphs.docx 20 312 950 287
ole-embedded.doc 20 298 540 238
ole-embedded.docx 20 269 574 222
page-numbers.doc 20 234 598 257
page-numbers.docx 20 272 558 266
ru-en-mixed.doc 20 300 453 293
ru-en-mixed.docx 20 344 528 298
ru-plain.doc 20 344 572 256
ru-plain.docx 20 281 455 274
ru-table-image.doc 20 331 462 267
ru-table-image.docx 20 299 522 263
ru-times.doc 20 275 561 275
ru-times.docx 20 251 580 256
stale-cache.doc 20 307 511 264
stale-cache.docx 20 323 525 269
symbol-bullets.docx 20 335 459 310
too-many-pages.doc 20 405 599 265
too-many-pages.docx 20 327 724 288
big (синтетика ×400) 5 924 976 360

Итоги прогона: allocated-estimate=36069MB (≈71 МБ churn на конвертацию при медианном peak 300 МБ), max-live-after-gc=504MB, паузы 536 шт./4815 мс; VmHWM процесса: 1,34 ГБ после suite-части, 1,56 ГБ после big-части (-Xmx2g доступен, куча растягивается под churn).

Главный вывод baseline: память уходит не в копии документа, а в churn конвейера. Вход 2,6–182 КБ при peak 224–641 МБ — отношение долей порядка сотен. Профиль аллокаций (JFR, alloc-total — оценка сэмплера 26,3 МБ взвешенных):

  • доли приложения в топ-кадрах: DocxRewritePipeline.normalize — 0,44%, WordPdfConverter.convert — 0,36%, GlyphFont.draw — 0,10%; все остальные кадры ru.pjandro.* — ниже 0,1% (гейты §4);
  • остальное — библиотеки: JAXB-андмаршалинг docx4j через DOM (DOMScanner.visit/scan, SAXOutput.getQName, NamespaceContextImpl.put, SAX2DOMEx.startElement, ClassFactory.create0), Xalan/XSLT, FOP (таблицы OpenType: OTFAdvancedTypographicTableReader, OpenFont.readHorizontalMetrics), commons-io IOUtils.byteArray, Arrays.copyOf, Throwable.fillInStackTrace (docx4j использует исключения как control flow — «Package field null» и т.п.);
  • JEuclid (Parser.parseStreamSourceAsOdf) — OMML-формулы на хосте с fontconfig (в CI/контейнере иначе: MathFallback).

3. Что нашли при чтении кода (архитектурные находки)

  1. FO материалзуется как String. Форк FORendererApacheFOP.convert(FODocumentHandler, FOConverterContext, String) (javap docx4j-export-fo 17.3.2) принимает весь выход XSLT одной строкой UTF-16: для FO-документа это ≈2 байта/символ и FO в разы больше исходного XML. Убрать можно только правкой форка (templates.transform стримом в FOP-парсер) — вне рамок репозитория; фиделити-риск высокий. Дорожная карта.
  2. disableFontCache() в форке вызывается безусловно в 3 местах (javap FORendererApacheFOP: FontManager.disableFontCache), один участок защищён Fop.isUseCache() из fop.xconf (по умолчанию кеш выключен) → таблицы шрифтов перечитываются на каждый рендер (видно в топ-кадрах). Потенциальный рычаг (churn+CPU), но включение кеша влияет на сабзеттинг/метрики — только с фиделити-прогоном, в форк/конфиг. Дорожная карта.
  3. WordprocessingMLPackage в docx4j 17.3.2 не имеет close()/dispose() (javap пакета openpackaging.packages/parts — только setJaxbElement/unmarshal): «освободить пакет явно» API не даёт; пакет — локальная переменная convertToStream и умирает вместе со стеком.
  4. Валидатор делает два полных стриминговых прохода по байтам входа (checkPageCount + checkDocxContainer/validate): CPU, память O(8 КБ буферов) — на peak не влияет (§4, гейт E).
  5. Мост .doc уже отпускает потоки (releaseStreams), но DocxWriter.write держит одновременно bodyXml+parts+hyperlinks до toByteArray(); на фикстурах доля моста в аллокациях <0,15% — не рычаг при текущих документах (§4, гейт C).

4. Кандидаты оптимизаций и гейты

Гейт: кандидат остаётся, только если после правки suite-сумма peak или big-peak улучшились ≥3% (для «всегдашнего» A — плюс отсутствие регрессии); для B/C/E — плюс доля ≥5% в app-sites JFR. Прогоны «до/после» — идентичной методикой, один и тот же компьютер, подряд.

Кандидат Доля в аллокациях (гейт 5%) Замер после (гейт 3%) Итог
A. Чанковый буфер PDF вместо ByteArrayOutputStream — allocated +0,7% (шум), сумма peak +7,2% (хуже) отклонён, откачен
B. Needle-гейт декода в DocxRewritePipeline normalize 0,44% — отклонён до правки
C. Ранний отпуск bodyXml/parts/hyperlinks в DocxWriter.write кадров моста в топ-15 нет (<0,15%) — отклонён до правки
D. Явный release пакета docx4j API отсутствует (§3.3) — нереализуем
E. Один проход валидатора кадров валидатора в топ-15 нет (<0,1%) — отклонён до правки (плюс риск порядка ошибок — контракт 400-кодов)

Почему A отклонён измерением, хотя «в теории» экономит. Реализация (PdfOutputChunks, чанки вместо удваивающегося byte[]) протестирована на эквивалентность байтов и прогнана полным бенчем (25 фикстур ×20 + big ×5, тот же метод):

  • PDF фикстур в среднем 385 КБ: для них PdfOutputChunks с фиксированным чанком выделяет больше, чем рост ByteArrayOutputStream от Math.max(1<<16, docxBytes.length) — сумма peak выросла на 7,2%;
  • микробенч на 24 МБ (одноразовый PeakProof, куча 2г): peak 76 МБ у чанков против 61 МБ у BAOS — чанк 1 МиБ на G1 humongous (регион 1 МиБ → 2 региона на чанк, отсюда ×2), чанк 256 КиБ уходит в young и при подсчёте peak платит растянутым Eden; live-минимум чанков (P+P против 2–3P у BAOS) выигрывает только на PDF десятки мегабайт, каких в фикстурах нет;
  • вердикт гейта: не улучшено → откачен, конвейер остался на ByteArrayOutputStream.

Итог по правкам ядра: ни один кандидат не прошёл гейт. Это не «нечего улучшать», а «у текущих документов память тратят библиотеки» (JAXB-via-DOM, XSLT, FOP-шрифты, JEuclid — §2): точечными правками репозитория их не сократить, а правки библиотек/форка (FO-стриминг, font cache) — отдельные задачи с фиделити-гейтом. Практический рычаг «потреблять меньше» прямо сейчас — размеры кучи и GC (§5).

5. Матрица флагов JVM (итог: что ставить в прод)

Один и тот же прогон (--scenario all --loops 5 --big-loops 2), меняются только флаги (MB_JAVA_OPTS поверх дефолта харнеса; для смены GC нужен и -XX:-UseG1GC — иначе старт падает с «Multiple garbage collectors selected»). ВМ не кончалась ни на одном наборе, OOM'а нет нигде, включая big-сценарий:

Набор VmHWM suite, МБ VmHWM +big, МБ max-live, МБ Паузы (шт/мс) Вывод
f1 — G1, -Xmx2g (дефолт харнеса; прод-Containerfile как раз 2G/mem_limit 3G) 931 1337 575 159 / 1724 работает, но куча ×2,6 к реальной потребности
f2 — G1, -Xmx768m 802 902 451 183 / 1865 рекомендуемый: RSS ≤0,9 ГБ с JFR-буферами, запас к max-live 1,7×
f3 — G1, -Xmx512m 818 843 416 199 / 1877 работает, но max-live 416 из 512 — малый запас на chart-тяжёлые документы
f4 — Serial, -Xmx512m 748 748 482 126 / 4453 работает; паузы ×2,6 против G1
f5 — Serial, -Xmx384m 628 634 359 150 / 5803 максимальная плотность (RSS 0,63 ГБ); паузы ×3,4, max-live 359 из 384 — впритык

allocated-estimate у Serial-прогонов — 0: awk-агрегатор GC-лога понимает G1-формат (регионы), для Serial аллокации считаются по другому шаблону — на вывод матрицы не влияет.

Рекомендация прод-стеку (рендерится job'ом deploy из Gitea Variables — менять их, не репо):

  1. Heap: -Xmx768m (f2) вместо 2G; mem_limit — 1g вместо 3G. FopFactory/XSLT-кеш перманентны, их размер от кучи не зависит; 451 МБ max-live — это ~3 конвертации chart-тяжёлых документов в полёте (а конвертации сериализованы монитором — реально одна).
  2. G1 оставить (~13 мс пауз на конвертацию против ~40 мс у Serial; при конвертациях 1–4 с это не критично, но G1 при 768m ещё и ровнее ведёт humongous-аллокации растров чартов).
  3. Плотность выше f2 (Serial 384m) достижима, но запас <7% к max-live на 384m — для прод-вариабельности документов неприемлемо.

6. Итог апгрейда

  • Ядро не изменено: ни один кандидат (A–E, §4) не прошёл замерный гейт; экономия памяти на текущих документах лежит не в коде репозитория, а внутри JAXB/XSLT/FOP (§2–3). Правки форка (FO-стриминг, font cache) — зафиксированные дорожные пункты с фиделити-гейтом.
  • Практический эффект «потреблять меньше» — профиль кучи: 2G/3G → 768m/1g (в ~3 раза меньше резидентной памяти на стенде) без потери проходимости всех сценариев, включая big.
  • Инфраструктура измерений осталась в репо: MemoryBench + membench.sh + ./mise.sh run mem-bench — любой следующий раунд начинается с baseline за 10 минут.

7. Как читать этот документ дальше

  • Перепроверить числа: §1 (команды) — прогон ~10 мин, артефакты в target/ и wordpdf-core/target/membench-*.jfr.
  • Перед новым «починить память»: сначала топ-кадры собственного прогона — доли приложения ≤0,4% означают, что чинить нужно библиотеки, а не WordPdfConverter.
  • Стоп-лист § «не чинить» из docs/agent/render-limitations.md остаётся в силе: экономия памяти не должна менять выход PDF (фиделити-тесты — единственный арбитр).