Skip to content

Self-managed server

Last updated

View as Markdown

For PostgreSQL installed directly on a server, outside a container or a managed service, run the collector as a container alongside it and add node_exporter on each database host.

Before you start, create the database login and write collector.toml as described in Choose your setup. A complete file is in Self-managed PostgreSQL.

Running the collector

Section titled “Running the collector”

Run it on a Docker host, with the config file in the current directory. :latest is convenient while you try it out. For anything you intend to keep running, pin a release tag or a digest, so a restart cannot silently change the running version:

Terminal window
# Pin a release tag instead of :latest in production.
docker run --rm \
  -v "$PWD/collector.toml:/etc/dbg-collector/collector.toml:ro" \
  -e DBG_SERVER_SECRET="<secret from the app>" \
  -e DB_PASSWORD="<your database password>" \
  dbgorillapublic.azurecr.io/dbg-collector:latest \
  --config-file /etc/dbg-collector/collector.toml

The collector is an ordinary container, so it also runs under Docker Compose or in Kubernetes. For Kubernetes there is an official Helm chart at oci://dbgorillapublic.azurecr.io/charts/dbg-collector. It takes the same collector.toml and requires Kubernetes 1.25 or newer:

Terminal window
helm install dbg-collector oci://dbgorillapublic.azurecr.io/charts/dbg-collector \
  --namespace dbg-collector --create-namespace \
  --set-file config.inline=./collector.toml \
  --set secrets.serverSecret="<secret from the app>" \
  --set-string secrets.databasePasswords.DB_PASSWORD="<your database password>"

The chart creates only core Kubernetes objects, with no operator or custom resources. Its pod meets the restricted Pod Security Standard, so it installs into a namespace that enforces it.

See Query plans are on in the sample in Collector commands.

node_exporter

Section titled “node_exporter”

node_exporter is an open-source Prometheus exporter that provides host metrics to the collector. The collector discovers exporters automatically on the default port 9100 on your database hosts. Where port 9100 is not exposed, set mode = "disabled" under [component.provider.node_exporter] so the probe does not stall discovery.

The Prometheus project maintains it, and it is free to download from github.com/prometheus/node_exporter. It is packaged in EPEL for RHEL-based distributions, and runs under Docker with:

Terminal window
docker run -d \
  --net="host" \
  --pid="host" \
  -v "/:/host:ro,rslave" \
  quay.io/prometheus/node-exporter:latest \
  --path.rootfs=/host

With metrics flowing, DBGorilla is usable from the dashboard. To bring your team in, see Organization Management.

Self-managed PostgreSQL

Section titled “Self-managed PostgreSQL”

This config is for PostgreSQL you run yourself, on a VM, a bare-metal host or in a container, with the collector running as a Docker container that can reach it.

[dbgorilla]
agent_id  = "<agent id from the app>"
tenant_id = "<tenant id from the app>"
secret    = "${DBG_SERVER_SECRET}"


[[component]]
name   = "orders"
engine = "postgres"


[component.provider]
type = "self_hosted"


[component.auth]
method   = "password"
user     = "dbg_readonly"
password = "${ORDERS_DB_PASSWORD}"


[component.connect]
host      = "db.internal.example.com"
port      = 5432
databases = ["orders"]
ssl_mode  = "verify-full"


[topology]
interval = "60s"


[commands]
enabled = true
allowed = ["explain", "collect_statistics"]   # see https://www.dbgorilla.com/docs/reference/collector-commands/#database-commands

Run it with the secrets in a separate file, mode 0600 and out of version control:

secrets.env
DBG_SERVER_SECRET=your-client-secret
ORDERS_DB_PASSWORD=your-database-password
Terminal window
docker run --rm \
  -v "$PWD/collector.toml:/etc/dbg-collector/collector.toml:ro" \
  --env-file secrets.env \
  dbgorillapublic.azurecr.io/dbg-collector:latest \
  --config-file /etc/dbg-collector/collector.toml

Pin a release tag in place of latest for anything you keep running. For host metrics, run node_exporter on the database host; see node_exporter.

For PostgreSQL on your own laptop, the CLI writes this file: dbgorilla collector install --target docker. See Your machine (Docker).

Self-managed MySQL

Section titled “Self-managed MySQL”

This config is for MySQL 8.0 or later that you run yourself, with the collector in a Docker container.

[dbgorilla]
agent_id  = "<agent id from the app>"
tenant_id = "<tenant id from the app>"
secret    = "${DBG_SERVER_SECRET}"


[[component]]
name   = "staging-mysql"
engine = "mysql"


[component.provider]
type = "self_hosted"


[component.auth]
method   = "password"
user     = "dbg_monitor"
password = "${MYSQL_PASSWORD}"


[component.connect]
host      = "mysql.internal"
port      = 3306
databases = ["app"]
ssl_mode  = "verify_identity"   # disabled | required | verify_ca | verify_identity (default)


[topology]
interval = "60s"


[commands]
enabled = true
allowed = ["explain", "collect_statistics"]   # see https://www.dbgorilla.com/docs/reference/collector-commands/#database-commands

ssl_mode uses MySQL’s spellings, with underscores. What a PostgreSQL value does is on Collector configuration.

Run it with the same docker run as Self-managed PostgreSQL, with secrets.env holding DBG_SERVER_SECRET and MYSQL_PASSWORD. The performance_schema consumers MySQL needs turned on are listed on MySQL.