Adding a managed DBMS

Adding a DBMS in NOM’s terminology means to enable the monitoring of every instance in the DBMS by installing a NOM agent on the instance host and configuring it appropriately.

Register agent

Before adding the DBMS for NOM monitoring, an agent needs to be registered with NOM server which provides server communication configuration for the agent.

  1. Click the top right settings icon that redirects you to the global settings.

  2. Click Agents, where you will see a list of all registered agents along with their last contact times and versions.

    agents

  3. Click Register New Agent button, and enter the name and description for your new agent followed by clicking Register button.

    agent new

  4. The agent will be created and randomly generated agent credentials will be displayed on the screen.

    agent credentials

    The credentials and other key agent configuration values are displayed as environment variable declarations. You can copy them over to your instance host for ease of agent configuration.

  5. After you have captured the credentials, click the confirmation checkbox and Finish button. Newly created agent will be displayed on the list of agents.

Check if the instance of DBMS to be monitored has a supported version. Only Neo4j Enterprise Edition versions from 4.4.0 on are supported.

Install agent

The following steps are required to install an agent:

  • Standalone binaries (only linux and windows platform binaries are available)

    • Download: Download

    • Extract the archive:

      tar -xvzf <agent downloaded archive>

    • Add the bin folder in the extracted directory to PATH

  • To verify the installation, run the following command:

    agent version

    Which should output:

    <agent name> <agent version> <agent revision>

  • Make sure the agent version is equal to that of the NOM server.

Configure agent

An agent’s run configurations are provided through environment variables. The following table lists configuration keys and values to be set for them:

Variable Description Example

CONFIG_SERVER_ADDRESS

Server GRPC Address

server:9090

CONFIG_TOKEN_URL

Server Token URL

https://server:8080/api/login/agent

CONFIG_TOKEN_CLIENT_ID

Client ID for the agent

` 3ff98478-d6d2-4e1b-b816-e758c835f076`

CONFIG_TOKEN_CLIENT_SECRET

Client secret for the agent

secret

CONFIG_TLS_TRUSTED_CERTS

PEM encoded trusted CA list ()

/path/to/a/pem/file

CONFIG_LOG_LEVEL

Log level (debug,info,warn,error)

info

CONFIG_LOG_FILE

Path to the log file

/var/log/nom-agent/log.txt

Since agent-server communication needs to be encrypted, you need to configure the agent so that it trusts the server’s certificates. The file that contains the trusted certificate list (PEM encoded) can be specified through the CONFIG_TLS_TRUSTED_CERTS environment variable. While most operating systems default to the system-wide trusted certificates, that’s not the case on Windows. For that reason, you must set this environment variable on Windows.

Apart from the start configuration above, for each of the monitored DBMS instance(s), the following environment variables needs to be set to allow the agent to access the instance:

Variable Description Example

CONFIG_INSTANCE_n_NAME

Name of nth instance

my-instance-n

CONFIG_INSTANCE_n_BOLT_URI

Bolt URI for nth instance

bolt://localhost:7687

CONFIG_INSTANCE_n_BOLT_USERNAME

Bolt user name for nth instance

neo4j

CONFIG_INSTANCE_n_BOLT_PASSWORD

Bolt password for nth instance

password

Environment variable considerations:

  • n in the above environment variables needs to be replaced with 1, 2, etc. for each of the monitored DBMS instances on the same host. For example, for a single monitored DBMS, the environment variables must be named as CONFIG_INSTANCE_1_NAME, CONFIG_INSTANCE_1_BOLT_URI, CONFIG_INSTANCE_1_BOLT_USERNAME and CONFIG_INSTANCE_1_BOLT_PASSWORD.

  • The instance name that you specify for CONFIG_INSTANCE_n_NAME will be used to identify your instance on NOM. For this reason, it is important that you specify unique names across your cluster.

Agents are supposed to monitor only local instances and should not be configured to connect to remote instances.

Run agent

An agent can run in two modes, console or service. Best practice is to run an agent in service mode.

  1. Run an agent in console mode:

    All configuration values for the agent should be set as environment variables before starting the agent

    • Command:

      agent console

  2. Run an agent in service mode:

    To run an agent in service means that the agent process runs in the background and monitors the instance and this is the recommended way. The agent lifecycle is handled by the operating system service manager.

    • Install the service for linux (systemd):

      • Run

        agent service install

      • Execute

        systemctl edit neo4j-ops-manager-agent.service

        and set environment variables by either setting Environment or EnvironmentFile options. For example, using the Environment options, the override file looks as follows:

        [Service]
Environment="CONFIG_SERVER_ADDRESS=<server grpc address>"
Environment="CONFIG_TOKEN_URL=<server http login url>"
Environment="CONFIG_TOKEN_CLIENT_ID=<client id>"
Environment="CONFIG_TOKEN_CLIENT_SECRET=<client secret>"
Environment="CONFIG_TLS_TRUSTED_CERTS=</path/to/trusted/certs/pem/file>"
Environment="CONFIG_LOG_FILE=</path/to/nom-agent/log.txt>"
Environment="CONFIG_INSTANCE_1_NAME=<instance name>"
Environment="CONFIG_INSTANCE_1_BOLT_URI=<bolt uri of the local instance>"
Environment="CONFIG_INSTANCE_1_BOLT_USERNAME=<local instance user name>"
Environment="CONFIG_INSTANCE_1_BOLT_PASSWORD=<local instance password>"

      • Start your service

        systemctl start neo4j-ops-manager-agent.service

        or

        systemctl stop neo4j-ops-manager-agent.service

      • Logs are available, using journalctl, via

        journalctl -u neo4j-ops-manager-agent

    • Install the service for Windows:

      • Run

        agent service install

      • Open registry editor and navigate to HKLM\SYSTEM\CurrentControlSet\Services\neo4j-ops-manager-agent.

      • Create a key of type REG_MULTI_SZ named Environment and add your environment variables, each on a separate line:

        CONFIG_SERVER_ADDRESS=<server grpc address>
CONFIG_TOKEN_URL=<server http login url>
CONFIG_TOKEN_CLIENT_ID=<client id>
CONFIG_TOKEN_CLIENT_SECRET=<client secret>
CONFIG_TLS_TRUSTED_CERTS=</path/to/the/trusted/certs/pem>
CONFIG_LOG_FILE=</path/to/nom-agent/log.txt>
CONFIG_INSTANCE_1_NAME=<instance name>
CONFIG_INSTANCE_1_BOLT_URI=<bolt uri of the local instance>
CONFIG_INSTANCE_1_BOLT_USERNAME=<local instance user name>
CONFIG_INSTANCE_1_BOLT_PASSWORD=<local instance password>

      • Start your service

        agent service start

    • To uninstall the service

      agent service uninstall

Add a single instance

To add a single instance DBMS to monitor:

  • Register agent.

  • Install agent.

  • Configure the environment variables required by the agent.

  • Run the agent.

Add a cluster

To add a cluster DBMS to monitor, for every instance of the cluster:

  • Register agent.

  • Install agent.

  • Configure the environment variables required by the agent.

  • Run the agent.