Logging

In the GDS library there are three types of logging: debug logging, progress logging and hints or warnings logging.

Debug logging provides information about events in the system. For example, when an algorithm computation completes, the amount of memory used and the total runtime may be logged. Exceptional events, when an operation fails to complete normally, are also logged. The debug log information is useful for understanding events in the system, especially when troubleshooting a problem.

Progress logging is performed to track the progress of operations that are expected to take a long time. This includes graph projections, algorithm computation, and result writing.

Hints or warnings logging provides the user with useful hints or warnings related to their queries.

All log entries are written to the log files configured for the Neo4j database. For more information on configuring Neo4j logs, please refer to the Neo4j Operations Manual.

Progress-logging procedure

Progress is also tracked by the GDS library itself. This makes it possible to inspect progress via Cypher, in addition to looking in the log files. To access progress information for currently running tasks (also referred to as jobs), we can make use of the list progress procedure: gds.listProgress. A task in the GDS library is defined as a running procedure, such as an algorithm or a graph load procedure.

The list progress procedure has two modes, depending on whether a jobId parameter was set: First, if jobId is not set, the procedure will produce a single row for each task currently running. This can be seen as the summary of those tasks, displaying the overall progress of a particular task for example. Second, if the jobId parameter is set it will show a detailed view for the given running job. The detailed view will produce a row for each step or task that job will perform during execution. It will also show how tasks are structured as a tree and print progress for each individual task.

For users with administrator privileges, this procedure will list the running tasks of all users.

Syntax

Getting the progress of tasks:

CALL gds.listProgress(jobId: String)
YIELD
  username,
  jobId,
  taskName,
  progress,
  progressBar,
  status,
  timeStarted,
  elapsedTime

Table 1. Parameters
Name	Type	Default	Optional	Description
jobId	String	""	yes	The jobId of a running task. This will trigger a detailed overview for that particular task.

Table 2. Results
Name	Type	Description
`username`	String	The user who started the running task.
`jobId`	String	A generated identifier of the running task.
`taskName`	String	The name of the running task, i.e. `Node2Vec`.
`progress`	String	The progress of the job shown as a percentage value.
`progressBar`	String	The progress of the job shown as an ASCII progress bar.
`status`	String	The current status of the job, i.e. `RUNNING` or `CANCELED`.
`timeStarted`	LocalTime	The local wall clock time when the task has been started.
`elapsedTime`	Duration	The duration from `timeStarted` to now.

Some kinds of jobs that typically take while to run, like graph projections and running algorithms, takes an optional jobId in their configuration parameter maps. This can make tracking them easier as they will then be listed under the provided jobId in the gds.listProgress results. For algorithms, see the jobId parameter documentation for more on this.

Examples

Assuming we just started gds.node2vec.stream procedure.

CALL gds.listProgress()
YIELD
  jobId,
  taskName,
  progress

Table 3. Results
jobId	taskName	progress
"d21bb4ca-e1e9-4a31-a487-42ac8c9c1a0d"	"Node2Vec"	"42%"

User log

Hints and warnings can also be tracked through the GDS library and be accessed via Cypher queries. The GDS library keeps track for each user their 100 most recent tasks that have generated hints or warnings and stores them in memory. When a user calls procedure gds.userLog, their respective list of generated hints and warnings is returned.

Syntax

Getting the hints and warnings for a user:

CALL gds.userLog()
YIELD
  taskName,
  timeStarted,
  message

Table 4. Results
Name	Type	Description
`taskName`	String	The name of the task that generated a warning or hint, i.e. `WCC`.
`timeStarted`	LocalTime	The local wall clock time when the task has been started.
`message`	String	A hint or warning associated with the task.

Examples

Suppose that we have called the gds.wcc.stream procedure and set a relationshipWeightProperty without specifying a threshold value. This generates a warning which can be accessed via the user log as seen below.

CALL gds.userLog()
YIELD
  taskName,
  message

Table 5. Results
taskName	message
"WCC"	"Specifying a `relationshipWeightProperty` has no effect unless `threshold` is also set"