Мониторинг при локальной разработке

Наблюдатель подключается не только к production, но и к приложению на вашем компьютере: в Docker Compose, обычным процессом (npm run dev, dotnet run, go run, uvicorn) или в локальном Kubernetes — Docker Desktop, kind, minikube, k3d. Агент сам ходит в облако по исходящему соединению, поэтому ноутбук за NAT подключается так же, как сервер. Открывать порты наружу не нужно.

Зачем мониторинг при локальной разработке:

• куда уходит время в запросе — эндпоинт, запросы к базе, вызовы других сервисов (трассировка);
• N+1 и медленный SQL — до того, как код попал в production (запросы к базе данных);
• исключения с трейсбеком и группировкой (ошибки приложения);
• что приложение пишет в события, логи и метрики — проверить отправку до выкладки (события и логи, метрики приложения).

#Отдельный проект «— локально»

Заведите для локальной машины отдельный проект, например «Магазин — локально», и в нём стек local. Не добавляйте локальный стек в боевой проект: правила и каналы уведомлений общие на весь проект. Иначе каждый перезапуск контейнера на ноутбуке уходил бы в рабочий чат команды как «Контейнер: ошибка завершения».

1. Нажмите «Создать проект» и задайте название, например «Магазин — локально».
2. В проекте добавьте стек local.
3. Создайте для стека агента и сохраните токен: он показывается один раз.

Уведомления в локальном проекте можно не настраивать: без каналов события только пишутся в ленту. Подробнее о том, как раскладывать окружения, — в статье проекты, стеки и серверы.

Важно. Токен агента не должен попасть в git. Положите его в .env рядом с docker-compose.yml (NABL_AGENT_TOKEN=…) и проверьте, что .env есть в .gitignore. В файлах, которые коммитятся, — только ${NABL_AGENT_TOKEN}.

#Приложение в Docker Compose

Проще всего добавить агента в основной docker-compose.yml — тем же сервисом, что и в production:

  nabl-agent:
    image: velgir/nabl-agent:latest
    restart: unless-stopped
    environment:
      NABL_AGENT_TOKEN: ${NABL_AGENT_TOKEN}
      NABL_BASE_URL: https://app.nablops.io
      NABL_OTLP_ENABLED: "true"
    expose: ["4317", "4318", "4319"]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Тогда один и тот же compose работает везде, разница только в .env: на ноутбуке — токен стека local, на сервере — токен боевого стека. Агент и настройки OpenTelemetry остаются в файле насовсем, и при выкладке мониторинг уже на месте. Без NABL_AGENT_TOKEN в окружении сервера агент не запустится, поэтому заведите боевой стек тоже.

Приложения в compose отправляют трассы на http://nabl-agent:4318, а события и логи — на http://nabl-agent:4319/v1/log. Если у сервисов приложения задан networks:, добавьте агента в ту же сеть.

Чтобы отличать локальные трассы от боевых, передайте окружение через .env:

    environment:
      OTEL_RESOURCE_ATTRIBUTES: deployment.environment=${APP_ENV:-local}

#Отдельный файл только на время отладки

Если менять общий compose нельзя, положите тот же сервис в docker-compose.nabl.yml (файл начинается с services:) и запускайте его вместе с основным файлом. Так агент окажется в том же compose-проекте и увидит контейнеры приложения:

docker compose -f docker-compose.yml -f docker-compose.nabl.yml up -d

Подробно об установке и проверке агента — в статье мониторинг Docker Compose.

#Приложение запущено не в Docker

Агент всё равно запускается контейнером, но его порты нужно опубликовать на localhost — иначе приложение с хоста до агента не достучится. Если у проекта уже есть compose для зависимостей (база, Redis, брокер), добавьте агента туда: заодно он покажет и их контейнеры. Если compose нет, создайте docker-compose.nabl.yml:

services:
  nabl-agent:
    image: velgir/nabl-agent:latest
    restart: unless-stopped
    environment:
      NABL_AGENT_TOKEN: ${NABL_AGENT_TOKEN}
      NABL_BASE_URL: https://app.nablops.io
      NABL_OTLP_ENABLED: "true"
    ports:
      - "127.0.0.1:4317:4317"
      - "127.0.0.1:4318:4318"
      - "127.0.0.1:4319:4319"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

