Files
java-word-pdf/docs/MEM_USAGE_UPGRADE.md
T
Pjandro f3ff218686
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 5m26s
Main: tests, deploy, autotests / web (push) Successful in 9s
Main: tests, deploy, autotests / images-web (push) Successful in 23s
Main: tests, deploy, autotests / java (push) Successful in 1m30s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Successful in 2m13s
Main: tests, deploy, autotests / autotests (push) Successful in 17s
Main: tests, deploy, autotests / rollback (push) Has been skipped
feat(core): собственный рендер OMML→PNG и полный FOP-конфиг шрифтов
Замена JEuclid/AWT-ветки формул на детерминированный растер только
бандл-шрифтами jar (без fontconfig); FOP-конфиг дополняется всеми
бандл-начертаниями при каждом declare — иначе общая FopFactory
замораживает fopconf первого документа и теряет глифы.

MathModel/MathRenderer: OMML (§22.1) → дерево боксов → PNG 300 dpi
(только GlyphFont/fontbox, без java.awt.Font); метрики боксов равны
габариту paint (пределы nary/sPre не обрезаются канвой). Unsupported
конструкция или переполнение бюджета — текстовая деградация (m:t).
Inline-картинка опускается раном w:rPr/w:position на базовую линию
строки (FOP ставит инлайн-графику нижним краем на базу; AUDIT-FIX
baseline-shift). Байтовое правило 6 MathFallbackNormalizer (перед
GlyphCoverage) срезает unsupported-формулы до загрузки docx4j; формула
в wps:txbx уходит в docx4j-фолбэк mathText.

JEuclid исключён из pom (de.rototor jeuclid-core/jeuclid-fop); порядок
zip-правил сдвинут (MathFallback → 6). Порядок сканов шрифтов закрыт
гейтом FontsBundledOnlyInvariantTest + BundledFontAliases (единый
алиас-реестр вместо рефлексивных мутаций реестра).

Счётчики: 63 класса / 1004 теста (core 57/956, app 6/48); JaCoCo
BRANCH core 0.8518. Доки: pipeline/render-limitations/repo-map/
testing/doc-bridge/MEM_USAGE_UPGRADE синхронизированы.
2026-11-20 23:51:40 +03:00

191 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Потребление памяти при конвертации 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)~~ — **удалён из класса путей** (2026-11): jeuclid исключён exclusion'ом из
`docx4j-export-fo`, формулы рисует собственный `MathRenderer` (PNG, только бандл-шрифты);
`MathFallbackNormalizer` теперь деградирует в текст только конструкции вне `MathModel.SUPPORTED`.
## 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-шрифты — §2; JEuclid больше
не потребитель — исключён из зависимостей): точечными
правками репозитория их не сократить, а правки библиотек/форка (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 (фиделити-тесты — единственный арбитр).