{"id":51020893,"url":"https://github.com/bitrix-tools/b24-ai-starter-otel","last_synced_at":"2026-06-21T16:01:51.813Z","repository":{"id":365905342,"uuid":"1155358052","full_name":"bitrix-tools/b24-ai-starter-otel","owner":"bitrix-tools","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-10T06:25:12.000Z","size":94,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T12:34:32.206Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitrix-tools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T12:26:23.000Z","updated_at":"2026-06-05T07:45:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bitrix-tools/b24-ai-starter-otel","commit_stats":null,"previous_names":["bitrix-tools/b24-ai-starter-otel"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bitrix-tools/b24-ai-starter-otel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter-otel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter-otel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter-otel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter-otel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitrix-tools","download_url":"https://codeload.github.com/bitrix-tools/b24-ai-starter-otel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitrix-tools%2Fb24-ai-starter-otel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34616512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-21T16:01:51.112Z","updated_at":"2026-06-21T16:01:51.795Z","avatar_url":"https://github.com/bitrix-tools.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# b24-ai-starter-otel\n\nНезависимая телеметрическая инфраструктура (OpenTelemetry Backend) для приложений Bitrix24.\n\n**Статус**: 🚧 В разработке  \n**Версия**: 0.1.0-alpha  \n**Дата**: 16 февраля 2026\n\n---\n\n## О проекте\n\nЭто **отдельный репозиторий инфраструктуры** для сбора, хранения и визуализации телеметрии от приложений на базе [b24-ai-starter-ru](../b24-ai-starter-ru).\n\n### Что внутри\n\n- **OpenTelemetry Collector** — прием событий по протоколу OTLP (HTTP/gRPC)\n- **ClickHouse** — колоночная СУБД для хранения событий и метрик\n- **Grafana** — визуализация, дашборды, алерты\n\n### Основная идея\n\n```\n┌─────────────────────────────────────────┐\n│ Ваши приложения (PHP/Python/Node.js)   │\n│   - b24-ai-starter-ru                   │\n│   - другие приложения                   │\n└─────────────────┬───────────────────────┘\n                  │ OTLP/HTTP\n                  │ (port 4318)\n                  ▼\n┌─────────────────────────────────────────┐\n│ b24-ai-starter-otel (этот репозиторий)  │\n│                                          │\n│  OTel Collector → ClickHouse → Grafana  │\n└─────────────────────────────────────────┘\n```\n\n**Ключевые преимущества:**\n- ✅ Работает независимо от приложений\n- ✅ Принимает телеметрию от любых OTLP-совместимых клиентов\n- ✅ Один инстанс обслуживает множество приложений\n- ✅ Легко масштабируется\n\n---\n\n## Быстрый старт\n\n### Требования\n\n- Docker 20.10+\n- Docker Compose v2+\n- 2+ GB RAM\n- 10+ GB диска\n\n### Запуск\n\n```bash\n# Клонировать репозиторий\ngit clone \u003crepo-url\u003e b24-ai-starter-otel\ncd b24-ai-starter-otel\n\n# Настроить переменные окружения\ncp .env.example .env\n# Отредактируйте .env: установите пароли!\n\n# Запустить инфраструктуру\ndocker-compose up -d\n\n# Проверить статус\ndocker-compose ps\n```\n\n**Сервисы доступны по адресам:**\n- Grafana: http://localhost:3001 (логин: admin, пароль: из .env)\n- ClickHouse UI: http://localhost:8123/play\n- OTel Collector: http://localhost:4318 (OTLP HTTP endpoint)\n\n### Подключение приложения\n\nВ вашем приложении (например, `b24-ai-starter-ru`):\n\n```bash\n# .env\nTELEMETRY_ENABLED=true\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318\nOTEL_SERVICE_NAME=my-bitrix24-app\nOTEL_ENVIRONMENT=development\n```\n\nПосле перезапуска приложения события начнут поступать в ClickHouse, и их можно будет увидеть в Grafana.\n\n---\n\n## Структура репозитория\n\n```\nb24-ai-starter-otel/\n├── README.md                 # Этот файл\n├── docker-compose.yml        # Определение сервисов\n├── .env.example              # Шаблон конфигурации\n│\n├── otel-collector/\n│   └── config.yaml           # Конфигурация OTel Collector\n│                             # - receivers (OTLP HTTP/gRPC)\n│                             # - processors (batch, filter)\n│                             # - exporters (ClickHouse)\n│\n├── clickhouse/\n│   ├── init.sql              # Создание БД и пользователя\n│   └── schema/\n│       ├── otel_logs.sql           # Основная таблица логов\n│       ├── logs_analytics_mv.sql   # View для продуктовой аналитики\n│       └── logs_support_mv.sql     # View для техподдержки\n│\n├── grafana/\n│   ├── grafana.ini           # Основная конфигурация\n│   └── provisioning/\n│       ├── datasources/\n│       │   └── clickhouse.yaml     # Подключение к ClickHouse\n│       ├── dashboards/\n│       │   ├── dashboards.yaml          # Auto-provisioning\n│       │   ├── product-analytics.json\n│       │   ├── errors-overview.json\n│       │   ├── portal-health.json\n│       │   ├── api-performance.json\n│       │   └── conversion-funnel.json   # Воронка активации\n│       └── alerting/\n│           ├── contact-points.yaml      # Email-получатели алертов\n│           ├── notification-policies.yaml\n│           └── alert-rules.yaml         # 5 правил по ошибкам\n│\n└── docs/\n    ├── DEPLOYMENT.md         # Развертывание в production\n    └── ARCHITECTURE.md       # Детали архитектуры\n```\n\n---\n\n## Конфигурация\n\n### Переменные окружения (.env)\n\nОсновные параметры:\n\n```bash\n# OpenTelemetry Collector\nOTEL_COLLECTOR_HTTP_PORT=4318\nOTEL_COLLECTOR_GRPC_PORT=4317\n\n# ClickHouse\nCLICKHOUSE_DB=telemetry\nCLICKHOUSE_USER=telemetry_user\nCLICKHOUSE_PASSWORD=changeme_secure_password\nCLICKHOUSE_HTTP_PORT=8123\nCLICKHOUSE_NATIVE_PORT=9000\n\n# Grafana\nGRAFANA_ADMIN_USER=admin\nGRAFANA_ADMIN_PASSWORD=changeme_admin_password\nGRAFANA_HTTP_PORT=3001\n\n# Путь к директории logs/ репозитория приложения (b24-ai-starter-full или другого).\n# Используется filelog receiver для чтения файловых логов — ошибок, произошедших\n# ДО инициализации классов телеметрии (PHP fatals, ошибки DI-контейнера Symfony,\n# краши на старте). Такие ошибки не попадают в MonologOTelHandler и доступны\n# только через файлы логов.\n#\n# Может быть относительным (от директории b24-ai-starter-otel) или абсолютным.\n# Относительный путь по умолчанию предполагает, что оба репозитория лежат рядом:\n#   ../b24-ai-starter-otel/   (этот репозиторий)\n#   ../b24-ai-starter-full/   (репозиторий приложения)\n#\n# Пример абсолютного пути:\n#   APP_LOGS_PATH=/home/user/projects/b24-ai-starter-full/logs\nAPP_LOGS_PATH=../b24-ai-starter-full/logs\n```\n\n⚠️ **Важно**: В production обязательно измените пароли по умолчанию!\n\n### Сбор файловых логов (filelog receiver)\n\nOTel Collector следит за файлами логов приложения через `filelog` receiver. Это позволяет перехватывать ошибки, которые происходят до инициализации телеметрии и не попадают в OTLP-поток:\n\n| Файл | Что содержит |\n|---|---|\n| `logs/php/phpfpm/error.log` | PHP fatals, ошибки PHP-FPM (все окружения) |\n| `logs/php/symfony/*.log` | Логи Monolog stream handler (только dev) |\n| `logs/node/*.log` | Логи Node.js бэкенда |\n| `logs/python/*.log` | Логи Python бэкенда |\n\nВсе записи из файлов получают атрибут `log.source=file`, что позволяет в Grafana отличать их от логов, пришедших через OTLP (`log.source=otlp`).\n\nПозиции чтения сохраняются в Docker volume `otel-filepos` — при рестарте коллектора файлы не перечитываются заново.\n\n### Volumes (данные)\n\nDocker volumes для персистентности:\n\n- `clickhouse_data` — данные ClickHouse\n- `grafana_data` — конфигурация и дашборды Grafana\n\n```bash\n# Посмотреть volumes\ndocker volume ls | grep b24\n\n# Бэкап ClickHouse\ndocker-compose exec clickhouse clickhouse-client --query=\"BACKUP DATABASE telemetry TO Disk('backups', 'backup-$(date +%Y%m%d).zip')\"\n```\n\n---\n\n## Дашборды Grafana\n\nПосле запуска автоматически создаются 4 дашборда:\n\n### 1. Product Analytics\nПродуктовая аналитика для Product Managers:\n- Activation rate (% пользователей, завершивших онбординг)\n- Retention cohorts\n- Core actions (ключевые действия пользователей)\n- Feature adoption\n- Funnel analysis (воронки конверсии)\n\n### 2. Errors Overview\nМониторинг ошибок для DevOps/Support:\n- Количество ошибок по типам\n- Top 10 ошибок\n- Affected portals (какие порталы затронуты)\n- Error rate trends\n- Stack traces (топ фреймов)\n\n### 3. Portal Health\nЗдоровье конкретных порталов:\n- API latency (p50, p95, p99)\n- Success rate процессов\n- Resource usage\n- Active users\n- Фильтр по portal_id\n\n### 4. API Performance\nПроизводительность API вызовов:\n- Request rate (rps)\n- Response time distribution\n- Error rate\n- Top slow endpoints\n- Bitrix24 API calls (успешные/неудачные)\n\n### 5. Conversion Funnel (Воронка активации)\nПродуктовая воронка конверсии — сколько пользователей прошли каждый шаг онбординга:\n\n| Шаг | Событие |\n|---|---|\n| 1 | `app_installed` — установка приложения |\n| 2 | `app_install_finalized` — завершение установки |\n| 3 | `event_subscription_registered` — подписка на события |\n| 4 | `app_opened` — первое открытие |\n| 5 | `ui_button_click` — первое целевое действие |\n\nДашборд показывает уникальных пользователей (`portal.member_id`) на каждом шаге за выбранный период.\nПоддерживает фильтрацию по домену портала (`$domain`).\n\n---\n\n## Алерты\n\nGrafana автоматически загружает правила из `grafana/provisioning/alerting/`. Правила оцениваются каждую минуту по скользящему окну 5 минут.\n\n### Настроенные правила\n\n| Правило | Условие | Severity |\n|---|---|---|\n| FATAL ошибки | любое появление FATAL | critical |\n| Всплеск backend ошибок | \u003e 10 ERROR/FATAL за 5 мин | warning |\n| Всплеск frontend JS ошибок | \u003e 20 событий `ui_error` за 5 мин | warning |\n| Ошибки на нескольких порталах | \u003e 3 уникальных портала с ошибками за 5 мин | critical |\n| Общий всплеск ошибок | \u003e 50 ошибок (backend + frontend) за 5 мин | critical |\n\nПосмотреть состояние правил: **Grafana → Alerting → Alert rules** (папка `Telemetry Alerts`).\n\n### Настройка email-уведомлений\n\nПо умолчанию SMTP отключён. Для получения алертов на почту:\n\n**1. Настроить SMTP в `.env`** — раскомментировать и заполнить блок:\n\n```bash\nGF_SMTP_ENABLED=true\nGF_SMTP_HOST=smtp.gmail.com:587        # для Gmail\nGF_SMTP_USER=your@gmail.com\nGF_SMTP_PASSWORD=your_app_password     # App Password, не основной пароль\nGF_SMTP_FROM_ADDRESS=your@gmail.com\nGF_SMTP_FROM_NAME=Grafana Alerts\n```\n\n\u003e Для Gmail: включить двухфакторную аутентификацию → [создать App Password](https://myaccount.google.com/apppasswords) → использовать его как `GF_SMTP_PASSWORD`.\n\n**2. Указать email-получателя** в файле `grafana/provisioning/alerting/contact-points.yaml`:\n\n```yaml\nsettings:\n  addresses: \"your@email.com\"  # ← изменить на реальный адрес\n```\n\nНесколько адресов разделяются точкой с запятой: `user1@example.com;user2@example.com`\n\n**3. Перезапустить Grafana:**\n\n```bash\nsudo rm -f data/grafana/grafana.db\nmake up\n```\n\n\u003e Удаление `grafana.db` необходимо — иначе Grafana использует закешированную конфигурацию provisioning.\n\n---\n\n## Интеграция с приложениями\n\n### PHP (b24-ai-starter-ru)\n\nСм. документацию в репозитории [b24-ai-starter-ru](../b24-ai-starter-ru).\n\nКраткий пример:\n\n```php\n// composer.json\n\"require\": {\n    \"open-telemetry/sdk\": \"^1.0\",\n    \"open-telemetry/exporter-otlp\": \"^1.0\"\n}\n```\n\n```php\n// отправка события\n$telemetry-\u003etrackEvent('user.activation.completed', [\n    'portal_id' =\u003e $portalId,\n    'user_id' =\u003e $userId,\n    'step' =\u003e 'final'\n]);\n```\n\n### Python\n\n```bash\npip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp\n```\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\n\n# Инициализация\nprovider = TracerProvider()\ntrace.set_tracer_provider(provider)\notlp_exporter = OTLPSpanExporter(endpoint=\"http://localhost:4318/v1/traces\")\nprovider.add_span_processor(BatchSpanProcessor(otlp_exporter))\n\n# Использование\ntracer = trace.get_tracer(__name__)\nwith tracer.start_as_current_span(\"process-data\"):\n    # ваш код\n    pass\n```\n\n### Node.js\n\n```bash\nnpm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http\n```\n\n```javascript\nconst { NodeSDK } = require('@opentelemetry/sdk-node');\nconst { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');\n\nconst sdk = new NodeSDK({\n  traceExporter: new OTLPTraceExporter({\n    url: 'http://localhost:4318/v1/traces',\n  }),\n  serviceName: 'my-node-app',\n});\n\nsdk.start();\n```\n\n---\n\n## Управление\n\n### Основные команды\n\n```bash\n# Запуск\ndocker-compose up -d\n\n# Статус сервисов\ndocker-compose ps\n\n# Логи\ndocker-compose logs -f                    # все сервисы\ndocker-compose logs -f otel-collector     # только collector\ndocker-compose logs -f clickhouse         # только clickhouse\ndocker-compose logs -f grafana            # только grafana\n\n# Остановка\ndocker-compose stop\n\n# Перезапуск\ndocker-compose restart\n\n# Полное удаление (с данными!)\ndocker-compose down -v\n```\n\n### Проверка работоспособности\n\n```bash\n# OTel Collector (должен ответить)\ncurl http://localhost:4318/v1/logs -X POST\n\n# ClickHouse (проверка подключения)\ndocker-compose exec clickhouse clickhouse-client --query=\"SELECT 1\"\n\n# Проверка таблиц\ndocker-compose exec clickhouse clickhouse-client --query=\"SHOW TABLES FROM telemetry\"\n\n# Количество событий\ndocker-compose exec clickhouse clickhouse-client --query=\"SELECT count() FROM telemetry.otel_logs\"\n```\n\n### Troubleshooting\n\n**Проблема**: События не поступают в ClickHouse\n\n```bash\n# 1. Проверить логи OTel Collector\ndocker-compose logs otel-collector | grep ERROR\n\n# 2. Проверить, что endpoint доступен\ncurl -v http://localhost:4318/v1/logs\n\n# 3. Проверить конфигурацию приложения\n# OTEL_EXPORTER_OTLP_ENDPOINT должен указывать на collector\n```\n\n**Проблема**: Grafana не показывает данные\n\n```bash\n# 1. Проверить подключение к ClickHouse\ndocker-compose exec grafana curl http://clickhouse:8123/\n\n# 2. Проверить, что данные есть\ndocker-compose exec clickhouse clickhouse-client \\\n  --query=\"SELECT count() FROM telemetry.otel_logs WHERE timestamp \u003e now() - INTERVAL 1 HOUR\"\n\n# 3. Проверить datasource в Grafana (Configuration → Data sources)\n```\n\n---\n\n## Production Deployment\n\nДля production рекомендуется:\n\n1. **Разделить компоненты**\n   - ClickHouse на отдельном сервере (или кластер)\n   - OTel Collector за load balancer (несколько инстансов)\n   - Grafana Cloud или управляемый Grafana\n\n2. **Безопасность**\n   - TLS для OTLP endpoint\n   - Аутентификация для Grafana\n   - Network policies / firewall\n   - Регулярные обновления образов\n\n3. **Масштабирование**\n   - ClickHouse sharding для больших нагрузок\n   - Replication для высокой доступности\n   - Мониторинг самой инфраструктуры\n\nПодробнее: [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)\n\n---\n\n## Связанные репозитории\n\n- [b24-ai-starter-ru](../b24-ai-starter-ru) — PHP приложение с клиентом телеметрии\n- [OpenTelemetry Documentation](../README.md) — общая документация по телеметрии\n- [ARCHITECTURE_SPLIT.md](../ARCHITECTURE_SPLIT.md) — детали архитектуры разделения\n\n---\n\n## Roadmap\n\n- [x] Базовая архитектура (февраль 2026)\n- [ ] docker-compose.yml (в процессе)\n- [ ] Конфигурация OTel Collector\n- [ ] Схемы ClickHouse (otel_logs, MVs)\n- [ ] 4 дашборда Grafana\n- [ ] Production deployment guide\n- [ ] Kubernetes Helm chart\n- [ ] Мониторинг самой инфраструктуры\n- [ ] Automated backups\n\n---\n\n## Лицензия\n\nMIT License\n\n---\n\n## Поддержка\n\n- 📖 [Документация](docs/)\n- 🐛 [Issues](../../issues)\n- 💬 Создайте issue для вопросов\n\n**Дата последнего обновления**: 16 февраля 2026\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitrix-tools%2Fb24-ai-starter-otel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitrix-tools%2Fb24-ai-starter-otel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitrix-tools%2Fb24-ai-starter-otel/lists"}