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.
Add a DBMS instance
Prerequisites
To be monitored by NOM an instance of a DBMS must:
-
be running a Neo4j Enterprise Edition v4.4.0 or higher
-
have the following config settings set in neo4j.conf:
-
metrics.prometheus.endpoint=127.0.0.1:2004
-
metrics.prometheus.enabled=true
-
metrics.enabled=true
-
metrics.filter=*
-
metrics.jmx.enabled=true
-
metrics.namespaces.enabled=true
-
Register agent
Before adding a DBMS instance for NOM monitoring, one agent needs to be registered with the NOM server which provides server communication configuration for the agent.
-
Click the top right settings icon that redirects you to the global settings.
-
Click Agents, where you will see a list of all registered agents along with their last contact times and versions.
-
Click Register New Agent button, and enter the name and description for your new agent followed by clicking Register button.
-
The agent will be created and randomly generated agent credentials will be displayed on the screen.
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.
-
After you have captured the credentials, click the confirmation checkbox and Finish button. Newly created agent will be displayed on the list of agents.
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 toPATH
-
-
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 |
---|---|---|
|
Server GRPC Address |
server:9090 |
|
Server Token URL |
https://server:8080/api/login/agent |
|
Client ID for the agent |
` 3ff98478-d6d2-4e1b-b816-e758c835f076` |
|
Client secret for the agent |
secret |
|
PEM encoded trusted CA list () |
|
|
Log level (debug,info,warn,error) |
info |
|
Path to the log file |
|
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 |
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 |
---|---|---|
|
Name of nth instance |
my-instance-n |
|
Bolt URI for nth instance |
bolt://localhost:7687 |
|
Bolt user name for nth instance |
neo4j |
|
Bolt password for nth instance |
password |
To enable the log streaming functionality, there are also a few optional environment variables.
If CONFIG_INSTANCE_n_QUERY_LOG_PORT
is not set, the feature is treated as disabled.
Variable | Description | Example |
---|---|---|
|
Port for connecting the agent to the Neo4j log4j appender |
9500 |
|
Path to the instance log4j config. If set, appends the appropriate log appender automatically (including the port specified above). |
/var/lib/neo4j/conf/server-logs.xml |
|
Minimum duration in milliseconds for a query to be logged (optional) |
100 |
|
Enable filter for errors under the minimum duration in milliseconds (optional) |
true |
|
Disable the string literal obfuscation in queries (optional) |
true |
Environment variable considerations:
|
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.
-
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
-
-
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
namedEnvironment
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
-
Check agent and DBMS
Ensure agent has contacted NOM server, is online and is reporting DBMS correctly.
-
Return to Agents listing in global settings
-
Identify the newly created agent.
-
Check that there is a value for Last contact time.
-
If the agent has never contacted NOM server then go back to where the agent is running and check the logs. It may be that the server address is configured incorrectly or the TLS certificates are not correctly specified.
-
-
Verify that the agent has a current status of
Online
.-
If the agent is not currently online then go to where it is running and check the logs.
-
-
Hover over the newly added agent and click the cog icon to show agent configuration. Check configuration is as expected.
-
Navigate to the home page and wait for DBMS to appear, this can take a few minutes.
-
Select the Alerts tab and make sure that there are no alerts for the new DBMS.
Was this page helpful?