Дерево страниц
Перейти к концу метаданных
Переход к началу метаданных

Описание


Сервис Eltex-Mcdonalds предназначен для интеграции платформы с системой клиента в рамках API. Клиент хочет копить у себя данные пользователей, которые прошли авторизацию. Нужно синхронно (online) пересылать информацию о старте и завершении пользовательской сессии портальных гостевых клиентов на внешнюю систему через HTTP Rest (JSON) API.

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

Глоссарий

ТерминОписание
Eltex-McdonaldsEltex сервис, который умеет отправить данные в формате McD-API.
McD-APIСтороннее McDonald's API, принимающее запросы по HTTP PUT.
PCRF

Eltex сервис, который знает об услуге все. Он ничего не знает о существовании Mcdonalds. Его задача здесь - отправить универсальные события в шину данных.

User session valueДанные о сессии пользователя, которыми оперирует PCRF.
Шина данных

Сервис, отвечающий за передачу потока сообщений потребителям. В качестве шины выбрана Apache Kafka.

Принцип работы

  • Eltex-PCRF отправляет данные о начале и окончании всех сессий пользователей в шину данных Kafka. В шину данных летит информация о сессиях всех клиентов, всех пользователей.
  • Kafka может раздавать данные произвольному числу клиентов. Все клиенты подписываются на topic сообщений. К Kafka можно подключать как клиентов, выполняющих различные действия над одними данными (то есть сервисы разных типов) так и несколько сущностей одного сервиса для повышения пропускной способности и резервирования;
  • Eltex-Mcdonalds забирает сообщения из Kafka, проводит валидацию (заполнение обязательный полей) и фильтрацию данных (по домену) и отправляет данные в McD-API. Eltex-Mcdonalds отправляет данные только о пользователях давших согласие  на получение рекламной рассылки. Фильтрация данных настраивается только по домену. В системе должен быть создан корневой гостевой домен клиента mcdonalds. Для подключения к API фронт-системе необходимо использовать токен;
  • Сообщения передаются в режиме реального времени, чтобы иметь возможность сразу же обработать эту информацию и скорректировать стратегию коммуникации с пользователем. Для уменьшения трафика передаются только события старта и окончания сессии;
  • Согласие на получение рекламных материалов указывается на портале при регистрации.

Описание McD-API

Для отправки данных  используются два метода:

Базовый URL: https://apicrm.mcdonalds.ru/api/v1-1/wifihs, тип запроса PUT.

МетодСобытие
/session/createСоздание сессии пользователя (ACCT START)
/session/update
  1. Завершение сессии пользователя (ACCT STOP)
  2. Система получила mac-адрес пользователя

Пример передаваемых данных:

 # Старт  сессии 
 {
   "session_id": "720575940379279391",
   "phone": "79123456789",
   "mac_address_user": "78:02:f8:fa:8f:f4",
   "session_start": 1616061507,
   "session_time": 0,
   "hotspot_identifier": "A8-F9-4B-AB-2F-00",
   "event_ts": 1616061507,
   "personal_data_processing_confirm": true,
   "ts": 1616061508
  } 
# Cтоп сессии
 {
   "session_id": "720575940379279391",
   "phone": "79123456789",
   "mac_address_user": "78:02:f8:fa:8f:f4",
   "session_start": 1616061927,
   "session_stop": 1616063139,
   "session_time": 1623,
   "hotspot_identifier": "A8-F9-4B-AB-2F-00",
   "event_ts": 1616061927,
   "personal_data_processing_confirm": true,
   "ts": 1616063140
  }

Полный список полей:

КлючЗначениеТип поля

Обязательный

/session/create

Обязательный

/session/update

Присутствует
phoneТелефон в формате E164 без "+"stringданет

RADIUS

User-Name

session_idИдентификатор сессииstringдада

RADIUS

Acct-Session-Id

personal_data_processing_confirmФакт согласия на обработку ПД (в SoftWLC это Согласие на получение рекламных материалов)
boolданет

MySQL radstat

advertising

