Documentation

Author: IoannisPanagiotas

doc/modules/ROOT/pages/common-usage/monitoring-system.adoc

@@ -104,3 +104,112 @@ Here we can note that there is only one GDS procedure currently running, namely
 We also see that it may use up to an estimated `234 kB` of memory.
 Note that it may not currently be using that much memory and so it may require more memory later in its execution, thus possible lowering our current `freeHeap`.
 Apparently it wants to use up to `16` CPU cores, leaving us with a total of `84` currently available cores in the system not requested by any GDS procedures.
+
+[[Memory-reporting-procedures]]
+== Memory reporting procedures
+
+To facilitate memory management, the Neo4j GDS Library offers two memory reporting procedures, alongside the aforementioned monitoring capabilities.
+
+[detailed-memory-listing]
+=== Detailed memory listing
+
+Through the `gds.listMemory` procedure, a user can obtain a combined list of their projected graphs and running tasks alongside their memory footprint.
+
+For graphs, the size of the in-memory graph is returned,  whereas  for algorithms the  memory estimation i.e., the maximum memory needs that this task is expected to require over the course of its execution.
+
+This procedure can help a user realize which of his operations might be memory demanding and plan accordingly (e.g., drop a graph, or termination a transaction).
+
+A user can access only his own graphs or tasks, but an admin can obtain information for all users.
+
+[[syntax]]
+==== Syntax
+.List the graphs and tasks of a user along with their memory footprint.
+[source, cypher, role=noplay]
+----
+CALL gds.listMemory()
+YIELD
+  user: String,
+  name: String,
+  entity: String
+  memoryInBytes: Integer
+----
+
+.Results
+[opts="header",cols="1,1,6"]
+|===
+| Name                          | Type        | Description
+| user                      | String     | The username
+| name                     | String     | The name of the graph or running task.
+| entity                       | String     | If the reporting entity is a task, this corresponds to its job id. Otherwise, it is set to "graph".
+| memoryInBytes          | Integer     | The occupying memory
+for a graph or the estimation of a task.
+|===
+
+=== Example
+
+.List running tasks and graphs for Bob.
+[source, cypher, role=noplay]
+----
+CALL gds.listMemory()
+YIELD
+  user, name, entity, memoryInBytes
+----
+
+.Results
+[opts="header",cols='2,2,2,2']
+|===
+| user | name | entity | memoryInBytes |
+"Bob" | "my-graph" | "graph" | 20 |
+"Bob" | "Node2Vec" | 111-222-333 | 234
+|===
+
+As we can see, Bob has projected a graph named 'my-graph' occupying  200 bytes memory, and is currently running Node2Vec which has a memory footprint of 234 bytes.
+
+[memory-summary]
+===  Memory Summary
+
+The `gds.listMemory.summary` procedure provides an overview of the total graph memory, and the total  memory requirements of running tasks for a given users.
+
+
+A user can access only his own graphs or tasks, but an admin can obtain information for all users.
+
+[[syntax]]
+==== Syntax
+.List the graphs and tasks of a user along with their memory footprint.
+[source, cypher, role=noplay]
+----
+CALL gds.listMemory.summary()
+YIELD
+  user: String,
+  totalGraphsMemory : Intger,
+  totalTasksMemory : Integer
+----
+
+.Results
+[opts="header",cols="1,1,6"]
+|===
+| Name                          | Type        | Description
+| user                      | String     | The username.
+|totalGraphsMemory |  Integer| The total requirement for that user's graphs.
+| totalTasksMemory          | Integer |  The total requirements of that user's tasks.
+|===
+
+=== Example
+
+.List running tasks and graphs for Bob.
+[source, cypher, role=noplay]
+----
+CALL gds.listMemory.summary()
+YIELD
+  user, totalGraphsMemory, totalTasksMemory
+----
+
+.Results
+[opts="header",cols='2,2,2']
+|===
+| user | totalGraphsMemory | totalTasksMemory |
+"Bob" | 20 | 234
+|===
+
+
+

proc/misc/src/integrationTest/java/org/neo4j/gds/MemoryProcTest.java

