{"id":15062604,"url":"https://github.com/exitfound/lologen","last_synced_at":"2025-07-11T10:34:17.751Z","repository":{"id":256270713,"uuid":"847491741","full_name":"exitfound/lologen","owner":"exitfound","description":"Утилита для генерации искусственных журнальных сообщений для их последующей отправки в Loki.","archived":false,"fork":false,"pushed_at":"2024-11-15T22:00:15.000Z","size":24,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-15T22:29:03.981Z","etag":null,"topics":["grafana","logs","loki","promtail","python3","tools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exitfound.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-26T00:42:13.000Z","updated_at":"2024-11-15T21:58:31.000Z","dependencies_parsed_at":"2024-09-13T06:20:26.965Z","dependency_job_id":null,"html_url":"https://github.com/exitfound/lologen","commit_stats":null,"previous_names":["exitfound/lologen"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exitfound%2Flologen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exitfound%2Flologen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exitfound%2Flologen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exitfound%2Flologen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exitfound","download_url":"https://codeload.github.com/exitfound/lologen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225715909,"owners_count":17512909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grafana","logs","loki","promtail","python3","tools"],"created_at":"2024-09-24T23:43:27.020Z","updated_at":"2025-07-11T10:34:17.742Z","avatar_url":"https://github.com/exitfound.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Loki Log Generator**\n\n**Lologen** – это консольная утилита, написанная на Python и предназначенная для непрерывной генерации искусственных журнальных сообщений (они же logs). Основная цель заключается во взаимодействии с Loki (в рамках ознакомления с ним), а также тестировании его работоспособности путем отправки этих самых сгенерированных журнальных сообщений с помощью используемого вами агента, такого как Promtail и т.п. На текущий момент поддерживает некоторое колличество различных опций, которые позволят отправить ваши данные в Loki в том виде и формате, в каком вы пожелаете (в рамках доступной функциональности самого инструмента). Ниже представлено краткое содержание:\n\n- [Содержание:](loki-log-generator)\n  - [Мотивация](#мотивация)\n  - [Установка](#установка)\n    - [Из исходного кода](#из-исходного-кода)\n    - [С помощью Docker](#с-помощью-docker)\n    - [Бинарная версия](#бинарная-версия)\n  - [Подключение к Loki](#подключение-к-Loki)\n  - [Быстрый старт](#быстрый-старт)\n  - [Работа с утилитой](#работа-с-утилитой)\n  - [Сборка бинарного файла](#сборка-бинарного-файла)\n\n## **Мотивация:**\n\nМотивацией к написанию данной утилиты послужил исключительно образовательный интерес, поэтому я не думаю, что сей инструмент хоть сколько-то можно использовать в производственной среде. Тем не менее когда у нас есть развернутый экземпляр Loki и мы хотим разобраться с какой-то его функциональностью, хотелось бы (во всяком случае мне) иметь что-то большее в лице полезной нагрузки, чем пресловутый контейнер Nginx в качестве примера, который затем мы дернем curl'ом и получим сообщение в одну строку. Такой подход просто покажет, что Loki, в сочетании с используемым агентом и визуализатором, как Grafana, работает и больше ничего. Однако любые чуть более специфические требования, такие как принудительная отправка данных в stderr или запись в файл, а также указание используемого формата журнальных сообщений и т.д. будут недоступны, если только у вас нет своего приложения, которое уже будет содержать в себе нужные вам компоненты для желаемого тестирования. Эту потребность и пытается закрыть данный инструмент. Сильно в Интернете я не искал, так что возможно и существуют более внятные аналоги. Мне же было интересно написать утилиту с нуля, которая подходила бы под мои требования в рамках взаимодействия с Loki.\n\n## **Установка:**\n\nДля успешного взаимодействия с данной утилитой необходимо обладать минимальным количеством программных коммпонентов и вспомогательных инструментов. В частности, это:\n\n- `Python` версии 3 для запуска непосредственно самой утилиты, а также ряд зависимостей, которые перечислены в файле `requirements.txt`;\n\n- `Git` с помощью которого вами будет загружен репозиторий из Github;\n\n- `Wget`, `curl` и `jq`, которые понадобятся для загрузки бинарной версии из релиза (опциональный вариант использования);\n\n- `Grafana Stack` как инструмент агрегации и визуализации журнальных сообщений (опционально, поскольку утилита самодостаточна и ничто не запрещает её использовать просто так);\n\n### **Из исходного кода:**\n\nЧтобы начать работу с исходной версией приложения достаточно выполнить следующую последовательность команд:\n\n```\ngit clone https://github.com/exitfound/lologen.git\ncd lologen\npip3 install --user -r requirements.txt\npython3 lologen.py -h\n```\n\n### **С помощью Docker:**\n\nОбраз основан на базе Distroless от [GoogleContainerTools](https://github.com/GoogleContainerTools). В примере c тэгом `main` используется базовый образ `python3-debian12`, который хоть и является легковесным, всё же содержит в себе интепретатор Python. В случае с бинарной версией, с тэгом `binary`, используется базовый образ `base-debian12`. Благодаря этому удалось получить образ с минимально допустимым размером, что по меркам Python довольно-таки неплохо. Результат представлен в примере ниже:\n\n```\ndocker images\n\nREPOSITORY         TAG       IMAGE ID       CREATED         SIZE\nmdd13/lologen      main      8bb8e746c3e7   1 minutes ago   57.3MB\nmdd13/lologen      binary    25734e3606f2   1 minutes ago   27.6MB\n```\n\nИтак, в рамках работы с Docker можно прибегнуть к трем вариантам запуска утилиты:\n\n- Забрать готовый образ на базе `python3-debian12` из репозитория Docker Hub:\n\n```\ndocker run -d --name lologen mdd13/lologen:main\n```\n\n- Собрать образ на базе `python3-debian12` локально и запустить его в своей системе:\n\n```\ndocker build -t \"lologen:main\" .\ndocker run -d --name lologen lologen:main\n```\n\n- Собрать образ на базе `python3-debian12` с помощью Docker Compose (предварительно изменив файл Docker Compose под локальную сборку):\n\n```\ndocker compose up -d --build\n```\n\n### **Бинарная версия:**\n\nДанный метод основан на упаковке Python-скрипта в бинарный файл с помощью инструмента `Pyinstaller`. Сам бинарный файл хранится в релизе. Чтобы начать работу с бинарной версией необходимо выполнить следующую последовательность команд:\n\n```\nwget https://github.com/exitfound/lologen/releases/latest/download/lologen_linux_amd64.zip\nunzip lologen_linux_amd64.zip\nsudo mv lologen /usr/local/bin/\nlologen -h\n```\n\nПримечание: Альтернативный путь, по которому также можно забрать архив с бинарным файлом:\n\n```\nwget $(wget -q -O - https://api.github.com/repos/exitfound/lologen/releases/latest | jq -r '.assets[] | select(.name | contains (\"lologen\")) | .browser_download_url')\n```\n\nКо всему прочему бинарная версия утилиты была упакована в Docker образ. Концептуально ничем не отличается в плане своей функциональности от основной версии утилиты (с тэгом `main`), за тем лишь исключением, что в качестве базового образа используется более легковесная версия образа Distroless в лице `base-debian12`. Поскольку мы используем бинарный формат, нам не нужен интерпретатор Python как такого. За счет этого удалось уменьшить финальный варианта используемого нами образа в два раза. В остальном всё идентично:\n\n```\ndocker run -d --name lologen mdd13/lologen:binary\n```\n\nИ вы также можете собрать данную версию образа локально, как вручную:\n\n```\ndocker build -f ./binary/binary.dockerfile -t \"lologen:binary\" .\ndocker run -d --name lologen-binary lologen:binary\n```\n\nТак и с помощью Docker Compose (предварительно изменив файл Docker Compose под локальную сборку):\n\n```\ndocker compose -f ./binary/binary.docker-compose.yaml up -d --build\n```\n\n## **Подключение к Loki:**\n\nВообще как именно вы будете настраивать метод отправки информации о журнальных сообщениях зависит от используемого вами стека технологий. В конце концов, во всяком случае в теории, данной утилите нет до этого дела. Она просто пишет журнальные сообщения в том виде и туда, куда вы скажете в рамках той среды, в которой она была запущена. Однако на примере используемого мною Grafana Stack (Loki, Promtail и Grafana) я оставлю краткое руководство по сбору и отправке журнальных сообщений из запущенного контейнера. Вообще существует два способа по настройке сбора журнальных сообщений для контейнеров: `Driver Loki` для Docker и `Scraping` через Promtail. Я предпочитаю первый вариант и моём docker-compose файле это уже отражено. Выглядит следующим образом:\n\n```\n    # Driver variant\n    logging:\n      driver: loki\n      options:\n        loki-url: \"http://172.17.0.1:3100/loki/api/v1/push\"\n        loki-retries: \"3\"\n        loki-pipeline-stages: |\n          - json:\n              expressions:\n                level:\n          - regex:\n              expression: '(level|levelname|level_extracted|lvl|severity)=(?P\u003clevel\u003e\\w+)'\n          - labels:\n              level:\n```\n\nВ данном случае мы указываем конечный URL-адрес запущенного нами Loki, а также делаем преобразование имён для поля level, на тот случай, если имя по умочланию будет отличаться в строке журнальных сообщений. В противном случае Grafana, в паре с Loki, не сможет отрисовать это должным образом. В общем данный пример является полностью рабочим для файла Docker Compose, только предварительно необходимо установить сам `Driver Loki`. Но вы также можете использовать `Scraping`, указав вместо примера выше вот такую конфигурацию:\n\n```\n    # Scrape variant:\n    labels:\n      name: \"lologen\"\n```\n\nПравда просто так это работать не будет. Конфигурационный файл вашего агента Promtail должен содержать информацию о `Scraping` для Docker:\n\n```\nscrape_configs:\n  - job_name: docker_scrape\n    docker_sd_configs:\n      - host: unix:///var/run/docker.sock\n        refresh_interval: 5s\n    relabel_configs:\n      - source_labels: ['__meta_docker_container_name']\n        regex: '/(.*)'\n        target_label: 'container'\n      - source_labels: ['__meta_docker_container_log_stream']\n        target_label: 'stream'\n      - source_labels: ['__meta_docker_container_label_name']\n        target_label: 'name'\n```\n\nЕсли представленная выше информация вам ни о чем не говорит, в таком случае я рекомендую прочитать написанную мною статью по тому, как собирать журнальные сообщения из контейнеров, запущенных в среде Docker – [тык](https://t.me/opengrad/117). Вы также можете обратиться к официальной документации Loki. Если же вы используете другой стэк технологий, тогда вам нужно знать только то, как работать с данной утилитой.\n\n## **Быстрый старт:**\n\nИспользуйте следующую команду (в зависимости от применяемого метода запуска), чтобы запустить генерацию журнальных сообщений с параметрами по умолчанию, которые указаны в файле docker-compose (там же их можно и изменить при работе с Docker):\n\n```\npython3 lologen.py\ndocker run -d --name lologen mdd13/lologen:main\ndocker run -d --name lologen mdd13/lologen:binary\nlologen\n```\n\n## **Работа с утилитой:**\n\nНиже будет представлено более подробное руководство по работе с данной утилитой. В первую очередь стоит отметить, что некоторые опции обладают несколькими возможными к использованию параметрами. Походу дела каждый из существующих параметров будет рассмотрен. Итак, как уже было отмечено ранее, чтобы вызвать `help`, достаточно запустить утилиту со следующим флагом (в примере будет представлен лишь один из вариантов запуска, но параметры идентично применимы ко всем возможным вариантам, которые были упомянуты выше):\n\n```\npython3 lologen.py -h\n```\n\nПо умолчанию утилита использует режим `console` (отправка в `std`) при работе с хендлером (отвечающий за отправку журнальных сообщений). Вы можете задать желаемый режим самостоятельно. На данный момент поддерживается четыре режима отправки: `console` (он же std), `file` (запись в произвольный файл в системе), `journald` (запись в journalctl systemd) и `http` (отправка журнальных сообщений веб-серверу). Чтобы указать желаемый режим используйте флаг `-t` при работе с утилитой:\n\n```\npython3 lologen.py -t [console|file|journald|http]\n```\n\nПри использовании флага `-t` с параметром `http` вы также можете использовать флаг `-W`, который активирует встроенный Web-сервер, на который, собственно, и будут отправляться журнальные сообщения. Например:\n\n```\npython3 lologen.py -t http -W\n```\n\nПредставленный выше пример это работа с Web-сервером по умолчанию, однако вы также можете указать произвольные значения (считай любой другой Web-сервер), использовав для этого такие ключи, как `-H` и `-P` (хост и порт). По желанию также можно указать один из двух методов – `GET` или `POST`. Выглядеть будет следующим образом:\n\n```\npython3 lologen.py -t http -H yourdomain_or_ip -P 8080 -M POST\n```\n\nЕсли вы выбрали `console` в качестве режима отправки данных, возможнно, что вы захотите указать тип потока (`stream`). Их тоже может быть два: `stdout` и `stderr`. По умолчанию журнальные сообщения отправляются в `stdout`, но это можно изменить с помощью флага `-s`:\n\n```\npython3 lologen.py -t console -s [stdout|stderr]\n```\n\nЕсли же вы выбрали отправку данных в `file`, в таком случае вы также можете указать путь к файлу, куда будут отправляться журнальные сообщения. По умолчанию это домашний каталог + имя файла в лице `spam_application.log`. Однако с помощью флага `-p` вы можете указать любой необходимый вам путь (только для некоторых путей могут понадобится допольнительные права на запись):\n\n```\npython3 lologen.py -t file -p /var/log/lologen.log\n```\n\nВне зависимости от используемого режима отправки данных каждое журнальное сообщение, так или иначе, выражено в определенном формате. На данный момент консольная утилита поддерживает три формата журнальных сообщений: это `logfmt` (по умолчанию), `JSON` и `unstructured` (простая строка, без каких либо полей, по типу журнального сообщения Nginx). Используйте флаг `-f` для указания желаемого формата журнальных сообщений:\n\n```\npython3 lologen.py -t console -s stdout -f [json|logfmt|unstructured]\n```\n\nИ, как и в случае с форматом, вне зависимости от используемого типа отправки данных, у всех журнальных сообщений, так или иначе, присутствует уровень логирования. В нашем случае мы можем указать минимальный уровень журнального сообщения, который хотим видеть при отправке, например, в `std`. По умолчанию отправляются журнальные сообщения всех уровней, вплоть до `DEBUG`, но изменить это можно с помощью флага `-l`:\n\n```\npython3 lologen.py -t console -s stdout -f json -l [debug|info|warning|error|critical]\n```\n\nПомимо всего прочего можно также указать желаемый интервал времени, после которого будет отправлено новое журнальное сообщение. По умолчанию следующее сообщение отправляется спустя две секунды после того, как было отправлено предыдущее. Параметр поддерживает значение с плавающей запятой, так что можно даже указать интервал в 0,5 секунд, для ускоренной отправки данных. Чтобы сделать это используйте флаг `-T`:\n\n```\npython3 lologen.py -t console -s stdout -f json -l warning -T 0.5\n```\n\nПоследние две опции по своей природе являются максимально опциональными. Первая позволяет задать произвольное имя для создаваемого логера. По умолчанию это `spam_application`. Задать своё имя можно с помощью флага `-n`:\n\n```\npython3 lologen.py -t console -s stdout -f json -l warning -T 0.5 -n my_log_output\n```\n\nТогда как с помощью второй опции, при желании, можно окрасить в определенный цвет содержимое поля `msg` в журнальном сообщении. По сути это наша полезная нагрузка, где в зависимости от установленного уровня логирования мы получаем соответствующий текст. Обладает двумя параметрами: `always` и `never`. По умолчанию окрашивание текста включено всегда. Если вы хотите отключить его используйте флаг `-c`:\n\n```\npython3 lologen.py -t console -s stdout -f json -l warning -T 0.5 -n my_log_output -c never\n```\n\nНапоминаю, что все представленные опции также применимы и по отношению к бинарному файлу, и по отношению к запускаемым образам Docker. Кстати говоря, в контексте Docker, в качестве точки входа установлен запуск самой утилиты, так что если вы захотите изменить значения по умолчанию, необходимо после установленного имени образа указать необходимый список опций. Например:\n\n```\ndocker run -d --name lologen mdd13/lologen:main -t console -s stdout -f json -l warning -T 0.5 -n my_log_output -c never\ndocker run -d --name lologen mdd13/lologen:binary -t console -s stderr -f logfmt -l info -T 1 -n my_log_output -c always\n```\n\nЧто же касается Docker Compose, то все опции можно передать через `command` внутри описываемого файла:\n\n```\nversion: '3.7'\nservices:\n  lologen:\n    command: [ \"-f\", \"json\", \"-l\", \"info\", \"-s\", \"stdout\", \"-t\", \"console\", \"-T\", \"2\", \"-c\", \"always\"]\n```\n\n## **Запуск тестов**\n\nДля запуска тестов воспользуйтесь следующей командой (необходимо установить зависимости для запуска):\n\n```\npytest tests/\n```\n\nДля получения полной информации по покрытию кода тестами необходимо выполнить следующую команду:\n\n```\npytest  --cov=./ --cov-report=html\n```\n\n## Сборка бинарного файла:\n\nЕсли у вас возникла потребность в самостоятельной сборке бинарного файла, можете воспользоваться следующей командой:\n\n```\npip3 install --user -r requirements.txt\npython3 -m PyInstaller --onefile --noconfirm --clean --name lologen lologen.py\n./dist/lologen -h\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexitfound%2Flologen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexitfound%2Flologen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexitfound%2Flologen/lists"}