> ## Documentation Index
> Fetch the complete documentation index at: https://cs-lua.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# log

> Один лог-файл на плагин с автоматической ротацией по дням

# log

Один лог-файл на плагин с автоматической ротацией по дням.

`log.write(msg)` пишет строку в текстовый лог плагина — свой файл на каждый
календарный день, без настройки каналов и без ручной ротации.

<h2 id="write">
  log.write
</h2>

Пишет строку в лог плагина.

```lua theme={null}
log.write(msg[, opts])
```

### Аргументы

| # | имя    | тип          |                         |
| - | ------ | ------------ | ----------------------- |
| 1 | `msg`  | string       | строка для записи в лог |
| 2 | `opts` | table \| nil | см. Опции ниже          |

### Возвращает

| тип                         |                                                                            |
| --------------------------- | -------------------------------------------------------------------------- |
| `boolean`                   | `true` при успехе, `false` при неудаче (нет контекста плагина, не создался |
| каталог, диск полон и т.п.) |                                                                            |

<h3 id="write-опции">
  Опции
</h3>

| поле     | тип     |                                                                                 |
| -------- | ------- | ------------------------------------------------------------------------------- |
| `global` | boolean | `false` по умолчанию; `true` — писать в общий лог модуля, а не в свой           |
| `level`  | string  | `"info"` по умолчанию; `"info"`, `"warning"`, `"error"`, `"debug"`, `"success"` |

### Пример

```lua theme={null}
hook.add("player:death", "myplugin.kills_log", function(e)
  log.write(("%s killed %s"):format(
    e.attacker and e.attacker:name() or "world", e.player:name()))
end)

log.write("не удалось подключиться к API", { level = "error" })
log.write("подозрительная активность", { global = true, level = "warning" })
```

`log.write` рассчитан на то, чтобы дёргать его где угодно не проверяя
результат — `false` возвращается редко и не как повод остановить логику
плагина.

## Файл и формат

По умолчанию (`global` не задан или `false`) путь —
`plugin.data_dir()/logs/<YYYY-MM-DD>.log`: дата берётся из системного
времени сервера на момент вызова, каждый файл открывается на дозапись,
каждая строка со своей меткой времени и уровнем:

```
[2026-08-18 21:07:03] [INFO] player1 killed player2
[2026-08-18 21:08:11] [ERROR] не удалось подключиться к API
```

С `global = true` файл лежит в `addons/lua/logs/<plugin_id>-<YYYY-MM-DD>.log`
— в том же каталоге, куда пишет собственная диагностика самого модуля
(`netwatch.log`), но под именем плагина, чтобы логи разных плагинов не
сливались в одну кашу и не пересекались с внутренними файлами модуля.
Годится, когда лог нужен рядом с логами модуля — например, общий
модерационный журнал, который ведут сразу несколько плагинов — а не
спрятанным в приватном каталоге одного плагина.

Файл — обычный текстовый файл в том же каталоге, что и `file.*` (для
плагинного лога), но [file.list()](../file/index.md#list) его не покажет:
`logs/` — отдельное хранилище.

<Warning>
  Неизвестное значение `level` — ошибка Lua, а не тихая запись без метки:
  опечатка в уровне ловится сразу, а не при попытке отфильтровать логи потом.
</Warning>

<Warning>
  `global = true` не выйти читать через `file.*` — та песочница нарочно не
  выходит за пределы каталога вызывающего плагина, а общий лог лежит выше
  него. Читать такой файл можно только руками на диске.
</Warning>

<Warning>
  Ротация — это только «новый файл на новый день». Старые файлы не удаляются
  автоматически, ни через сколько-то дней, ни по объёму. Если нужна очистка —
  плагин делает её сам через [file.remove](../file/index.md#remove) (или, если
  нужен доступ к `logs/` напрямую, через `os`), эта библиотека такого не
  предлагает намеренно, чтобы не терять чужие логи молча.
</Warning>

<Warning>
  `log.write` не дублирует сообщение в консоль. Для вывода, который должен
  увидеть человек прямо сейчас, — обычный `print`. `log` — это тихая, durable
  запись, а не альтернативная форма `print`.
</Warning>