jina-ai · hanxiao · Jun 9, 2022 · Jun 9, 2022
diff --git a/docs/api.md b/docs/api.md
@@ -5,5 +5,5 @@ This section includes the API documentation from the `jina` codebase. These are
 ```{toctree}
 
 api/jina
-api/cli
+api/jina_cli
 ```
diff --git a/docs/fundamentals/executor/monitoring-executor.md b/docs/fundamentals/executor/monitoring-executor.md
@@ -1,6 +1,9 @@
 (monitoring-executor)=
 # Monitor
 
+By default, every method which is decorated by the `@requests` decorator will be monitored, it will create a
+[Prometheus Summary](https://prometheus.io/docs/concepts/metric_types/#summary) which will keep track of the time of 
+the execution of the method.
 
 This section documents the ability to add custom monitoring to the Executor with the Grafana/Prometheus.
 
@@ -9,19 +12,15 @@ the full power of the [Prometheus Client](https://github.com/prometheus/client_p
 for each of your Executors. We provide a convenient wrapper as well, i.e `@monitor()`, which let you easily monitor
 sub-method of your Executor. 
 
+When the monitoring is enabled each Executor will expose its 
+own metrics. This means that in practice each of the Executors will expose a Prometheus endpoint using the [Prometheus Client](https://github.com/prometheus/client_python).
 
 ```{admonition} Full detail on monitoring
 :class: seealso
 This section describes how to define and use **custom** metrics. To use the default metrics exposed by the Executor 
 please refer to {ref}`this <monitoring-flow>` section.
 ```
 
-When the monitoring is enabled each Executor will expose its 
-own metrics. This means that in practice each of the Executors will expose a Prometheus endpoint using the [Prometheus Client](https://github.com/prometheus/client_python).
-
-By default, every method which is decorated by the `@requests` decorator will be monitored, it will create a
-[Prometheus Summary](https://prometheus.io/docs/concepts/metric_types/#summary) which will keep track of the time of 
-the execution of the method.
 
 ## Define custom metrics
 
@@ -33,12 +32,28 @@ image embedding. By using custom metrics on these two tasks you can identify pot
 
 Overall the ability to add custom metrics allows you to have the full flexibility on the monitoring of your Executor.
 
-### Defining custom metrics with `@monitor`
+### Use context manager
 
-````{admonition} Using @monitor
-:class: hint
-Adding the custom monitoring on a method is as straightforward as decorating the method with `@monitor` 
-````
+You can use `self.monitor` to monitor the internal blocks of your function:
+
+```python
+from jina import Executor, requests
+
+
+class MyExecutor(Executor):
+    @requests
+    def foo(self, docs, **kwargs):
+        with self.monitor('processing_seconds', 'Time processing my document'):
+            docs = process(docs)
+        print(docs.texts)
+        with self.monitor('update_seconds', 'Time updates my document'):
+            docs = update(docs)
+```
+
+
+### Use `@monitor` decorator
+
+Adding the custom monitoring on a method is as straightforward as decorating the method with `@monitor`.
 
 ```python
 from jina import Executor, monitor
@@ -64,30 +79,51 @@ def method(self):
     ...
 ```
 
-You can as well monitor internal part of your executor with a Context Manager:
+````{admonition} respect Prometheus naming
+:class: caution
+You should respect Prometheus naming [conventions](https://prometheus.io/docs/practices/naming/#metric-names). 
+therefore because `@monitor` creates a [Summary](https://prometheus.io/docs/concepts/metric_types/#summary) under the hood
+your metrics name should finish with `seconds`
+````
 
-```python
-from jina import Executor, requests
+### Use Prometheus client
 
+Under the hood, the monitoring feature of the Executor is handled by the 
+Python [Prometheus-client](https://github.com/prometheus/client_python). The `@monitor` decorator is a convenient tool
+to monitor sub-methods of an Executor, but you might need more flexibility and that is why you can access the Prometheus
+client directly from the Executor to define every kind of metric supported by Prometheus.
 
-def process():
-    ...
+Let's see it in an example
+
+
+```python
+from jina import requests, Executor, DocumentArray
+
+from prometheus_client import Counter
 
 
 class MyExecutor(Executor):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.counter = Counter(
+            name='my_count_total',
+            documentation='my count',
+            registry=self.runtime_args.metrics_registry,
+        )
+
     @requests
-    def foo(self, docs, **kwargs):
-        with self.monitor('processing_seconds', 'Time processing my document'):
-            docs = process(docs)
+    def encode(self, docs: DocumentArray, **kwargs):
+        self.counter.inc(len(docs))
 ```
 
-````{admonition} respect Prometheus naming
+This will create a Prometheus [Counter](https://prometheus.io/docs/concepts/metric_types/#counter). 
+
+````{admonition} Directly using the Prometheus client
 :class: caution
-You should respect Prometheus naming [conventions](https://prometheus.io/docs/practices/naming/#metric-names). 
-therefore because `@monitor` creates a [Summary](https://prometheus.io/docs/concepts/metric_types/#summary) under the hood
-your metrics name should finish with `seconds`
+You need to pass the metrics registry from the Executor when creating custom metrics directly with the Prometheus client.
 ````
 
+
 ## Example
 
 Let's take an example to illustrate custom metrics:
@@ -164,43 +200,6 @@ class MyExecutor(Executor):
 ```
 ````
 
-### Defining custom metrics directly with the Prometheus client
-
-Under the hood, the monitoring feature of the Executor is handled by the 
-Python [Prometheus-client](https://github.com/prometheus/client_python). The `@monitor` decorator is a convenient tool
-to monitor sub-methods of an Executor, but you might need more flexibility and that is why you can access the Prometheus
-client directly from the Executor to define every kind of metric supported by Prometheus.
-
-Let's see it in an example
-
-
-```python
-from jina import requests, Executor, DocumentArray
-
-from prometheus_client import Counter
-
-
-class MyExecutor(Executor):
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.counter = Counter(
-            name='my_count_total',
-            documentation='my count',
-            registry=self.runtime_args.metrics_registry,
-        )
-
-    @requests
-    def encode(self, docs: DocumentArray, **kwargs):
-        self.counter.inc(len(docs))
-```
-
-This will create a Prometheus [Counter](https://prometheus.io/docs/concepts/metric_types/#counter). 
-
-````{admonition} Directly using the Prometheus client
-:class: caution
-You need to pass the metrics registry from the Executor when creating custom metrics directly with the Prometheus client.
-````
-
 
 ## See further