Merge pull request #279 from NikitaSkrynnik/monitor

Add feature description: Connection Monitoring API

content/docs/concepts/components_description.md

@@ -174,7 +174,7 @@ Admission Webhook K8s simplifies working with NSM if NSM is deployed in a Kubern
 2. Fills in remaining connection properties like IP, hardware addresses, and DNS configurations for the user's goals.
 
 ## Network Service Client (NSC)
-**Network Service Client** allows external workloads to request access to NSM's **Network Services** and maintains connections ([Controlplane](https://networkservicemesh.io/docs/concepts/features/healing) and [Dataplane](https://networkservicemesh.io/docs/concepts/features/datapath_healing) healing). This component can also provide a local DNS Server for accessing NSM resources by their names.
+**Network Service Client** allows external workloads to request access to NSM's **Network Services** and maintains connections ([Controlplane](https://networkservicemesh.io/docs/concepts/specification/healing) and [Dataplane](https://networkservicemesh.io/docs/concepts/specification/datapath_healing) healing). This component can also provide a local DNS Server for accessing NSM resources by their names.
 
 **Package**: https://github.com/networkservicemesh/cmd-nsc/pkgs/container/cmd-nsc
 

content/docs/concepts/features.md → content/docs/concepts/specs.md

@@ -1,13 +1,14 @@
 +++
-title = "Features"
+title = "Specs"
 description = "Concepts of NSM Capabilities"
 weight = 5
 date = "2023-06-24"
 +++
 
-## Features
+## Specs
 
 Since NSM can run in any environment, here is described only concepts of the available functionality.
 
-- [Healing](../features/healing)
-- [Datapath Healing](../features/datapath_healing)
+- [Healing](../specs/healing)
+- [Datapath Healing](../specs/datapath_healing)
+- [Connection Monitoring API](../specs/monitoring)

content/docs/concepts/features/datapath_healing.md → content/docs/concepts/specs/datapath_healing.md

