Служба мониторинга
==================

Пир и ордерер размещают у себя HTTP-сервер с REST API. Это API не связано со службами
сети Fabric и предназначается для использования операторами по мониторингу, а не администраторами или
"пользователям" сети.

API имеет следующие функции:

- Управление логированием
- Проверка работоспособности (Health checks)
- Prometheus-метрики (если настроено)
- Информация о версии

Настройка службы мониторинга
-----------------------------

Служба мониторинга (operations service) зависит от двух основных фрагментов конфигурации:

- **адрес** и **порт**, которые она будет прослушивать
- **TLS-сертификаты** и **ключи** для аутентификации и шифрования.
  Заметьте, что **эти сертификаты должны быть сгенерированы отдельным выделенным под это CA**.
  Не используйте CA, который генерировал сертификаты для любых организаций любых каналов.

Пир
~~~

Для каждого пира, сервер службы может быть настроен в секции
``operations`` файла ``core.yaml``:

.. code:: yaml

  operations:
    # адрес и порт сервера
    listenAddress: 127.0.0.1:9443

    # TLS-конфигурация для защищенного взаимодействия с пользователями API
    tls:
      # Включить TLS
      enabled: true

      # Путь к TLS-сертификату сервера в формате PEM
      cert:
        file: tls/server.crt

      # Путь к TLS-ключу сервера в формате PEM
      key:
        file: tls/server.key

      # Большинство функций сервера требует аутентификации, если включен TLS.
      # clientAuthRequired требует аутентификации клиента через его сертификат на уровне TLS
      clientAuthRequired: false

      # Пути к CA сертификатам, выписавывающих сертификаты клиентам, которым нужно доверять
      # для того, чтобы обеспечить аутентификацию клиента.
      clientRootCAs:
        files: []

Поле ``listenAddress`` определяет адрес и порт, которые будут прослушиваться сервером.
Если сервер должен прослушать все адреса, часть `host` может быть опущена.

Секция ``tls`` определяет, включен ли TLS для службы мониторинга, путь к сертификату и приватному ключу службы,
а также пути к центрам сертификации, которым необходимо доверять для обеспечения аутентификации клиентов.
Кода TLS включен (``enabled: true``), большинство функций API потребует аутентификации клиента, следовательно должны быть указаны
``clientRootCAs.files``. Когда ``clientAuthRequired: true``, прослойка TLS будет требовать от клиентов сертификат для аутентификации с каждыми запросом.
Для более подробной информации смотрите секцию Безопасность службы.

Ордерер
~~~~~~~

Для ordering-службы сервер может быть настроен в секции ``Operations`` файла ``orderer.yaml``:

.. code:: yaml

  Operations:
    # адрес и порт сервера
    listenAddress: 127.0.0.1:9443

    # TLS-конфигурация для защищенного взаимодействия с пользователями API
    tls:
      # Включить TLS
      enabled: true

      # Путь к TLS-ключу сервера в формате PEM
      PrivateKey: tls/server.key

      # Путь к TLS-сертификату сервера в формате PEM
      Certificate: tls/server.crt

      # Пути к CA сертификатам, выписавывающих сертификаты клиентам, которым нужно доверять
      # для того, чтобы обеспечить аутентификацию клиента.
      ClientRootCAs: []

      # Большинство функций сервера требует аутентификации, если включен TLS.
      # clientAuthRequired требует аутентификации клиента через его сертификат на уровне TLS
      ClientAuthRequired: false

Поле ``listenAddress`` определяет адрес и порт, которые будут прослушиваться сервером.
Если сервер должен прослушать все адреса, часть `host` может быть опущена.

Секция ``tls`` определяет, включен ли TLS для службы мониторинга, путь к сертификату и приватному ключу службы,
а также пути к центрам сертификации, которым необходимо доверять для обеспечения аутентификации клиентов.
Кода TLS включен (``enabled: true``), большинство функций API потребует аутентификации клиента, следовательно должны быть указаны
``clientRootCAs.files``. Когда ``clientAuthRequired: true``, прослойка TLS будет требовать от клиентов сертификат для аутентификации с каждым запросом.
Для более подробной информации смотрите секцию Безопасность службы.

Безопасность службы
~~~~~~~~~~~~~~~~~~~

Так как эта служба занимается мониторингом и специально не связана с сетью Fabric,
она не использует MSP или ACL. Вместо этого, служба мониторинга работает взаимной
TLS аутентификации между службой и клиентом.

Когда TLS выключен, аутентификация пропускается и любой клиент, подсоединившийся к API, сможет его использовать.

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

Когда включен clientAuthRequired, прослойка TLS потребует от клиента валидный сертификат для осуществления любого запроса.

Управление логированием
~~~~~~~~~~~~~~~~~~~~~~~

Служба мониторинга предоставляет ресурс ``/logspec``, который операторы могут использовать, чтобы
управлять включенным логированием пира или ордерера. Ресурс - стандартный REST-ресурс и поддерживает запросы
``GET`` и ``PUT``.

Когда служба получает запрос ``GET /logspec``, она ответит
значением JSON, содержащим текущую спецификацию логирования:

