Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bitrix-tools/b24-ai-starter-otel


https://github.com/bitrix-tools/b24-ai-starter-otel

Last synced: 3 days ago
JSON representation

Awesome Lists containing this project

README 

          
# b24-ai-starter-otel



Независимая телеметрическая инфраструктура (OpenTelemetry Backend) для приложений Bitrix24.



**Статус**: 🚧 В разработке  

**Версия**: 0.1.0-alpha  

**Дата**: 16 февраля 2026



---



## О проекте



Это **отдельный репозиторий инфраструктуры** для сбора, хранения и визуализации телеметрии от приложений на базе [b24-ai-starter-ru](../b24-ai-starter-ru).



### Что внутри



- **OpenTelemetry Collector** — прием событий по протоколу OTLP (HTTP/gRPC)

- **ClickHouse** — колоночная СУБД для хранения событий и метрик

- **Grafana** — визуализация, дашборды, алерты



### Основная идея



```

┌─────────────────────────────────────────┐

│ Ваши приложения (PHP/Python/Node.js)   │

│   - b24-ai-starter-ru                   │

│   - другие приложения                   │

└─────────────────┬───────────────────────┘

                  │ OTLP/HTTP

                  │ (port 4318)

                  ▼

┌─────────────────────────────────────────┐

│ b24-ai-starter-otel (этот репозиторий)  │

│                                          │

│  OTel Collector → ClickHouse → Grafana  │

└─────────────────────────────────────────┘

```



**Ключевые преимущества:**

- ✅ Работает независимо от приложений

- ✅ Принимает телеметрию от любых OTLP-совместимых клиентов

- ✅ Один инстанс обслуживает множество приложений

- ✅ Легко масштабируется



---



## Быстрый старт



### Требования



- Docker 20.10+

- Docker Compose v2+

- 2+ GB RAM

- 10+ GB диска



### Запуск



```bash

# Клонировать репозиторий

git clone  b24-ai-starter-otel

cd b24-ai-starter-otel



# Настроить переменные окружения

cp .env.example .env

# Отредактируйте .env: установите пароли!



# Запустить инфраструктуру

docker-compose up -d



# Проверить статус

docker-compose ps

```



**Сервисы доступны по адресам:**

- Grafana: http://localhost:3001 (логин: admin, пароль: из .env)

- ClickHouse UI: http://localhost:8123/play

- OTel Collector: http://localhost:4318 (OTLP HTTP endpoint)



### Подключение приложения



В вашем приложении (например, `b24-ai-starter-ru`):



```bash

# .env

TELEMETRY_ENABLED=true

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

OTEL_SERVICE_NAME=my-bitrix24-app

OTEL_ENVIRONMENT=development

```



После перезапуска приложения события начнут поступать в ClickHouse, и их можно будет увидеть в Grafana.



---



## Структура репозитория



```

b24-ai-starter-otel/

├── README.md                 # Этот файл

├── docker-compose.yml        # Определение сервисов

├── .env.example              # Шаблон конфигурации

│

├── otel-collector/

│   └── config.yaml           # Конфигурация OTel Collector

│                             # - receivers (OTLP HTTP/gRPC)

│                             # - processors (batch, filter)

│                             # - exporters (ClickHouse)

│

├── clickhouse/

│   ├── init.sql              # Создание БД и пользователя

│   └── schema/

│       ├── otel_logs.sql           # Основная таблица логов

│       ├── logs_analytics_mv.sql   # View для продуктовой аналитики

│       └── logs_support_mv.sql     # View для техподдержки

│

├── grafana/

│   ├── grafana.ini           # Основная конфигурация

│   └── provisioning/

│       ├── datasources/

│       │   └── clickhouse.yaml     # Подключение к ClickHouse

│       ├── dashboards/

│       │   ├── dashboards.yaml          # Auto-provisioning

│       │   ├── product-analytics.json

│       │   ├── errors-overview.json

│       │   ├── portal-health.json

│       │   ├── api-performance.json

│       │   └── conversion-funnel.json   # Воронка активации

│       └── alerting/

│           ├── contact-points.yaml      # Email-получатели алертов

│           ├── notification-policies.yaml

│           └── alert-rules.yaml         # 5 правил по ошибкам

│

└── docs/

    ├── DEPLOYMENT.md         # Развертывание в production

    └── ARCHITECTURE.md       # Детали архитектуры

```



