Мониторинг Python приложений с помощью Proto Observability Platform

На этой странице:

• Введение
• Установка Python трейсера
  • Если приложение запускается в Docker контейнере
  • Если приложение работает в Kubernetes
    • Без использования автоматического подключения трейсера
    • С использованием автоматического подключения трейсера
    • Автоматическое подключение трейсера без использования лейблов
• Поддерживаемые технологии трейсером
  • Версии Python
  • Автоматическая инструментация библиотек и фреймворков
  • Хранилища данных
  • Библиотеки
• Дополнительная инструментация вызовов
• Кастомные метрики Python приложений
  • Типы кастомных метрик

Введение

Общий процесс подключения Python приложения на мониторинг:

1. Установка ProtoOBP Агента
2. Установка трейсера

Установка Python трейсера

1. Установите библиотеку pobptrace выполнив:

   pip install pobptrace --user --index-url "https://<token_name>:<token_key>@git.proto.group/api/v4/projects/125/packages/pypi/simple"
   

   Пример для Dockerfile и .gitlab-ci.yml:

   • в настройках проекта в Gitlab добавьте две переменные окружения (Проект -> Settings -> CI/CD -> Variables):

     • имя: PROTOOBP_INSTALL_TOKEN_NAME, значение = ваши данные из лицензионного сертификата (token или логин)
     • имя: PROTOOBP_INSTALL_TOKEN_KEY, значение = ваши данные из лицензионного сертификата (пароль)

   Имя и значение токена находятся в вашем лицензионном сертификате Proto Observability Platform.

   • .gitlab-ci.yml – необходимо передать значения переменных от Gitlab CI к docker build через --build-arg:

       script:
         - docker build --build-arg PROTOOBP_INSTALL_TOKEN_NAME=${PROTOOBP_INSTALL_TOKEN_NAME} --build-arg PROTOOBP_INSTALL_TOKEN_KEY=${PROTOOBP_INSTALL_TOKEN_KEY} .
     

   • Dockerfile – необходимо добавить переменные окружения через ARG и передать их в pip install --index-url:

     FROM python:latest
     ARG PROTOOBP_INSTALL_TOKEN_NAME
     ARG PROTOOBP_INSTALL_TOKEN_KEY
     RUN pip install pobptrace --user --index-url "https://${PROTOOBP_INSTALL_TOKEN_NAME}:${PROTOOBP_INSTALL_TOKEN_KEY}@git.proto.group/api/v4/projects/125/packages/pypi/simple"
     

2. Добавьте pobptrace-run команду как entrypoint вашего приложения. Например:

   pobptrace-run python app.py
   

   • Пример для типового Python приложения:

     CMD ["pobptrace-run", "python", "app.py"]
     

   • Пример для uwsgi и Dockerfile:

     CMD ["pobptrace-run", "uwsgi", "--ini", "app.ini"]
     

3. Добавьте следующие переменные окружения:

   • POBP_AGENT_HOST – адрес Агента, на который будет отсылать данные трейсер
   • POBP_SERVICE=<service_name> – имя сервиса, как он будет отображаться в интерфейсе Proto Observability Platform
   • POBP_TRACE_TELEMETRY_ENABLED="false" – обязательно

Если приложение запускается в Docker контейнере

Выполните пункты указанные выше и добавьте следующие переменные окружения:

• POBP_AGENT_HOST – адрес Агента, на который будет отсылать данные трейсер:
  • если Агент запущен в Docker контейнере, укажите имя Docker контейнера Агента:

    ENV POBP_AGENT_HOST="protoobp-agent"
    

    Убедитесь, что контейнер Агента и контейнер приложения находятся в одной Docker сети. Адрес агента должен быть доступен из Docker контейнера приложения.
  • если Агент запущен на хосте как сервис (не в контейнере):

    ENV POBP_AGENT_HOST="host.docker.internal"
    

    Убедитесь что в конфигурации Агента разрешен прием APM данных от контейнеров:

    apm_config:
      apm_non_local_traffic: true
    

• POBP_SERVICE – имя сервиса, которое будет отображаться в интерфейсе Proto OBP:

  ENV POBP_SERVICE="my_service_name"
  

• POBP_TRACE_TELEMETRY_ENABLED – установите в false

  ENV POBP_TRACE_TELEMETRY_ENABLED="false"
  

Пример полного Dockerfile:

FROM python:latest

WORKDIR /
COPY requirements.txt .

ARG PROTOOBP_INSTALL_TOKEN_NAME
ARG PROTOOBP_INSTALL_TOKEN_KEY

RUN pip install pobptrace --user --index-url "https://${PROTOOBP_INSTALL_TOKEN_NAME}:${PROTOOBP_INSTALL_TOKEN_KEY}@git.proto.group/api/v4/projects/125/packages/pypi/simple"
RUN pip install -r requirements.txt --user

