Skip to content

What is black-box monitoring

NebulaGraph comes with a black-box monitoring feature that collects and archives data on the operating system and service metrics on a regular basis. When the NebulaGraph service fails, it helps you quickly locate the problem and analyze the cause without a direct network connection.


The black-box monitoring feature is for the NebulaGraph Enterprise Edition only.


Black-box monitoring operates as a set of background processes on the server and collects metric data regularly. Currently, only operating system performance metrics are collected (e.g., CPU, Memory, Network IO, and other related metrics). In the future, we will support collecting NebulaGraph service-related metrics. For the description of metrics, see PROC.

Enable black-box monitoring

The black-box monitoring feature is turned on by default. The black-box directory is created and stored in the NebulaGraph installation directory the first time NebulaGraph is started. Files of collected black-box monitoring data are stored in that directory.

You can disable the black-box monitoring by setting the related parameters in the Black box configurations section of the configuration files of all NebulaGraph services. For details about service configurations, see Configurations.

Black-box monitoring files

Directory structure

In the black_box directory, the system automatically creates sub-directories. Sub-directories are named with the corresponding process number of each NebulaGraph service running on the current machine. In each sub-directory, by default, a binary file is generated every 5 seconds to record the OS performance metric data during this time. The file name is in the format of black_box.{timestamp_id}.log. timestamp_id is the timestamp when the file is generated.

├── 5776 # The service process number    ├── black_box.1665472900.log # Black-box monitoring file   ├── black_box.1665472905.log
│   ...
├── 5787   ├── black_box.1665728450.log
│   ├── black_box.1665728455.log
│   ...

Each black-box monitoring file has 30 minutes (1800 seconds) of storage by default. Files stored for more than 30 minutes will be automatically deleted.

The generation interval and storage time of black-box monitoring files can be configured in the Black box configuration section of the configuration file of each NebulaGraph service. For configuration file details, see Configurations.

Viewing black-box monitoring files

To view the black-box binaries you need to use the NebulaGraph Black Box tool, which can also be used to convert the binaries to CSV files and export them for viewing. For using the NebulaGraph Black Box tool, see Black Box tool Nebula-BBox.

Last update: May 16, 2023