| Status | IN PROGRESS |
|---|---|
| Stakeholders | |
| Outcome | |
| Due date | |
| Owner |
Background
Iroha Users need information about "system" aspects which are not available via Iroha Queries to World State View, for example
Abstract
Clients needs information about Iroha entities outside `WorldStateView`:
Peer's Health Check (Naming of states inspired by Prometheus)
Peer's Management - start, stopResources Monitoring - CPU, Memory and Disk consumption
- Logging Configuration
Business Measurements of Iroha
Transactions per second amount
Blocks Storage size
- Submitted transactions statuses changes
- Blocks statuses changes
...
Problem
For some clients and for Iroha administrators it is important to have more information than can be provided by the Iroha Data Model.
One of such a cases were described by the following requirements:
...
Because transactions states changes are not stored on the Blockchain and can't be presented in World State View `Maintenance Endpoint` is a good place to add this functionality to.
...
Solution
As a result Iroha provides an additional endpoint for maintenance purposes, described in Abstract.
Some of requests answered with "current state" responses information like CPU and Memory consumption.
For "subscribe" functionality connection should be permanent and still - network problems, peers or clients disconnections and other troubles will lead to automatic end of "subscription".
we can create additional client-facing Iroha API which described in the table below:
| API | URI | Protocol | Comments |
|---|---|---|---|
| Configuration | `/config` | HTTP | REST API for managing Iroha Peer's configuration:
|
| Monitoring | `/health` | HTTP | Aligned with Prometheus Peer's Health Check information |
| `/metric` | HTTP | Metrics ready to be scraped by Prometheus | |
| Events | `/event` | WebSocket | Human friendly WS API for Cloud Events consumers |
| TCP/IP | Low-level API with binary messages for Cloud Events consumers |
Each API responsible for subset of maintenance features. Events API available in two variants - WebSocket for mobile clients, web applications and other human oriented technologies, while TCP/IP option for those clients which resources are limited.
Decisions
- Use HTTP for configuration and monitoring APIs (message format can be json or text based on Prometheus specification)
- Events API implemented as WebSocket and proprietary TCP/IP variants
- Additional port should be used by Maintenance Endpoint
Alternatives
- We can stay with TCP approach but we will need to change DevOps processes and tools, Substrate Off-chain workers also will not be able to deal with TCP
- We can use HTTP for Events API but it's not effective way to handle active sessions between Iroha Peers and Substrate Off-chain workers
Assumptions
Different system events will be aligned with CNCF CloudEvents Specification and may be used in non-maintenance endpoints later.
Concerns
...
To prevent secured information losses `subscribers` should receive only information they had permissions to have. The "CanAnything" permission will provide information about the entire system and most of maintenance endpoints will require accounts with it. If account has no "CanAnything" permission, it's signature should be presented in transactions to receive information about their states changes.
Events
Risks
- Substrate off-chain workers integration will require additional parties (no direct communication with Iroha) `[9;4]`
- Support of two variants for Events API will require additional maintenance resources `[7;2]`
Additional Information
- https://github.com/cloudevents/spec/blob/v1.0/spec.md
- https://prometheus.io/docs/instrumenting/exposition_formats/
- https://substrate.dev/docs/en/knowledgebase/runtime/off-chain-workers#fetching-external-data
...