ENV POBP_SERVICE="hello-world"
ENV POBP_AGENT_HOST="protoobp-agent" 
ENV POBP_TRACE_TELEMETRY_ENABLED="false"

CMD ["pobptrace-run", "python", "app.py"]

Если приложение работает в Kubernetes

Убедитесь, что у вас успешно установлен и настроен ProtoOBP Агент для Kubernetes.

Без использования автоматического подключения трейсера

Дополнительно необходимо передать поду переменную окружения POBP_AGENT_HOST со значением IP адреса воркер-ноды, а также переменные окружения для связи трейсов с инфраструктурой (имя k8s кластера нужно задать вручную).

apiVersion: apps/v1
kind: Deployment
#(...)
    spec:
      containers:
      - name: "<CONTAINER_NAME>"
        image: "<CONTAINER_IMAGE>/<TAG>"
        env:
          - name: POBP_SERVICE
            value: dispatch			
          - name: POBP_AGENT_HOST
            valueFrom:
              fieldRef:
                fieldPath: status.hostIP
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: POD_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
          - name: POD_NAME
            valueFrom:
              fieldRef:
                fieldPath: metadata.name
          - name: POBP_TAGS
            value: "pod_name:$(POD_NAME),node:$(NODE_NAME),kube_namespace:$(POD_NAMESPACE),kube_cluster_name:<my_cluster_name>"            
            

С использованием автоматического подключения трейсера

Агент ProtoOBP в K8s кластере по умолчанию инструментирует Python приложения с лейблом: admission.proto.group/enabled: "true"

1. В спецификации пода приложения добавьте анотацию и лейбл с версией Python трейсинг агента:

   apiVersion: apps/v1
   kind: Deployment
   metadata:
    labels:
    ...
   ...
   template:
      metadata:
        annotations:
          admission.proto.group/python-lib.version: "2.3.0" #Если Версия Python < 3.7, тогда необходимо указать версию "v1"
        creationTimestamp: null
        labels:
          admission.proto.group/enabled: "true" # Включение автоматической инструментации
          tags.proto.group/service: "my_service" #Укажите имя сервиса
          service: my_service
   

2. В спецификации пода добавьте imagePullSecrets для доступа к Docker репозиторию ProtoOBP. Подробнее о добавление Secret указано в документации Установка агента в Kubernetes

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     labels:
     ...
   ...
    template:
       metadata:
         annotations:
           admission.proto.group/python-lib.version: "2.3.0" #Если Версия Python < 3.7, тогда необходимо указать версию "v1"
         creationTimestamp: null
         labels:
           admission.proto.group/enabled: "true" # Включение автоматической инструментации
          service: my_service
      spec:
         containers:
            ...
         ...
         imagePullSecrets:
         - name: protoobp-registry
   

Автоматическое подключение трейсера без использования лейблов

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

Поддерживаемые технологии трейсером

Версии Python

Поддерживает CPython версий 2.7, 3.5-3.10.

Автоматическая инструментация библиотек и фреймворков

Хранилища данных

Библиотеки

Дополнительная инструментация вызовов

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

Для примера будет использоваться следующий код приложения:

def make_sandwich_request(request):
    ingredients = get_ingredients()
    sandwich = assemble_sandwich(ingredients)

• Способ:
• Декоратор
• Context Manager
• Ручной

@tracer.wrap(service="my-sandwich-making-svc", resource="resource_name")
def get_ingredients():
    # сходить в кладовку
    # сходить к холодильнику
    # может быть сходить в магазин
    return

# можно добавить больше данных для кастомизации спана
@tracer.wrap("assemble_sandwich", service="my-sandwich-making-svc", resource="resource_name")
def assemble_sandwich(ingredients):
    return

from pobptrace import tracer

def make_sandwich_request(request):
    # запишем обе операции в спаны
    with tracer.trace("sandwich.make"):
        ingredients = get_ingredients()
        sandwich = assemble_sandwich(ingredients)

def make_sandwich_request(request):
    # запишем обе операции в спаны
    with tracer.trace("sandwich.create", resource="resource_name") as outer_span:

        with tracer.trace("get_ingredients", resource="resource_name") as span:
            ingredients = get_ingredients()

        with tracer.trace("assemble_sandwich", resource="resource_name") as span:
            sandwich = assemble_sandwich(ingredients)

from pobptrace import tracer
def make_sandwich_request(request):
    span = tracer.trace("sandwich.create", resource="resource_name")
    ingredients = get_ingredients()
    sandwich = assemble_sandwich(ingredients)
    span.finish()  # не забудьте закрыть спан

Кастомные метрики Python приложений

Кастомные, например, бизнес-метрики, можно генерировать напрямую из приложения и отсылать на Агента.