---



## Конфигурация



### Переменные окружения (.env)



Основные параметры:



```bash

# OpenTelemetry Collector

OTEL_COLLECTOR_HTTP_PORT=4318

OTEL_COLLECTOR_GRPC_PORT=4317



# ClickHouse

CLICKHOUSE_DB=telemetry

CLICKHOUSE_USER=telemetry_user

CLICKHOUSE_PASSWORD=changeme_secure_password

CLICKHOUSE_HTTP_PORT=8123

CLICKHOUSE_NATIVE_PORT=9000



# Grafana

GRAFANA_ADMIN_USER=admin

GRAFANA_ADMIN_PASSWORD=changeme_admin_password

GRAFANA_HTTP_PORT=3001



# Путь к директории logs/ репозитория приложения (b24-ai-starter-full или другого).

# Используется filelog receiver для чтения файловых логов — ошибок, произошедших

# ДО инициализации классов телеметрии (PHP fatals, ошибки DI-контейнера Symfony,

# краши на старте). Такие ошибки не попадают в MonologOTelHandler и доступны

# только через файлы логов.

#

# Может быть относительным (от директории b24-ai-starter-otel) или абсолютным.

# Относительный путь по умолчанию предполагает, что оба репозитория лежат рядом:

#   ../b24-ai-starter-otel/   (этот репозиторий)

#   ../b24-ai-starter-full/   (репозиторий приложения)

#

# Пример абсолютного пути:

#   APP_LOGS_PATH=/home/user/projects/b24-ai-starter-full/logs

APP_LOGS_PATH=../b24-ai-starter-full/logs

```



⚠️ **Важно**: В production обязательно измените пароли по умолчанию!



### Сбор файловых логов (filelog receiver)



OTel Collector следит за файлами логов приложения через `filelog` receiver. Это позволяет перехватывать ошибки, которые происходят до инициализации телеметрии и не попадают в OTLP-поток:



| Файл | Что содержит |

|---|---|

| `logs/php/phpfpm/error.log` | PHP fatals, ошибки PHP-FPM (все окружения) |

| `logs/php/symfony/*.log` | Логи Monolog stream handler (только dev) |

| `logs/node/*.log` | Логи Node.js бэкенда |

| `logs/python/*.log` | Логи Python бэкенда |



Все записи из файлов получают атрибут `log.source=file`, что позволяет в Grafana отличать их от логов, пришедших через OTLP (`log.source=otlp`).



Позиции чтения сохраняются в Docker volume `otel-filepos` — при рестарте коллектора файлы не перечитываются заново.



### Volumes (данные)



Docker volumes для персистентности:



- `clickhouse_data` — данные ClickHouse

- `grafana_data` — конфигурация и дашборды Grafana



```bash

# Посмотреть volumes

docker volume ls | grep b24



# Бэкап ClickHouse

docker-compose exec clickhouse clickhouse-client --query="BACKUP DATABASE telemetry TO Disk('backups', 'backup-$(date +%Y%m%d).zip')"

```



---



## Дашборды Grafana



После запуска автоматически создаются 4 дашборда:



### 1. Product Analytics

Продуктовая аналитика для Product Managers:

- Activation rate (% пользователей, завершивших онбординг)

- Retention cohorts

- Core actions (ключевые действия пользователей)

- Feature adoption

- Funnel analysis (воронки конверсии)



### 2. Errors Overview

Мониторинг ошибок для DevOps/Support:

- Количество ошибок по типам

- Top 10 ошибок