hotspot_identifierИдентификатор точкиstringданет

MAC-адрес

RADIUS

Called-Station-Id

session_startВремя начала сессииint (timestamp в секундах)данеттекущее время
session_stopВремя завершения сессииint (timestamp в секундах)нетдатекущее время
session_timeДлительность сессии (сек)intнетда

RADIUS

Session-Time

(PCRF  присылает sessionTime, сами не считаем)

mac_address_userMac-адрес пользователяstringнетнет

RADIUS

Calling-Station-Id

event_tsДата и время начала сессии
int (timestamp в секундах)дада

PCRF

sessionStart

Установка сервисов


Установка Kafka

Для работы сервисов необходимо подключить их к непосредственно Kafka.

Kafka можно запустить, используя docker-compose:

docker-compose.yml
version: '2'
 
services:
  zookeeper:
    container_name: zookeeper
    image: 'docker.io/bitnami/zookeeper:3-debian-10'
    ports:
      - '2181:2181'
    volumes:
      - 'zookeeper_data:/bitnami'
    environment:
      - ALLOW_ANONYMOUS_LOGIN=yes
      - ZOO_MAX_SESSION_TIMEOUT=500000
    mem_limit: 512m
  kafka:
    container_name: kafka
    image: 'docker.io/bitnami/kafka:2-debian-10'
    ports:
      - '9092:9092'
    volumes:
      - 'kafka_data:/bitnami'
    environment:
      - KAFKA_CFG_ZOOKEEPER_CONNECT=zookeeper:2181
      - ALLOW_PLAINTEXT_LISTENER=yes
      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092
      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://${KAFKA_HOST}:9092
      - KAFKA_LOG_RETENTION_CHECK_INTERVALS_MS=3600000
      - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=false
      - KAFKA_DELETE_TOPIC_ENABLE=true
    mem_limit: 1g
    depends_on:
      - zookeeper
 
volumes:
  zookeeper_data:
    driver: local
  kafka_data:
    driver: local

где KAFKA_HOST - это IP адрес машины, на которой развернута Kafka, белый IP, по которому сервис Kafka будет доступен другим приложениям.

Создание, изменение topic'а

Для управления параметрами Kafka можно использовать скипты, которые доступны в контейнере с самим сервисом

docker exec -it ${CONTAINER_ID} bash

где CONTAINER_ID - это ID для bitnami/kafka:2-debian-10 из команды вывода docker ps:

docker ps
CONTAINER ID   IMAGE                                                    COMMAND                  CREATED       STATUS         PORTS                                                                    NAMES
....
a85321836507   bitnami/kafka:2-debian-10                                "/opt/bitnami/script…"   7 days ago    Up 7 minutes   0.0.0.0:9092->9092/tcp

скрипты доступны по пути /opt/bitnami/kafka/bin внутри контейнера

Topic'и Kafka создаются автоматически, когда их начинают использовать, но можно создать вручную

kafka-topics.sh --create --zookeeper zookeeper:2181 --config cleanup.policy=delete --config file.delete.delay.ms=1 --replication-factor 1 --partitions 1 --topic mcd

Для изменения параметра Topic'а можно использовать следующую команду.

Изменить время хранения сообщений в топике (будет работать автоматическая очистка).

kafka-topics.sh --zookeeper zookeeper:2181 --alter --topic mcd \
--config segment.ms=86400000

kafka-topics.sh --zookeeper zookeeper:2181 --alter --topic mcd \
--config retention.ms=86400000

segment.ms - время, которое определяет периодичность перестроения сегмента

retention.ms - время хранения данных в журнале (время за которое consumer должен забрать данные из очереди сообщений)

Изменить число партиций топика (позволяет масштабировать сервис).

kafka-topics.sh --zookeeper zookeeper:2181 --alter --topic mcd \
--partitions 1

Можно выполнить все вышеперечисленные настройки одной командой, например:

