---
docgen:
  source: npm/lib/omlx-trace.mjs
  crc: 3ff568d5
  score: 100
---

# omlx-trace.mjs

## Огляд

Модуль збирає трасу викликів LLM, фіксуючи думки моделі та спостережуваний слід. Траса записується у локальний файл для ротації та готується для подальшої батч-агрегації. Дизайн-специфікація: docs/specs/2026-06-10-omlx-wire-trace-capture-design.md.

## Поведінка

MAX_MSG_CHARS
Ліміт символів на одне message.content у записі

ROTATE_BYTES
Поріг недеструктивної ротації активного файлу в байтах

tracePath
Повертає шлях до trace-файлу або null

capMessages
Обрізає message.content та рахує sha256 повного масиву

buildTraceRecord
Будує нормалізований trace-запис

rotateIfNeeded
Недеструктивно ротує файл при перевищенні ROTATE_BYTES

writeTrace
Записує trace-запис у файл з ротацією та fail-safe

## Публічний API

MAX_MSG_CHARS — встановлює максимальну кількість символів для вмісту повідомлення.
ROTATE_BYTES — визначає поріг для ініціювання ротації файлу.
tracePath — зберігає шлях до файлу трасування або порожній рядок, якщо трасування вимкнено.
N_CURSOR_LLM_TRACE — визначає пріоритет для вибору шляху трасування: спочатку перевіряється вимкнений перемикач, потім використовується явний шлях.
buildTraceRecord — створює запис трасування, залишаючи порожні значення для полів, які недоступні.
rotateIfNeeded — перейменовує файл при перевищенні ліміту, створюючи новий файл з послідовним індексом.
writeTrace — записує один запис трасування, обробляючи шляхи, ротуючи дані за необхідності та обробляючи помилки вводу/виводу.

## Гарантії поведінки

- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
- Не звертається до мережі.
