Работа с метриками и логами в качестве разработчика

Сначала ознакомьтесь с нашим документом по мониторингу для получения обзора того, что Baserow предлагает для самомониторинга.

Этот документ объясняет, как:

1. Настроить вашу среду разработки, чтобы вы могли мониторить ее, находить проблемы производительности и т.д.
2. Добавлять новые логи в кодовую базу и когда это делать.
3. Что такое трассировка и как добавлять новые трассировки ваших функций.
4. Добавлять новые метрики в кодовую базу и когда это делать.

Настройка Honeycomb для просмотра телеметрии Baserow в вашей локальной среде разработки

1. Зарегистрируйтесь на https://honeycomb.io.
2. Создайте свою собственную среду внутри Honeycomb, вы настроите свою локальную среду разработки для отправки событий сюда.
3. Нажмите на вашу новую среду в боковой панели, затем нажмите значок конфигурации.
4. Перейдите к API-ключам и скопируйте ваш API-ключ.
5. Отредактируйте ваш локальный .env и установите:

HONEYCOMB_API_KEY=YOUR_KEY
BASEROW_ENABLE_OTEL=true

6. ./dev.sh restart
7. Перейдите в вашу среду Honeycomb, и вы должны начать видеть создание новых наборов данных!

Отладка телеметрии

Посмотрите логи вашего otel-collector для начала:

docker logs baserow-otel-collector-1

Под капотом

• docker-compose.dev.yml также запускает службу Open Telemetry Collector с конфигурацией из файла deploy/otel/otel-collector-config.yaml.
• Когда вы включаете телеметрию с помощью BASEROW_ENABLE_OTEL=true, контейнеры разработки настраиваются с помощью OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 в docker-compose.dev.yml для отправки телеметрии этому локальному коллекционеру.
• Затем этот локальный коллекционер отправляет телеметрию в Honeycomb с использованием вашего HONEYCOMB_API_KEY, где вы можете наконец просмотреть все.

Как логировать

Чтобы записать что-то в лог, просто:

from loguru import logger

def application_code():
   logger.info('что-то')

См. документацию Loguru для получения дополнительной информации, она имеет множество отличных функций.

Когда и что логировать

По состоянию на февраль 2023 года Baserow не логирует много информации. Теперь у нас есть более удобная система логирования loguru и способ отправки и хранения логов с использованием OTEL, поэтому мы должны логировать гораздо больше.

1. Логируйте для людей, чтобы они могли диагностировать, что произошло в Baserow.
2. Используйте различные уровни логирования, доступные вам: error/warning/info/debug/trace.
3. Не бойтесь добавлять слишком много логов.

Как добавлять трассировки для запросов и производительности методов

Сначала прочитайте это для понимания, что такое трассировка и трассировка и почему мы хотим их использовать.

Трассировка функции

Вы можете использовать вспомогательный декоратор baserow_trace для обертывания функции в трассировку, чтобы отслеживать время ее выполнения и другие атрибуты:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)


class SomeClass:
    @baserow_trace(tracer)
    def my_func(
            self
    ):
        # выполните дорогостоящую операцию, которую мы хотим отслеживать
        pass

@baserow_trace будет:

1. Оборачивать функцию в трассировку.
2. Устанавливать имя трассировки автоматически на имя модуля функции + квалифицированное имя функции.
3. Перехватывать ошибки, помечать трассировку как неудачную и регистрировать исключение против трассировки, чтобы оно отправлялось коллекционеру.

Трассировка всех методов в классе

Вместо того, чтобы аннотировать каждый метод в классе с @baserow_trace, вы можете использовать функцию baserow_trace_methods, которая генерирует метакласс, делающий это за вас. По умолчанию, он будет трассировать все методы в классе, не начинающиеся с _.

baserow_trace_methods также поддерживает параметры only и exclude, которые позволяют ограничивать, какие именно методы трассировать.

from opentelemetry import trace

tracer = trace.get_tracer(__name__)


class SomeClass(metaclass=baserow_trace_methods(tracer)):
    def a(self):
        pass

    def b(self):
        pass

    def c(self):
        pass

    def d(self):
        pass

Это очень полезно при работе с классом, имеющим абстрактные методы, которые будут реализованы многими подклассами (что мы часто делаем в Baserow).

См. ниже пример того, как можно трассировать каждую реализацию метода .do для абстрактного базового класса!

import abc
from opentelemetry import trace

tracer = trace.get_tracer(__name__)


class ActionType(metaclass=baserow_trace_methods(tracer, abc=True, only='do')):
    @abc.abstractmethod
    def do(self):
        # Каждый подкласс ActionType будет иметь свой метод `do` трассированным!
        pass

    def b(self):
        pass

    def c(self):
        pass

    def d(self):
        pass

Добавление атрибутов к текущей трассировке

Часто очень полезно добавлять атрибуты к текущей трассировке, чтобы фильтровать и запрашивать их позже при просмотре телеметрии. У нас есть простая вспомогательная функция, которая позволяет это сделать:

add_baserow_trace_attrs(
    attr_you_want_on_the_span=value_you_want,
    other_attr=other_value
)

Или вы можете использовать стандартные методы OTEL:

span = get_current_span()
span.set_attribute(f"baserow.my_span_attr", value)

Использование OTEL API напрямую

Помните, что вы также можете использовать API OTEL Python напрямую. Вспомогательные функции, показанные выше, просто помогают вам.

Как отслеживать метрики

Вы также можете отслеживать различные числовые и статистические метрики с использованием Open Telemetry. Мы не предоставляем никаких вспомогательных методов, так как функции OTEL достаточно просты. Прочитайте это для ознакомления со всеми доступными типами метрик, которые вы можете использовать, но ниже приведен простой пример:

Важно: Любые атрибуты, которые вы добавите к метрике, приведут к отправке нового события при каждом периодическом отправке метрик для конкретной комбинации метрики и атрибутов. Вы должны убедиться, что любые добавленные атрибуты имеют только постоянное количество возможных значений и небольшое количество таких значений. Это необходимо для предотвращения бесконечного увеличения количества отправляемых метрических событий.

Например, если мы вызовем counter.add(1, {"table_id":table.id}), OTEL будет отправлять метрическую точку данных для каждой таблицы, которую он видел при каждом синхронизации, что приведет к бесконечному увеличению количества отправляемых метрических событий. Однако, если вместо этого атрибутом будет что-то вроде "bulk_created": True или False, это нормально, так как возможных значений всего два.

from opentelemetry import metrics

meter = metrics.get_meter(__name__)
rows_created_counter = meter.create_counter(
    "baserow.rows_created",
    unit="1",
    description="Количество созданных строк в пользовательских таблицах.",
)

def create_row(table):
    # создайте некоторую строку
    # отслеживайте количество созданных строк!
    rows_created_counter.add(
        1
    )

traceidratio и принудительная полная трассировка

Если вы установили сэмплер трассировщика с помощью traceidratio, то не каждый запрос будет иметь полную трассировку.

OTEL_TRACES_SAMPLER_ARG: "0.1"
OTEL_TRACES_SAMPLER: "traceidratio"

Это может затруднить отладку конкретного запроса. Поэтому мы реализовали параметр запроса, который позволяет принудительно выполнить полную трассировку. Вы можете добавить ?force_full_otel_trace=true к любому запросу на бэкенд, чтобы получить полную трассировку.