# Документация по LLMTracer

Модуль **LLMTracer** предназначен для трассировки запросов к LLM, а также для сбора статистики по токенам, времени выполнения и ошибкам. Все данные записываются в таблицу `llm_tracer`.

---

## Класс: Session

Подключается через

```js
let LLMTracer = require("Common.AIHelpers.LLMTracer")
```

### createSession(options)

Создаёт новую сессию трассировки.

**Пример:**

```js
let session = LLMTracer.createSession({
  business_id: "123",
  bot_id: "456",
  lead_id: "789",
  script_id: "script_1",
  command_id: "cmd_1",
  agent_name: "MyAgent",
  provider: "OpenAI",
  model: "gpt-4"
})
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-bus"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>business\_id</td><td>String</td><td>Идентификатор бизнеса</td></tr><tr><td>bot\_id</td><td>String</td><td>Идентификатор бота</td></tr><tr><td>lead\_id</td><td>String</td><td>Идентификатор лида</td></tr><tr><td>script\_id</td><td>String</td><td>Идентификатор скрипта</td></tr><tr><td>command\_id</td><td>String</td><td>Идентификатор команды</td></tr><tr><td>agent\_name</td><td>String</td><td>Имя агента</td></tr><tr><td>provider</td><td>String</td><td>Название провайдера LLM</td></tr><tr><td>model</td><td>String</td><td>Название модели LLM</td></tr></tbody></table>

**Return**  
Session — Экземпляр сессии трассировки.

---

### getCurrentSession()

Получает текущую сессию из атрибута лида.

**Пример:**

```js
let session = LLMTracer.getCurrentSession()
```

**Параметры:**  
Нет

**Return**  
Session | null — Текущий объект сессии или null, если не найден.

---

### prepareRecordData(data)

Преобразует данные в безопасный формат для записи в таблицу.

**Пример:**

```js
let safeData = LLMTracer.prepareRecordData({ message: "Тест", status: "ok" })
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-dat"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>data</td><td>Object</td><td>Объект с исходными данными</td></tr></tbody></table>

**Return**  
Object — Объект с преобразованными значениями.

---

### recordTrace(traceData)

Записывает трассировку в таблицу `llm_tracer`.

**Пример:**

```js
LLMTracer.recordTrace({
  agent_name: "MyAgent",
  outclient_name: "ClientA",
  step: "step1",
  outclient_time: 120,
  provider: "OpenAI",
  model: "gpt-4",
  type: "info",
  message: "Запрос выполнен",
  record: {},
  params: {},
  status: "ok",
  input_tokens: 100,
  output_tokens: 50
})
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-age"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>agent\_name</td><td>String</td><td>Имя агента</td></tr><tr><td>outclient\_name</td><td>String</td><td>Имя внешнего клиента</td></tr><tr><td>step</td><td>String</td><td>Название шага</td></tr><tr><td>outclient\_time</td><td>Number</td><td>Время выполнения шага (мс)</td></tr><tr><td>provider</td><td>String</td><td>Название провайдера LLM</td></tr><tr><td>model</td><td>String</td><td>Название модели LLM</td></tr><tr><td>type</td><td>String</td><td>Тип трассировки (info, error и др.)</td></tr><tr><td>message</td><td>String</td><td>Сообщение</td></tr><tr><td>record</td><td>Object</td><td>Дополнительные данные</td></tr><tr><td>params</td><td>Object</td><td>Параметры запроса</td></tr><tr><td>status</td><td>String</td><td>Статус выполнения</td></tr><tr><td>input\_tokens</td><td>Number</td><td>Количество входных токенов</td></tr><tr><td>output\_tokens</td><td>Number</td><td>Количество выходных токенов</td></tr></tbody></table>

**Return**  
Boolean — true при успехе, false при ошибке.

---

### recordTraceLLM(llm, timerCtrl, traceData)

Записывает трассировку по активному LLMClient.

**Пример:**

```js
LLMTracer.recordTraceLLM(llmClient, "START_TIME", { message: "Старт" })
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-llm"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>llm</td><td>Object</td><td>Экземпляр LLMClient</td></tr><tr><td>timerCtrl</td><td>String</td><td>Контроллер времени ("", "START\_TIME", "END\_TIME")</td></tr><tr><td>traceData</td><td>Object</td><td>Дополнительные параметры трассировки</td></tr></tbody></table>

**Return**  
Boolean — true при успехе, false при ошибке.

---

### recordTraceQuery(llm, timerCtrl, traceData)

Записывает трассировку для запросов к внешним сервисам.

**Пример:**

```js
LLMTracer.recordTraceQuery(llmClient, "END_TIME", { message: "Финиш" })
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-llm-0"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>llm</td><td>Object</td><td>Экземпляр LLMClient</td></tr><tr><td>timerCtrl</td><td>String</td><td>Контроллер времени ("", "START\_TIME", "END\_TIME")</td></tr><tr><td>traceData</td><td>Object</td><td>Дополнительные параметры трассировки</td></tr></tbody></table>

**Return**  
Boolean — true при успехе, false при ошибке.

---

### info(message, data)

Записывает информационную трассировку.

**Пример:**

```js
LLMTracer.info("Запрос выполнен", { step: "step1" })
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-mes"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>message</td><td>String</td><td>Текст сообщения</td></tr><tr><td>data</td><td>Object</td><td>Дополнительные данные</td></tr></tbody></table>

**Return**  
Boolean — true при успехе, false при ошибке.

---

### error(message, data)

Записывает ошибку в трассировку и отправляет сообщение админу.

**Пример:**

```js
LLMTracer.error("Ошибка запроса", { code: 500 })
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-mes-0"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>message</td><td>String</td><td>Текст ошибки</td></tr><tr><td>data</td><td>Object</td><td>Дополнительные данные</td></tr></tbody></table>

**Return**  
Boolean — true при успехе, false при ошибке.

---

### countTokens(dateRange)

Подсчитывает количество токенов за указанный период.

**Пример:**

```js
LLMTracer.countTokens({ from: "2024-06-01 00:00:00", to: "2024-06-30 23:59:59" })
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-fro"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>from</td><td>String</td><td>Начальная дата ("YYYY-MM-DD HH:MM:SS")</td></tr><tr><td>to</td><td>String</td><td>Конечная дата</td></tr></tbody></table>

**Return**  
Object — { input\_tokens, output\_tokens, total\_tokens }

---

### getActiveSessionsCount(minutes)

Подсчитывает количество активных сессий за последние N минут.

**Пример:**

```js
LLMTracer.getActiveSessionsCount(10)
```

**Параметры:**

<table id="bkmrk-%D0%98%D0%BC%D1%8F-%D0%A2%D0%B8%D0%BF-%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5-min"><thead><tr><th>Имя</th><th>Тип</th><th>Описание</th></tr></thead><tbody><tr><td>minutes</td><td>Number</td><td>Глубина окна в минутах (по умолчанию 5)</td></tr></tbody></table>

**Return**  
Number — Количество активных сессий.

---

## Быстрый старт

1. Создайте сессию: `LLMTracer.createSession({ ... })`
2. Запишите шаг: `LLMTracer.recordTrace({ ... })`
3. Для LLM: используйте `recordTraceLLM()`
4. Для ошибок: используйте `error()`
5. Для статистики: используйте `countTokens()`