docker exec ${CONTAINER_ID} sh /opt/bitnami/kafka/bin/kafka-topics.sh --create --bootstrap-server ${KAFKA_HOST}:9092 --replication-factor 1 --partitions 1 --topic mcd --config retention.ms=86400000 --config segment.ms=86400000 --config segment.bytes=209715200 --config cleanup.policy=delete --config file.delete.delay.ms=1

Для проверки того что топик был корректно создан можно выполнить команды:

docker exec ${CONTAINER_ID} sh /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server ${KAFKA_HOST}:9092 --list
docker exec ${CONTAINER_ID} sh /opt/bitnami/kafka/bin/kafka-configs.sh --bootstrap-server ${KAFKA_HOST}:9092 --describe --all --entity-type topics --entity-name ${TOPIC_NAME}

${KAFKA_HOST} - адрес хоста, на котором запущена кафка

${TOPIC_NAME} - имя топика, в нашем случае - mcd

Установка eltex-mcdonalds

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

apt install eltex-mcdonalds

Настройка


Настройка Captive portal

Следует помнить, что в McDonald's летит информация только о тех, что дал явное согласие на получение рекламы.

В настройках портала 'Общие', 'Рекламная рассылка' нужно установить 'Спрашивать согласие пользователей на рассылку'.

Параметр 'Обязательное поле' запрещает оказывать услугу тем, что не дал согласие на получение рекламы. Установка этого флага остается на усмотрение заказчика.

Настройка PCRF

Для работы с брокером сообщений Kafka, в конфигурационный файл /etc/eltex-pcrf/eltex-pcrf.json добавлен блок параметров "kafka".

Пример дефолтной конфигурации:

eltex-pcrf.json
  "kafka": {
    "bootstrap.servers": "localhost:9092",
    "mcd.enabled": false,
    "linger.ms": "1000",
    "topic": "mcd",
    "max.block.ms": "5000",
    "acks": "1"
  }
ПараметрОписаниеЗначение по умолчанию

bootstrap.servers

Адрес Kafka сервера.

"localhost:9092"

mcd.enabled

Параметр, отвечающий за использование отправки в Kafka. То есть по умолчанию этот функционал отключен.false

linger.ms

Устанавливает искусственную задержку отправки сообщений для буферизации пакетов Kafka, мс."1000"

topic

Имя топика Kafka, в который будет происходить отправка."mcd"

max.block.ms

Время на формирование блока данных для Kafka (получение метаданных и аллокации буфера), мс. Сериализация данных, ожидание ответа на запрос в это таймаут не входят."5000"

acks

Количество подтверждений от сервера о доставке сообщения. Может быть установлен в значение "0" для отправки без подтверждения."1"

Настройка eltex-mcdonalds

Конфигурационный файл для настройки доступен по пути /etc/eltex-mcdonalds/application.conf

Пример дефолтной конфигурации:

application.conf
mcd {
    baseUrl: "http://localhost:5555"
    requestTimeoutMs: 5000
    connectTimeoutMs: 5000
    socketTimeoutMs: 5000
    rootDomain: "mcd.root"
    appToken: "token"
    pollPeriodMs: 1000
    chunkSize: 100
    kafkaTopic: "mcd"
}

kafka {
    bootstrap.servers: "localhost:9092"
    group.id: "mcd"
    auto.offset.reset: "latest"
}


ПараметрОписаниеЗначение по умолчанию
Параметры Eltex-mcdonalds
baseUrlURL McD-API назначения для отправки данных."http://localhost:5555"
requestTimeoutMsТаймаут запроса к серверу назначения, мс.5000
connectTimeoutMsТаймаут установки соединения с сервером назначения, мс.5000
socketTimeoutMsТаймаут отправки/получения пакетов, мс.5000
rootDomainФильтр по домену для входящих сообщений от Kafka.
appTokenТокен для обращения к внешнему серверу.""
pollPeriodMsПараметр настраивающий период отправки сообщений по API McDonalds, мс.10000
chunkSizeМаксимальный размер (число сессий) порции передачи данных в McDonalds API.100
kafkaTopicИмя топика Kafka из которого Eltex-mcdonalds читает сообщения."mcd"
Параметры доступа к Kafka
bootstrap.servers Адрес Kafka сервера."127.0.0.1:9092"
group.idГруппа к которой принадлежит потребитель сообщений. Разные сущности сервиса одного типа должны иметь одинаковый group.id, что дает возможность резервирования и масштабирования сервиса)
"mcd"
auto.offset.reset