@@ -53,7 +53,7 @@ void shouldReturnEmptySummary() {
             "CALL gds.listMemory.summary",
             resultRow -> {
             assertThat(resultRow.getString("user")).isEqualTo("alice");
-                assertThat(resultRow.getNumber("totalGraphMemory")).asInstanceOf(LONG).isEqualTo(0);
+                assertThat(resultRow.getNumber("totalGraphsMemory")).asInstanceOf(LONG).isEqualTo(0);
                 assertThat(resultRow.getNumber("totalTasksMemory")).asInstanceOf(LONG).isEqualTo(0);
             });
         assertThat(rowCount).isEqualTo(1L);
@@ -97,7 +97,7 @@ void shouldSummarizeAccordingly() {
             "CALL gds.listMemory.summary",
             resultRow -> {
                 assertThat(resultRow.getString("user")).isEqualTo("bob");
-                assertThat(resultRow.getNumber("totalGraphMemory")).asInstanceOf(LONG).isEqualTo(0);
+                assertThat(resultRow.getNumber("totalGraphsMemory")).asInstanceOf(LONG).isEqualTo(0);
                 assertThat(resultRow.getNumber("totalTasksMemory")).asInstanceOf(LONG).isEqualTo(0);
             });
 
@@ -131,7 +131,7 @@ void canSummarizeRunningTask() {
             "CALL gds.listMemory.summary",
             resultRow -> {
                 assertThat(resultRow.getString("user")).isEqualTo("alice");
-                assertThat(resultRow.getNumber("totalGraphMemory")).asInstanceOf(LONG).isEqualTo(0);
+                assertThat(resultRow.getNumber("totalGraphsMemory")).asInstanceOf(LONG).isEqualTo(0);
                 assertThat(resultRow.getNumber("totalTasksMemory")).asInstanceOf(LONG).isGreaterThan(0);
             });
         assertThat(rowCountAlice).isEqualTo(1L);
@@ -140,7 +140,7 @@ void canSummarizeRunningTask() {
             "CALL gds.listMemory.summary",
             resultRow -> {
                 assertThat(resultRow.getString("user")).isEqualTo("bob");
-                assertThat(resultRow.getNumber("totalGraphMemory")).asInstanceOf(LONG).isEqualTo(0);
+                assertThat(resultRow.getNumber("totalGraphsMemory")).asInstanceOf(LONG).isEqualTo(0);
                 assertThat(resultRow.getNumber("totalTasksMemory")).asInstanceOf(LONG).isEqualTo(0);
             });
 

progress-tracking/src/main/java/org/neo4j/gds/mem/UserMemorySummary.java

@@ -19,5 +19,5 @@
  */
 package org.neo4j.gds.mem;
 
-public record UserMemorySummary(String user, long totalGraphMemory, long totalTasksMemory) {}
+public record UserMemorySummary(String user, long totalGraphsMemory, long totalTasksMemory) {}
 

progress-tracking/src/test/java/org/neo4j/gds/mem/MemoryTrackerTest.java

@@ -114,11 +114,11 @@ void shouldReturnMemoryForUser(){
         memoryTracker.onGraphStoreAdded(new GraphStoreAddedEvent("alice","neo4j","graph1",11));
 
         var  aliceMemory = memoryTracker.memorySummary("alice");
-        assertThat(aliceMemory.totalGraphMemory()).isEqualTo(11L);
+        assertThat(aliceMemory.totalGraphsMemory()).isEqualTo(11L);
         assertThat(aliceMemory.totalTasksMemory()).isEqualTo(12L);
 
         var  bobMemory = memoryTracker.memorySummary("bob");
-        assertThat(bobMemory.totalGraphMemory()).isEqualTo(0L);
+        assertThat(bobMemory.totalGraphsMemory()).isEqualTo(0L);
         assertThat(bobMemory.totalTasksMemory()).isEqualTo(5L);
 
     }
@@ -133,7 +133,7 @@ void shouldReturnMemoryForAll(){
 
         var list = memoryTracker.memorySummary().toList();
 
-        assertThat(list.stream()).map(UserMemorySummary::totalGraphMemory).containsExactlyInAnyOrder(11L,0L);
+        assertThat(list.stream()).map(UserMemorySummary::totalGraphsMemory).containsExactlyInAnyOrder(11L,0L);
         assertThat(list.stream()).map(UserMemorySummary::totalTasksMemory).containsExactlyInAnyOrder(12L,5L);
 
     }