- Affected portals (какие порталы затронуты)

- Error rate trends

- Stack traces (топ фреймов)



### 3. Portal Health

Здоровье конкретных порталов:

- API latency (p50, p95, p99)

- Success rate процессов

- Resource usage

- Active users

- Фильтр по portal_id



### 4. API Performance

Производительность API вызовов:

- Request rate (rps)

- Response time distribution

- Error rate

- Top slow endpoints

- Bitrix24 API calls (успешные/неудачные)



### 5. Conversion Funnel (Воронка активации)

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



| Шаг | Событие |

|---|---|

| 1 | `app_installed` — установка приложения |

| 2 | `app_install_finalized` — завершение установки |

| 3 | `event_subscription_registered` — подписка на события |

| 4 | `app_opened` — первое открытие |

| 5 | `ui_button_click` — первое целевое действие |



Дашборд показывает уникальных пользователей (`portal.member_id`) на каждом шаге за выбранный период.

Поддерживает фильтрацию по домену портала (`$domain`).



---



## Алерты



Grafana автоматически загружает правила из `grafana/provisioning/alerting/`. Правила оцениваются каждую минуту по скользящему окну 5 минут.



### Настроенные правила



| Правило | Условие | Severity |

|---|---|---|

| FATAL ошибки | любое появление FATAL | critical |

| Всплеск backend ошибок | > 10 ERROR/FATAL за 5 мин | warning |

| Всплеск frontend JS ошибок | > 20 событий `ui_error` за 5 мин | warning |

| Ошибки на нескольких порталах | > 3 уникальных портала с ошибками за 5 мин | critical |

| Общий всплеск ошибок | > 50 ошибок (backend + frontend) за 5 мин | critical |



Посмотреть состояние правил: **Grafana → Alerting → Alert rules** (папка `Telemetry Alerts`).



### Настройка email-уведомлений



По умолчанию SMTP отключён. Для получения алертов на почту:



**1. Настроить SMTP в `.env`** — раскомментировать и заполнить блок:



```bash

GF_SMTP_ENABLED=true

GF_SMTP_HOST=smtp.gmail.com:587        # для Gmail

GF_SMTP_USER=your@gmail.com

GF_SMTP_PASSWORD=your_app_password     # App Password, не основной пароль

GF_SMTP_FROM_ADDRESS=your@gmail.com

GF_SMTP_FROM_NAME=Grafana Alerts

```