Параметр определяет, какие сообщения необходимо загружать из топика. Может принимать значения:

  • "earliest" – все сообщения с начала топика;
  • "latest" – чтение с конца топика.
"latest"



Докеризация сервиса eltex-mcdonalds

Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.

eltex-mcdonalds docker-compose
version: "3"
services:
  eltex-mcdonalds:
    container_name: eltex-mcdonalds
    image: hub.eltex-co.ru/softwlc/eltex-mcdonalds:1.20-<tag>
    # Ограничиваем контейнеру потребление ОЗУ
    mem_limit: 128m
    environment:
      # Адрес шлюза McDonalds к которому обращается сервис
      - CONFIG_FORCE_mcd_baseUrl=${MCD_BASE_URL}
      - CONFIG_FORCE_mcd_requestTimeoutMs=${MCD_REQUEST_TIMEOUT_MS}
      - CONFIG_FORCE_mcd_connectTimeoutMs=${MCD_CONNECT_TIMEOUT_MS}
      - CONFIG_FORCE_mcd_socketTimeoutMs=${MCD_SOCKET_TIMEOUT_MS}
      # Фильтр по домену для входящих сообщений от Kafka
      - CONFIG_FORCE_mcd_rootDomain=${MCD_ROOT_DOMAIN}
      # Токен, для обращения к шлюзу McDonalds
      - CONFIG_FORCE_mcd_appToken=${MCD_APP_TOKEN}
      - CONFIG_FORCE_mcd_pollPeriodMs=${MCD_POLL_PERIOD_MS}
      - CONFIG_FORCE_mcd_chunkSize=${MCD_CHUNK_SIZE}
      # Название Kafka-топика
      - CONFIG_FORCE_mcd_kafkaTopic=${MCD_KAFKA_TOPIC}
      # Адрес сервера Kafka
      - CONFIG_FORCE_kafka_bootstrap_servers=${MCD_KAFKA_BOOTSTRAP_SERVERS}
      # Имя группы (необязательно)
      - CONFIG_FORCE_kafka_group_id=${MCD_KAFKA_GROUP_ID}
      - CONFIG_FORCE_kafka_auto_offset_reset=${MCD_KAFKA_AUTO_OFFSET_RESET}
      # Уровень логирования сервиса
      - MCD_LOG_LEVEL=${MCD_LOG_LEVEL}
Вместо <tag> необходимо указать актуальную версию, которую можно посмотреть по ссылке.
.env
MCD_BASE_URL=http://localhost:5555
MCD_REQUEST_TIMEOUT_MS=5000
MCD_CONNECT_TIMEOUT_MS=5000
MCD_SOCKET_TIMEOUT_MS=5000
MCD_ROOT_DOMAIN=root
MCD_APP_TOKEN=token
MCD_POLL_PERIOD_MS=1000
MCD_CHUNK_SIZE=100
MCD_KAFKA_TOPIC=mcd

MCD_KAFKA_BOOTSTRAP_SERVERS=localhost:9092
MCD_KAFKA_GROUP_ID=mcd
MCD_KAFKA_AUTO_OFFSET_RESET=latest

MCD_LOG_LEVEL=info

Файлы .env и docker-compose.yml должны находиться в одной папке. Контейнер запускается командой:

command
docker-compose up

Мониторинг

Для понимания работоспособности функционала на ядре доступны следующие механизмы.

PCRF

Доступны Prometheus  метрики обработки сообщений.

Метрики, срабатывающие на методе KafkaProducer.send (отправка сообщений в шину данных).

  • KafkaProducer.sendFailed - счетчик ошибок ;

  • KafkaProducer.sendSuccess - счетчик успешной отправки.

eltex-mcdonalds

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


  • Нет меток