# Потребление памяти при конвертации 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 (фиделити-тесты — единственный арбитр).