https://github.com/usetech/labelgun
https://github.com/usetech/labelgun
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/usetech/labelgun
- Owner: Usetech
- License: mit
- Created: 2020-08-31T15:49:58.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-11-24T21:08:14.000Z (over 3 years ago)
- Last Synced: 2025-07-10T16:46:04.571Z (9 months ago)
- Language: Python
- Size: 83 KB
- Stars: 4
- Watchers: 4
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
labelgun
========
labelgun - это библиотека позволяющая в декларативном стиле объявлять события обрабатывающиеся в системе.
# Содержание
- [Установка](#Установка)
- [Внедрение в проект](#Внедрение-в-проект)
- [Потенциальные проблемы](#Потенциальные-проблемы)
- [Name clash](#Name-clash)
- [Разработка](#Разработка)
- [Настройка окружения](#Настройка-окружения)
- [Сборка дистрибутива](#Сборка-дистрибутива)
- [Генерация setup.py](#Генерация-setup.py)
- [Документация](#Документация)
- Установка базовой версии библиотеки
pip
```
pip install git+https://gitlab.usetech.ru/pub/labelgun.git
Установка заданной версии
pip install git+https://gitlab.usetech.ru/pub/labelgun.git@
```
poetry
```
poetry add git+https://gitlab.usetech.ru/pub/labelgun.git
```
- Установка библиотеки с зависимостями необходимыми для организации логирования
pip
```
pip install git+https://gitlab.usetech.ru/pub/labelgun.git#egg=labelgun[logger]
Установка заданной версии
pip install git+https://gitlab.usetech.ru/pub/labelgun.git@#egg=labelgun[logger]
```
poetry
```
poetry add git+https://gitlab.usetech.ru/pub/labelgun.git -E logger
```
**Extra Requirements**
- logger - устанавливает зависимости необходимые для организации логирования
- dev - устанавливает зависимости необходимые для разработки
**Важное замечание**
Если вы пытаетесь установить библиотеку из git при помощи poetry, убедитесь, что версия poetry у вас 1.1.5 или выше.
С младшими версиями могут возникать проблемы. Это связано с несколькими багами, которые были исправлены в последних
версиях.
Новые библиотеки внедрять в проект всегда тяжело, по этому, мы подготовили 2 простых проекта, которые показывают как
выполняется интеграция библиотеки и как ее можно использовать.
В этих проектах вы сможете найти примеры того как реализовать интеграцию structlog и logging, как реализовать
логирование в json, а так же как применять labelgun для структурирования логов.
**Чистый python проект**
Проект вы можете найти в папке `example/integrate_with_logging`.
Если вас интересует, как выполняется интеграция с logging и как конфигурируется подсистема логирования, то необходимо
посмотреть содержимое `examples/integrate_with_logging/logger.py`.
Для внедрения данного кода к себе в проект, нужно просто скопировать модуль `logger.py` в целевой проект и в точке
входа добавить вызов `init_logger`.
**Django проект**
Проект вы можете найти в папке `example/integrate_with_django`.
Как и в любом django проекте, конфигурирование логирования производится в settings.py, в разделе `Logger`. Начало и
конец этого раздела отделены от остальных настроек строкой из тире.
Если вам нужно интегрировать логирование в свой проект, то можете просто скопировать содержимое раздела `Logger` и
вставить его у себя.
При использовании библиотеки нужно быть осторожным с передачей параметров логгеру:
```python
class UserEvent(Label):
LEVEL_UP = "Обновляем уровень пользователю"
def update_user_level(**params):
if 'level' not in params:
params['level'] = calculate_new_level_for(user)
logger.log(**UserEvent.LEVEL_UP, **params)
print('level up!')
```
Подобный код полностью перезапишет параметр level для логгера. Следовательно,
нужно следить за передачей в structlog переменных, совпадающих по имени с переменными
событий: `label.category`, `event`, `label.description`, `level`.
Имена `event` и `level` не имеют префиксов, т.к. требуются для передачи логгеру.
Установка зависимостей
```
poetry install -E logger
```
```
make build
```
После каждого обновления pyproject.toml необходимо обновлять файл setup.py, чтобы была возможность установить библиотеку
из git репозитория и проекты не использующие poetry могли использовать ее.
Сделать это можно при помощи команды:
```
make build-setuppy
```
**structlog processor**
`labelgun.integrations.structlog_utils.dict_msg_processor`
Позволяет переложить конвертацию данных в строку на Formatter библиотеки logging. Данная возможность полезна при
внедрении structlog в приложение, где часть логов уже пишется при помощи библиотеки logging.
P.S. Иными словами, данный процессор служит заменой для structlog.dev.ConsoleRenderer или
structlog.processors.JSONRenderer и позволяет сказать библиотеке structlog, что данные, которые необходимо
залогировать сформированы и можно передать их дальше.
Данный процессор должен быть ВСЕГДА ПОСЛЕДНИМ в списке процессоров.
`labelgun.integrations.structlog_utils.convert_event_dict_to_str_processor`
Выполняет конвертацию "примитивных" типов в строки. Под примитивами понимаются числа, uuid, различные обертки
позволяющие выполнять точные расчеты (например Decimal) и т.д.
Помогает избежать проблемы, если логи вашего приложения загружаются в elasticsearch для анализа.
Пример решаемой проблемы:
Логи с нескольких сервисов собираются в одном индексе elasticsearch и каждый из этих сервисов в логах использует
переменную с одинаковым именем, но содержание у них разное. На пример в одном сервисе логируется user_id=1, а в
другом user_id='4v43gbv33'. В этом случае в elasticsearch попадут логи только того сервиса, сообщение от которого
будет обработано раньше. Это происходит потому, что индекс в elasticsearch типизирован и одно поле не может хранить
данные различных типов.