Connection modes reference#
The connection mode determines how the metadata tracking will work when you initialize a run or other object.
Available connection modes:
||Neptune stores the logged data locally and periodically synchronizes it with the server in the background.|
||No data is stored or sent anywhere.|
||Data is not sent to Neptune but stored locally.|
||No data can be logged, only fetched.|
||Neptune immediately synchronizes the data each time a tracking call (such as
Setting the connection mode#
You can set the mode in the following ways:
The environment variable is used if the
mode parameter is omitted from the
This can be a handy way to debug or "switch off" Neptune without modifying your code.
By default, metadata tracking works asynchronously: The tracked data is temporarily stored on the local disk and periodically synchronized by a separate thread in the background. All tracking calls (like
upload()) are non-blocking.
To be able to restore tracked data in case you experience connectivity issues or your machine restarts (for example, if you use spot instances), you should use Neptune with persistent disks.
Neptune triggers disk flushing:
- Every 5 seconds (default). You can set a different interval with the
- When you call
wait()on a Neptune object.
- When the connection to the object stops (the object context is destroyed).
In asynchronous mode, metadata tracking calls do not throw exceptions related to connectivity or metadata consistency issues. Such issues are printed to stderr.
In asynchronous mode, if there is a problem with the connection to Neptune servers (for example, due to internet connectivity issues), the Neptune client library will track your metadata locally and continuously try to re-establish a connection with the Neptune servers.
Once your run is finished, if the connection has not been re-established, Neptune will continue trying for another 5 minutes. After this period, the process will end. All the unsuccessful tracking calls are stored on the local disk.
You can upload the unsynchronized metadata later via the Neptune Command Line Interface, using the
neptune sync command.
Debug mode essentially turns off all the Neptune-related logging. It can come in handy when you're debugging your code and don't want to pollute your Neptune project.
In contrast to offline mode, debug mode doesn't save any data locally.
In this mode, no connection to Neptune servers is established. Instead, all the tracked metadata is stored on the local disk, in the
.neptune folder of the current working directory.
Good to know
Read only mode is useful when you only want to fetch metadata rather than record it. For example, when you're connecting to Neptune to perform specific analysis on your run metadata.
In read only mode:
- No write operation is possible. Any write-like operation will be ignored.
- No metadata is sent to Neptune. In particular, stdout and stderr are not captured, and no hardware consumption is logged.
Only pre-existing objects can be initialized in read only mode.
In synchronous mode, Neptune executes a tracking call only after all other calls have reached the Neptune servers.
In this mode, tracking methods throw exceptions in case of issues related to connectivity or the consistency of an object's local representation. Neptune will retry each request for 60 seconds before throwing the exception.
If there's an issue with your code but you're not sure where, synchronous mode can help you locate the problematic part.
Note that this mode may slow down your logging.
For an example of ensuring synchronous tracking across multiple processes, see How to use
sync() to ensure synchronous logging.