1. Подключите библиотеку protoobp выполнив:

   pip install protoobp --user --index-url "https://<token_name>:<token_key>@git.proto.group/api/v4/projects/125/packages/pypi/simple"
   

   имя и значение токена находятся в вашем лицензионном сертификате Proto Observability Platform.

   Пример для Dockerfile и .gitlab-ci.yml:

   • в настройках проекта в Gitlab добавьте две переменные окружения (Проект -> Settings -> CI/CD -> Variables):

     • имя: PROTOOBP_INSTALL_TOKEN_NAME, значение = ваши данные из лицензионного сертификата (token или логин)
     • имя: PROTOOBP_INSTALL_TOKEN_KEY, значение = ваши данные из лицензионного сертификата (пароль)

   • .gitlab-ci.yml – необходимо передать значения переменных от Gitlab CI к docker build через --build-arg:

       script:
         - docker build --build-arg PROTOOBP_INSTALL_TOKEN_NAME=${PROTOOBP_INSTALL_TOKEN_NAME} --build-arg PROTOOBP_INSTALL_TOKEN_KEY=${PROTOOBP_INSTALL_TOKEN_KEY} .
     

   • Dockerrfile – необходимо добавить переменные окружения через ARG и передать их в pip install --index-url:

     FROM python:latest
     ARG PROTOOBP_INSTALL_TOKEN_NAME
     ARG PROTOOBP_INSTALL_TOKEN_KEY
     RUN pip install protoobp --user --index-url "https://${PROTOOBP_INSTALL_TOKEN_NAME}:${PROTOOBP_INSTALL_TOKEN_KEY}@git.proto.group/api/v4/projects/125/packages/pypi/simple"
     

2. Инициализируйте StatsD клиента, используя UDP в коде приложения:

   from protoobp import initialize, statsd
   
   options = {
       "statsd_host": "127.0.0.1",
       "statsd_port": 8125,
   }
   
   initialize(**options)
   

3. Теперь можно добавлять собственные метрики, пример использования:

   from protoobp import initialize, statsd
   import time
   
   options = {
       'statsd_host':'127.0.0.1',
       'statsd_port':8125
   }
   
   initialize(**options)
   
   while(1):
     statsd.increment('example_metric.increment', tags=["environment:dev"])
     statsd.decrement('example_metric.decrement', tags=["environment:dev"])
     time.sleep(10)
   

Типы кастомных метрик

После установки библиотеки для отправки метрик в Protoobp будут доступны следующие функции в зависимости от типа метрик. Функции имеют следующие общие параметры:

1. COUNT

   • increment(<METRIC_NAME>, <SAMPLE_RATE>, <TAGS>)
     Используется для увеличения значения метрики типа COUNT.

   • decrement(<METRIC_NAME>, <SAMPLE_RATE>, <TAGS>)
     Используется для уменьшения значения метрики типа COUNT.

   Пример:

   from protoobp import initialize, statsd
   import time
   
   options = {
       'statsd_host':'127.0.0.1',
       'statsd_port':8125
   }
   
   initialize(**options)
   
   while(1):
     statsd.increment('example_metric.increment', tags=["environment:dev"])
     statsd.decrement('example_metric.decrement', tags=["environment:dev"])
     time.sleep(10)
   

   Обратите внимание

   Не забудьте сделать flush / close клиента, когда он уже более не нужен.

2. GAUGE

   • gauge(<METRIC_NAME>, <METRIC_VALUE>, <SAMPLE_RATE>, <TAGS>)

   Пример:

   from protoobp import initialize, statsd
   import time
   
   options = {
       'statsd_host':'127.0.0.1',
       'statsd_port':8125
   }
   
   initialize(**options)
   
   i = 0
   
   while(1):
     i += 1
     statsd.gauge('example_metric.gauge', i, tags=["environment:dev"])
     time.sleep(10)
   

   Обратите внимание

   Не забудьте сделать flush / close клиента, когда он уже более не нужен.

3. HISTOGRAM

   • histogram(<METRIC_NAME>, <METRIC_VALUE>, <SAMPLE_RATE>, <TAGS>)
     Отправляются агрегаты max, median, avg и count.
     Отправляется 95-й перцентиль.

   Пример:

   from protoobp import initialize, statsd
   import time
   import random
   
   options = {
       'statsd_host':'127.0.0.1',
       'statsd_port':8125
   }
   
   initialize(**options)
   
   while(1):
     statsd.histogram('example_metric.histogram', random.randint(0, 20), tags=["environment:dev"])
     time.sleep(2)   
   

   Обратите внимание

   Не забудьте сделать flush / close клиента, когда он уже более не нужен.

   Пример выше создаст следующие метрики:

   Метрика	Описание
   example_metric_histogram_count	Количество раз сбора метрики
   example_metric_histogram_avg	Среднее из собранных значений
   example_metric_histogram_median	Медианное значение собранных значений
   example_metric_histogram_max	Максимум среди собранных значений
   example_metric_histogram_95percentile	95-й перцентиль собранных значений