> Для Gmail: включить двухфакторную аутентификацию → [создать App Password](https://myaccount.google.com/apppasswords) → использовать его как `GF_SMTP_PASSWORD`.



**2. Указать email-получателя** в файле `grafana/provisioning/alerting/contact-points.yaml`:



```yaml

settings:

  addresses: "your@email.com"  # ← изменить на реальный адрес

```



Несколько адресов разделяются точкой с запятой: `user1@example.com;user2@example.com`



**3. Перезапустить Grafana:**



```bash

sudo rm -f data/grafana/grafana.db

make up

```



> Удаление `grafana.db` необходимо — иначе Grafana использует закешированную конфигурацию provisioning.



---



## Интеграция с приложениями



### PHP (b24-ai-starter-ru)



См. документацию в репозитории [b24-ai-starter-ru](../b24-ai-starter-ru).



Краткий пример:



```php

// composer.json

"require": {

    "open-telemetry/sdk": "^1.0",

    "open-telemetry/exporter-otlp": "^1.0"

}

```



```php

// отправка события

$telemetry->trackEvent('user.activation.completed', [

    'portal_id' => $portalId,

    'user_id' => $userId,

    'step' => 'final'

]);

```



### Python



```bash

pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

```



```python

from opentelemetry import trace

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

from opentelemetry.sdk.trace import TracerProvider

from opentelemetry.sdk.trace.export import BatchSpanProcessor



# Инициализация

provider = TracerProvider()

trace.set_tracer_provider(provider)

otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")

provider.add_span_processor(BatchSpanProcessor(otlp_exporter))



# Использование

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("process-data"):

    # ваш код

    pass

```



### Node.js



```bash

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

```



```javascript

const { NodeSDK } = require('@opentelemetry/sdk-node');

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');



const sdk = new NodeSDK({

  traceExporter: new OTLPTraceExporter({

    url: 'http://localhost:4318/v1/traces',

  }),

  serviceName: 'my-node-app',

});



sdk.start();

```



---



## Управление



### Основные команды



```bash

# Запуск

docker-compose up -d



# Статус сервисов

docker-compose ps



# Логи

docker-compose logs -f                    # все сервисы

docker-compose logs -f otel-collector     # только collector

docker-compose logs -f clickhouse         # только clickhouse

docker-compose logs -f grafana            # только grafana



# Остановка

docker-compose stop



# Перезапуск

docker-compose restart



# Полное удаление (с данными!)

docker-compose down -v

```



### Проверка работоспособности



```bash

# OTel Collector (должен ответить)

curl http://localhost:4318/v1/logs -X POST



# ClickHouse (проверка подключения)

docker-compose exec clickhouse clickhouse-client --query="SELECT 1"



# Проверка таблиц

docker-compose exec clickhouse clickhouse-client --query="SHOW TABLES FROM telemetry"



# Количество событий

docker-compose exec clickhouse clickhouse-client --query="SELECT count() FROM telemetry.otel_logs"

```



### Troubleshooting



**Проблема**: События не поступают в ClickHouse



```bash

# 1. Проверить логи OTel Collector

docker-compose logs otel-collector | grep ERROR



# 2. Проверить, что endpoint доступен

curl -v http://localhost:4318/v1/logs



# 3. Проверить конфигурацию приложения

# OTEL_EXPORTER_OTLP_ENDPOINT должен указывать на collector

```



**Проблема**: Grafana не показывает данные



```bash

# 1. Проверить подключение к ClickHouse

docker-compose exec grafana curl http://clickhouse:8123/



# 2. Проверить, что данные есть

docker-compose exec clickhouse clickhouse-client \

  --query="SELECT count() FROM telemetry.otel_logs WHERE timestamp > now() - INTERVAL 1 HOUR"



# 3. Проверить datasource в Grafana (Configuration → Data sources)

```



---



## Production Deployment



Для production рекомендуется:



1. **Разделить компоненты**

   - ClickHouse на отдельном сервере (или кластер)

   - OTel Collector за load balancer (несколько инстансов)

   - Grafana Cloud или управляемый Grafana



2. **Безопасность**

   - TLS для OTLP endpoint

   - Аутентификация для Grafana

   - Network policies / firewall

   - Регулярные обновления образов



3. **Масштабирование**

   - ClickHouse sharding для больших нагрузок

   - Replication для высокой доступности

   - Мониторинг самой инфраструктуры



Подробнее: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)



---



## Связанные репозитории



- [b24-ai-starter-ru](../b24-ai-starter-ru) — PHP приложение с клиентом телеметрии

- [OpenTelemetry Documentation](../README.md) — общая документация по телеметрии

- [ARCHITECTURE_SPLIT.md](../ARCHITECTURE_SPLIT.md) — детали архитектуры разделения



---



## Roadmap



- [x] Базовая архитектура (февраль 2026)

- [ ] docker-compose.yml (в процессе)

- [ ] Конфигурация OTel Collector

- [ ] Схемы ClickHouse (otel_logs, MVs)

- [ ] 4 дашборда Grafana

- [ ] Production deployment guide

- [ ] Kubernetes Helm chart

- [ ] Мониторинг самой инфраструктуры

- [ ] Automated backups



---



## Лицензия



MIT License



---



## Поддержка



- 📖 [Документация](docs/)

- 🐛 [Issues](../../issues)

- 💬 Создайте issue для вопросов



**Дата последнего обновления**: 16 февраля 2026