.. code:: json

  {"spec":"info"}

Когда служба получает запрос ``PUT /logspec``, она прочитает body запроса как значение JSON.
Значение должно содержать единственный атрибут ``spec``.

.. code:: json

  {"spec":"chaincode=debug:info"}

Если новая спецификация была успешно активирована, сервис вернет ответ ``204 "No Content"``.
Если случилась ошибка, сервис вернет ``400 "Bad Request"``
и значение JSON:

.. code:: json

  {"error":"error message"}

Проверка работоспособности (Health Checks)
-------------------------------------------

Служба мониторинга предоставляет ресурс ``/healthz``, который операторы могут использовать, чтобы
определить работоспособность пиров и ордереров. Ресурс - традиционный REST-ресурс, поддерживающий
GET запросы. Реализация совместима с проверками работоспособности, используемыми Kubernetes.

Когда служба получает запрос ``GET /healthz``, она вызовет определенный проверки работоспособности
пира или ордерера. Если все проверки завершились успешно, она пошлет ответ с
``200 "OK"`` и таким JSON body:

.. code:: json

  {
    "status": "OK",
    "time": "2009-11-10T23:00:00Z"
  }

Если одна или более проверок возвратили ошибку, служба ответит с
``503 "Service Unavailable"`` и JSON body, включающем информацию о неудавшихся проверках:

.. code:: json

  {
    "status": "Service Unavailable",
    "time": "2009-11-10T23:00:00Z",
    "failed_checks": [
      {
        "component": "docker",
        "reason": "failed to connect to Docker daemon: invalid endpoint"
      }
    ]
  }

В текущей версии, единственные определенные проверки - для Docker.
В будущих версиях набор проверок будет расширен.

Когда TLS включен, сертификат клиента не требуется, если только ``clientAuthRequired`` не установлен на ``true``.

Метрики
-------

Некоторые компоненты пира и ордерера экспортируют метрики, которые могут позволяют
получить представления о поведении системы. Операторы и администраторы могут использовать эту информацию, чтобы
лучше понять, как система функционирует в течении определенного периода времени.

Настройка метрик
~~~~~~~~~~~~~~~~

Fabric предоставляет два способа экспорта метрик: pull-модель на основе
Prometheus и push-модель на основе StatsD.

Prometheus
~~~~~~~~~~

Стандартно настроенный Prometheus собирает метрики, запрашивая их через HTTP endpoint.
Так как при таком поведении Prometheus отвечает за сбор метрик, он считается
pull-системой.

При должной настройке, пиры или ордереры предоставят ресурс ``/metrics``:

* Пир: секция ``metrics`` файла ``core.yaml``.

.. code:: yaml

  metrics:
    provider: prometheus

* Ордерер: секция ``Metrics`` файла ``orderer.yaml``.

.. code:: yaml

  Metrics:
    Provider: prometheus

StatsD
~~~~~~

StatsD - простой daemon сбора статистики. Метрики отсылаются к
``statsd`` daemon, где они собираются, распределяются по категориям и отсылаются на бекенд
для визуализации и выдачи предупреждений. Так как эта модель требует правильно настроенного процесса
для отправления статистических данных StatsD, это считается push-системой

Пир
^^^

Пир можно настроить, чтобы он посылал метрики StatsD, если установить ``metrics provider``
на ``statsd`` в секции ``metrics`` файла ``core.yaml``. Подсекция ``statsd``
также должна быть настроена: необходимо указать адрес демона StatsD,
протокол передачи данных (``tcp`` или ``udp``), а также как часто необходимо отсылать метрики. Опциональный
``prefix`` может быть указан, чтобы различать источник метрик, например, чтобы собирать метрики отдельно для каждого пира.

.. code:: yaml

  metrics:
    provider: statsd
    statsd:
      network: udp
      address: 127.0.0.1:8125
      writeInterval: 10s
      prefix: peer-0

Ордерер
^^^^^^^

Ордерер можно настроить, чтобы он посылал метрики StatsD, если установить ``metrics provider``
на ``statsd`` в секции ``Metrics`` файла ``orderer.yaml``. Подсекция ``statsd``
также должна быть настроена: необходимо указать адрес демона StatsD,
протокол передачи данных (``tcp`` или ``udp``), а также как часто необходимо отсылать метрики. Опциональный
``prefix`` может быть указан, чтобы различать источник метрик, например, чтобы собирать метрики отдельно для каждого ордерера.

.. code:: yaml

  Metrics:
      Provider: statsd
      Statsd:
        Network: udp
        Address: 127.0.0.1:8125
        WriteInterval: 30s
        Prefix: org-orderer

Чтобы узнать, как создаются различные метрики, посетите
:doc:`metrics_reference`.

Версия
------

Службы ордерера и пира обе имеют ``/version`` endpoint. Этот endpoint
служит как документ JSON, содержащий версию пира или ордерера и SHA коммита, лежащего в основе релиза.

.. Licensed under Creative Commons Attribution 4.0 International License
   https://creativecommons.org/licenses/by/4.0/