Add documentation for Blazegraph supervision endpoints (#5209)

Co-authored-by: Simon Dumas <[email protected]>

docs/src/main/paradox/docs/delta/api/assets/supervision/supervision-blazegraph.json

@@ -0,0 +1,21 @@
+{
+  "assigned": [
+    {
+      "count": 311,
+      "project": "org/project1",
+      "view": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex"
+    },
+    {
+      "count": 940,
+      "project": "org/project2",
+      "view": "https://bluebrain.github.io/nexus/vocabulary/defaultSparqlIndex"
+    }
+  ],
+  "total": 1251,
+  "unassigned": [
+    {
+      "count": 0,
+      "namespace": "kb"
+    }
+  ]
+}

docs/src/main/paradox/docs/delta/api/assets/supervision/supervision-blazegraph.sh

@@ -0,0 +1 @@
+curl "http://localhost:8080/v1/supervision/blazegraph"

docs/src/main/paradox/docs/delta/api/supervision-api.md

@@ -1,6 +1,8 @@
 # Supervision
 
-This endpoint returns information about the projections running on the current node.
+Those endpoints return information which helps to monitor and investigate problems in Nexus.
+
+To access those endpoints, the `supervision/read` permission must be granted at the root level.
 
 ## Fetch projections
 
@@ -53,3 +55,31 @@ Request
 
 Response
 :   @@snip [project-heal.json](assets/supervision/project-heal.json)
+
+## Blazegraph
+
+This endpoint allows to return the total number of triples for all blazegraph views 
+and the number of triples per individual view.
+
+The unassigned part allows to spot orphan namespaces, that is to say namespaces which may not have been properly deleted
+when a view got modified or deprecated.
+
+This is an indicator which helps to scale correctly the @ref:[Blazegraph instance](../../getting-started/running-nexus/blazegraph.md).
+
+```
+GET /v1/supervision/blazegraph
+```
+
+Request
+:   @@snip [supervision-blazegraph.sh](assets/supervision/supervision-blazegraph.sh)
+
+Response
+:   @@snip [supervision-blazegraph.json](assets/supervision/supervision-blazegraph.json)
+
+## Composite views
+
+This endpoint serves the same purpose but for common namespaces of composite views.
+
+```
+GET /v1/supervision/composite-views
+```

docs/src/main/paradox/docs/getting-started/running-nexus/blazegraph.md

@@ -38,6 +38,11 @@ It is likely to happen when reindexing after updating search but if it happens r
 Blazegraph will use the available RAM in 2 ways, JVM heap and the file system cache
 so like Elasticsearch, the JVM garbage collection frequency and duration are also important to monitor.
 
+Using the supervision endpoints for @ref:[Blazegraph](../../delta/api/supervision-api.md#blazegraph) 
+and @ref:[composite views](../../delta/api/supervision-api.md#composite-views) and 
+the @link:[RAM guidance from Blazegraph](https://github.com/blazegraph/database/wiki/Hardware_Configuration#ram-sizing-guidance)
+gives some insights on how much memory can be assigned.
+
 **Storage:**
 
 Blazegraph stores data in an append only journal which means updates will use additional disk space.
@@ -51,6 +56,11 @@ to reduce the disk usage, but it takes quite a bit a time and requires taking th
 An alternative can be to reindex on a fresh instance of Blazegraph, this approach also allows to reconfigure the
 underlying namespaces.
 
+Using the supervision endpoints for @ref:[Blazegraph](../../delta/api/supervision-api.md#blazegraph)
+and @ref:[composite views](../../delta/api/supervision-api.md#composite-views) and
+the @link:[Data on disk guidance from Blazegraph](https://github.com/blazegraph/database/wiki/Hardware_Configuration#data-on-disk-sizing-guidance)
+gives some insights on how much storage can be assigned.
+
 **Query and indexing performance:**
 
 Query load and latency must be monitored to make sure that information in a timely manner to the client.