Ubuntu

1. Navigate to the agent config directory:

   cd /opt/watchlog-agent
   sudo vim integration.json
   
2. Locate the Elasticsearch object:

{ "service": "elasticsearch", "monitor": false, "protocol": "http", "host": "127.0.0.1", "port": "9200", "username": "", "password": "", "apiKey": "", "verifyCertificate": true }

3. Change `"monitor"` from `false` to `true`:
```diff
-  "monitor": false
+  "monitor": true

4. Populate the connection fields:

   • protocol — http or https. Elasticsearch 8 defaults to https, but a self-managed cluster is often left on http.
   • host, port — one reachable node is enough. The agent discovers the rest of the cluster from it.
   • username / password or apiKey. If both are set, the API key is used.

   You only need one endpoint even for a multi-node cluster:

   {
     "service": "elasticsearch",
     "monitor": true,
     "protocol": "https",
     "host": "es-node-1.internal",
     "port": "9200",
     "username": "watchlog_monitor",
     "password": "your_password"
   }
   

5. Save the file and reload the agent:

   sudo pm2 reload watchlog-agent
   

Verify the connection

The agent exposes a local, read-only connection test on its own API port. It validates the configuration already stored on this host and never returns your password:

curl -s -X POST http://127.0.0.1:3774/integrations/elasticsearch/test | jq

A working configuration answers:

{
  "ok": true,
  "kind": "ok",
  "clusterName": "production",
  "version": "8.17.3",
  "status": "green",
  "nodes": 3,
  "message": "Connected to production (Elasticsearch 8.17.3), 3 node(s), status green."
}

Anything else names the specific problem — connection_refused, authentication_failed, permission_denied, tls_error, timeout or unsupported_endpoint.

Minimum privileges

Create a dedicated user rather than reusing elastic:

curl -u elastic -X POST "https://localhost:9200/_security/role/watchlog_monitor" -H 'Content-Type: application/json' -d '{
  "cluster": ["monitor"],
  "indices": [{ "names": ["*"], "privileges": ["monitor"] }]
}'

curl -u elastic -X POST "https://localhost:9200/_security/user/watchlog_monitor" -H 'Content-Type: application/json' -d '{
  "password": "your_password",
  "roles": ["watchlog_monitor"]
}'

The built-in monitoring_user role grants the same thing if you would rather not define one.

TLS with a private CA

Point the agent at your CA rather than disabling verification:

{
  "service": "elasticsearch",
  "monitor": true,
  "protocol": "https",
  "host": "es.internal",
  "port": "9200",
  "username": "watchlog_monitor",
  "password": "your_password",
  "tls": {
    "ca": "/etc/elasticsearch/certs/http_ca.crt"
  }
}

The path is read on the agent's host. You can also paste the PEM text inline. If the CA cannot be read, the agent falls back to the system trust store and reports that as a capability note on the dashboard rather than failing silently.

Slow operations (optional)

Elasticsearch writes slow searches and slow indexing operations to log files on each node's host. Watchlog never enables slow logging for you — set a threshold yourself on the indices you want traced:

curl -u watchlog_monitor -X PUT "https://localhost:9200/my-index/_settings" -H 'Content-Type: application/json' -d '{
  "index.search.slowlog.threshold.query.warn": "10s",
  "index.indexing.slowlog.threshold.index.warn": "10s"
}'

Then enable collection in integration.json:

"slowlog": {
  "enabled": true,
  "minDurationMs": 0,
  "storeSource": false
}

The agent auto-discovers the log files in /var/log/elasticsearch and /usr/share/elasticsearch/logs. If yours are elsewhere, set the paths explicitly:

"slowlog": {
  "enabled": true,
  "searchLogPath": "/data/logs/production_index_search_slowlog.json",
  "indexingLogPath": "/data/logs/production_index_indexing_slowlog.json"
}

Make sure the agent user can read them:

sudo usermod -aG elasticsearch watchlog