@@ -98,4 +98,4 @@ See at [example of kernel liveness check](https://github.com/networkservicemesh/
 
 - [Source code](https://github.com/networkservicemesh/sdk/blob/release/v1.10.0/pkg/networkservice/common/heal/options.go#L43-L48)
 - [Root issue](https://github.com/networkservicemesh/sdk/issues/1187)
-- [See other features](../)
+- [See other concepts](../)

content/docs/concepts/features/healing.md → content/docs/concepts/specs/healing.md

@@ -19,14 +19,14 @@ date = "2021-06-19"
 **Enhanced Reliability:** healing enhances the reliability of applications by automatically recovering from failures, reducing manual intervention, and minimizing downtime. \
 **Improved User Experience:** The feature ensures a consistent user experience by maintaining service availability, even when underlying infrastructure or application components experience issues. \
 **Efficient Resource Utilization:** Through proactive scaling and resource management, healing optimizes resource utilization, ensuring efficient NSM domain operation. \
-**Simplified Operations:** Healing simplifies operational tasks, reducing the burden on administrators and DevOps teams. \
+**Simplified Operations:** Healing simplifies operational tasks, reducing the burden on administrators and DevOps teams.
 
 ## Concept
 
 NSM healing  is pretty simple:
 
 1. Healing is always starting on the Network Service Mesh Client.
-2. Network Service Client uses [monitor connectios](https://github.com/networkservicemesh/api/blob/release/v1.10.0/pkg/api/networkservice/connection.proto#L79-L81) api to monitor it's NSMgr to keep the connection up to date.
+2. Network Service Client uses [monitor connections](https://github.com/networkservicemesh/api/blob/release/v1.10.0/pkg/api/networkservice/connection.proto#L79-L81) api to monitor it's NSMgr to keep the connection up to date.
 3. If the Network Service Client gets an event from the NSMgr with a changing state, deleting a connection, or closing a stream, then the client forces a new request. Wherein the existing connection closes only if connectivity is gone.
 
 And that's it!
@@ -43,7 +43,7 @@ Healing is an indispensable tool for organizations leveraging NSM, enabling them
 
 ## References
 
-- [NSM Monitoring API](https://github.com/networkservicemesh/api/blob/release/v1.10.0/pkg/api/networkservice/connection.proto#L79-L81)
+- [NSM Monitoring API](../../specs/monitoring)
 - [Code implementation](https://github.com/networkservicemesh/sdk/tree/release/v1.10.0/pkg/networkservice/common/heal)
 - [Runnable k8s examples](https://github.com/networkservicemesh/deployments-k8s/tree/release/v1.10.0/examples/heal)
-- [See other features](../)
+- [See other concepts](../)

content/docs/concepts/specs/monitoring.md

@@ -0,0 +1,60 @@
++++
+title = "Connection Monitoring API"
+description = "Concept of Connection Monitoring API in NSM"
+short= "monitoring"
+date = "2024-02-13"
++++
+
+# Connection Monitoring API
+
+## Description
+
+Connection Monitoring API allows users to monitor NSM connections. This functionality can be used to build some third-party applications. An example of such application is [NSM Dashboard](https://github.com/networkservicemesh/cmd-dashboard-ui).
+
+## Concept
+
+1. All NSM components except Network Service Client provide a Monitor Connection Server. 
+2. Users can connect to these servers using a Monitor Connection Client and monitor connections owned by different NSM components. 
+3. The components can send Connection Events to all subscribed Monitor Connection Clients if any connection is created, changed or deleted.
+
+Each NSM component montors connections of the next component in the chain. If the next component generates a Connection Event, the current component receives this event and sends it back to the previous component in the chain.
+
+## Types of events
+
+**INITIAL_STATE_TRANSFER:** MonitorConnection Server sends an event with this type to MonitorConnection Client when the client makes the first request. The event with this type contains all connections owned by the MonitorConnection Server.
+
+**UPDATE:** Monitor Connection Server sends an event with this type when a connection changes. For example, the state of the connection has been changed.
+
+**DELETE:** Monitor Connection Server sends event with this type when the connection has been closed.
+
+## Example of UPDATE event
+
+On the **Diagram 1** you can see when NSM sends **UPDATE** event. It has the following steps:
+1. NSM components monitor each other
+2. Forwader changes a connection context of one of connections
+3. Forwarder sends **UPDATE** event with the changed connection to NSMgr
+4. NSMgr sends **UPDATE** event with the changed connection to NSC
+
+<img src="/img/concepts/specs/monitoring/update-event.svg" style="border: 1px dashed black; padding: 0.8em">
+
+ *Diagram 1: an example of UPDATE event in NSM*
+
+## Example of INITIAL_STATE_TRANSFER, UPDATE and DELETE event
+
+**Diagram 2** shows when NSM sends **INITIAL_STATE_TRANSFER**, **UPDATE** and **DELETE** events. Steps:
+1. 3rd-party app start to monitor connections of NSMgr
+2. NSMgr sends **INITIAL_STATE_TRANSFER** event with all its connections
+3. NSC connects to NSE
+4. NSMgr sends **UPDATE** event with the new connection established between NSC and NSE
+5. NSC closes the connection
+6. NSMgr sends **DELETE** event with the closed connection
+
+<img src="/img/concepts/specs/monitoring/initial-transfer-and-delete-event.svg" style="border: 1px dashed black; padding: 0.8em">
+
+ *Diagram 2: an example of INITIAL_STATE_TRANSFER, UPDATE and DELETE event in NSM*
+
+## References
+
+- [NSM Connection Monitoring API Definition](https://github.com/networkservicemesh/api/blob/release/v1.10.0/pkg/api/networkservice/connection.proto#L79-L81)
+- [Code implementation](https://github.com/networkservicemesh/sdk/tree/release/v1.10.0/pkg/networkservice/common/monitor)
+- [See other concepts](../)