docker compose -f docker-compose.nabl.yml -p nabl-local up -d

Что важно:

• Публикуйте порты только на 127.0.0.1. Приём событий и логов работает без авторизации, из сети он не должен быть виден.
• docker.sock нужен и здесь. По нему агент понимает, что работает как агент стека. Без него агент переходит в режим сервера и не опрашивает источники метрик.
• Приложению задайте OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318, события и логи отправляйте на http://127.0.0.1:4319/v1/log.
• Источник метрик указывайте по адресу, по которому агент из контейнера видит приложение на хосте: http://host.docker.internal:<порт>/metrics. Это работает в Docker Desktop. В Linux добавьте агенту extra_hosts: ["host.docker.internal:host-gateway"], а приложение должно слушать 0.0.0.0, а не только 127.0.0.1.
• Ошибки из stdout агент читает только у контейнеров. У процесса на хосте исключения видны в трассах: статус и исключение в спане. Нужные записи можно отправлять событиями.

#Локальный Kubernetes

Для Docker Desktop, kind, minikube или k3d установите агента так же, как в production, — манифестом из инструкции стека (см. мониторинг Kubernetes). Отдельный namespace для локального стенда не нужен: ставьте агента в namespace приложения.

• Поды приложения отправляют трассы на http://nabl-agent:4318, если агент в том же namespace, или на http://nabl-agent.<namespace>.svc:4318.

• Если приложение запущено на хосте, а остальное — в кластере, пробросьте порты агента и отправляйте на http://127.0.0.1:4318, как в варианте без Docker:

  bashКопировать

  kubectl -n <namespace> port-forward svc/nabl-agent 4317:4317 4318:4318 4319:4319

• CPU и память подов видны, только если в кластере есть metrics-server. В kind и k3d его нужно поставить, в minikube — minikube addons enable metrics-server. Статусы, перезапуски, OOM и ошибки из логов работают и без него.

#Как проверить, что всё работает

1. Откройте стек local в кабинете: агент должен быть на связи, а контейнеры — видны в списке.
2. Сделайте несколько запросов к приложению.
3. Откройте вкладку «Трассировка» — там должны появиться трассы.

Если трасс нет, проверьте адрес OTEL_EXPORTER_OTLP_ENDPOINT и то, что агент запущен с NABL_OTLP_ENABLED: "true". Больше вариантов — в статье частые проблемы.

#Как отлаживать с Наблюдателем

• Медленный запрос. Воспроизведите его, откройте самую долгую трассу и посмотрите, какие спаны заняли время. После правки повторите и сравните.
• Запросы к базе. Найдите самые медленные и частые запросы. N+1 выглядит так: один и тот же запрос повторяется десятки раз внутри одной трассы.
• Ошибки. Откройте ошибку, посмотрите трейсбек, а после исправления отметьте её решённой.
• События, логи и метрики. Убедитесь, что приложение отправляет то, что задумано, до выкладки.

Удобнее всего — через ИИ-ассистента: он сам подключит локальный стек, положит токен в .env, добавит агента в compose, а потом найдёт медленные запросы и N+1 в вашем эндпоинте. Подробнее — в статье ИИ-ассистент по MCP.

#Когда закончили

Агенту в основном compose ничего делать не нужно: он живёт вместе с проектом, как и в production.

• Остановить только агента: docker compose stop nabl-agent.
• Отдельный файл: docker compose -f docker-compose.nabl.yml down.
• Kubernetes: kubectl delete -f nabl-agent.yaml.

Данные хранятся по обычным срокам: трассы — 7 дней, трассы с ошибками — 30 дней. Если локальный проект больше не нужен, удалите его в «Управление» → «Основные» → «Удалить проект».

#Что дальше

• Мониторинг Docker Compose — установка агента по шагам.
• Трассировка — подключение OpenTelemetry к приложению.
• Запросы к базе данных — медленный SQL и N+1.
• Проекты, стеки и серверы — как разложить окружения.