Skip to content

Latest commit

 

History

History
318 lines (170 loc) · 15.7 KB

README.md

File metadata and controls

318 lines (170 loc) · 15.7 KB

Performance Monitor Darling — Headless Edition

Darling is the headless, centralized edition of Performance Monitor: a 24/7 service (a Windows service, or Linux with systemd or Docker Compose) that collects from your SQL Servers into a central PostgreSQL (optionally TimescaleDB) store, plus a detached desktop viewer that reads that store. No desktop app has to stay open for collection to happen, and every viewer seat reads the same central data.

Running an install day to day? Running Darling day to day has the steps to add or remove a server, change a password, rotate a token, pause collection, upgrade and uninstall.

It runs the same monitoring brain as the Lite edition — one shared codebase, two storage engines:

  • PerformanceMonitor.Collectors owns every collector definition (more than 40 for SQL Server and more than 25 for PostgreSQL): the exact query sent to monitored servers, the result-row mappings, the delta rules, the default cadences and retention horizons, and the ignored-wait-types list. Lite writes those rows to DuckDB; Darling writes the same rows to PostgreSQL via binary COPY. Each definition declares which engine it targets, and a collector never runs against the other one — see PostgreSQL targets.
  • PerformanceMonitor.Alerting owns the shared alert engine — the same thresholds, edge-trigger gates, cooldowns, and dedup fingerprints Lite uses.
  • The analysis/recommendations pipeline (the same inference engine behind both apps' Recommendations tabs and the analyze_server MCP tool) runs on a schedule inside the service.

A collector, alert, or analysis change lands once in the shared libraries and both editions get it. A Darling install monitoring a server even derives the same server_id Lite would for that server, because the identity rule (host[:database][:RO], hashed) is shared too.


When to Choose Darling vs. Lite

Lite Darling
Collection runs While the desktop app is open (or in the tray) 24/7 as a Windows service, or on Linux with systemd or Docker Compose
Data lives Locally per seat (DuckDB + Parquet) Centrally (PostgreSQL / TimescaleDB)
Execution plans Not stored (fetched live when you view a query) Captured and stored, TOAST-compressed (capturePlans, default on)
Viewers The app is the viewer Any number of viewer seats read the central store
Setup Download and run On Windows, extract the release zip and run install-darling.ps1 (on Linux, see Run on Linux). The shipped default is the bundled store (managed mode), so you provision no database. To use your own PostgreSQL, provision it and set its connection string.
Best for Quick triage, consultants, a handful of servers Always-on team monitoring, larger estates, one shared store
Configuration Settings UI darling.json seeds the first start. After that, the Viewer edits servers, alert settings and notification routes in the store. The web dashboard's Admin page edits a server in place and the agent channel of a notification route, for a sign-in that can make changes. Its Alert Settings tab is read-only.

Nothing is installed on the monitored SQL Servers by either edition beyond three lightweight Extended Events ring-buffer sessions and, when it is unset, a one-time blocked process threshold bootstrap (see What the Service Does on Monitored Servers).


Quick Start

Installing on Windows? Follow docs/darling/install.md. It is the ordered path from a downloaded zip to a working install, with a proof point at every step.

Installing on Linux, or turning on the web dashboard? Read docs/darling-quick-start.md.

The install reference that was here moved to these pages:

The headings below keep the old links working.

Prerequisites

This section moved to Install Darling.

Configure darling.json

This section moved to Install Darling.

Validate the Config (Pre-flight)

This section moved to Install Darling.

Check Host/Store Sizing Settings

This section moved to Install Darling.

Diagnostics Bundle

This section moved to The command line reference.

Run on Linux (Docker Compose or systemd)

This section moved to the Darling quick start.

Install as a Windows Service

This section moved to Install Darling.

Upgrading an existing install

This section moved to Running Darling day to day.

Rolling back to an older build

This section moved to Running Darling day to day.

Upgrading from a build that predates the script

This section moved to Running Darling day to day.

The install location has to be machine-scoped

This section moved to Install Darling.

Run the service as a domain account or gMSA

This section moved to Install Darling.

Build from source

This section moved to Install Darling.

Windows stops at start: the CET error

This section moved to Install Darling.

What the Service Does on Monitored Servers

This section moved to Darling and your monitored servers.

The Extended Events Sessions the Service Creates

This section moved to Darling and your monitored servers.

Permissions on Monitored Servers

This section moved to Darling and your monitored servers.


Configuration Reference

This section covered every block of darling.json and the collector settings. It moved to these pages:

The headings below keep the old links working.

Where each setting lives: first-run seed or file only

This section moved to Configuration Reference.

postgres

This section moved to Configuration Reference.

servers (array)

This section moved to Configuration Reference.

Testing an index on PostgreSQL

This section moved to Configuration Reference.

allowedAwsRoles (array, optional)

This section moved to Configuration Reference.

alerts

This section moved to Alert and notification settings.

Which engine each built-in alert and health band covers

This section moved to Alert and notification settings.

Notification routes — sending alert families to different channels

This section moved to Alert and notification settings.

Export the judged cases to test your own agent (#6236)

This section moved to Agents and alert sources.

mcp

This section moved to MCP configuration.

web

This section moved to Web dashboard configuration.

peers

This section moved to Configuration Reference.

Enable or disable a collector headlessly (--enable-collector / --disable-collector)

This section moved to Collector schedules and switches.

Make a new password key (--reset-password-key)

This section moved to Collector schedules and switches.

Set the time of day a daily collector runs (--set-collector-run-at)

This section moved to Collector schedules and switches.

Drop the Extended Events sessions a removed server left behind (--drop-xe-sessions)

This section moved to Collector schedules and switches.

Make a login for a system that sends alerts (--add-alert-source and friends)

This section moved to Agents and alert sources.

Alert sources on another machine

This section moved to Agents and alert sources.


PostgreSQL Targets

This section covered PostgreSQL servers as monitored targets. It moved to PostgreSQL Targets.

Permissions on a PostgreSQL target

This section moved to PostgreSQL Targets.

Oldest PostgreSQL version per collector

This section moved to PostgreSQL Targets.


Operations

This section moved to Operations. It covered the store, TimescaleDB, the background workers, retention, the logs, the Viewer, restarts and how to watch the service from outside.

The Store

This section moved to Operations.

Background workers: sizing an unmanaged store, and what happens if you don't

This section moved to Operations.

Retention

This section moved to Operations.

Logs

This section moved to Operations.

Watching the service from outside

This section moved to Operations.


Agent Changes: List, Undo and the Switch

This section moved to Security and agent changes.

Connect a Remote Viewer

This section covered a viewer seat on another machine. It moved to The WPF viewer.

1. Export the handoff folder (on the service host)

This section moved to The WPF viewer.

Manual configuration (fallback)

This section moved to The WPF viewer.


Troubleshooting

This section moved to Darling troubleshooting.


How It Runs (Reference)

This section listed the fixed cadences of the service. It moved to Running Darling day to day.


Managed Bundled PostgreSQL

This section covered the store that the service runs for itself in managed mode. It moved to Managed Bundled PostgreSQL.

Security & Least-Privilege Roles

This section moved to Security and agent changes.

Opt-in Network Endpoints (LAN)

This section moved to Opt-in Network Endpoints (LAN).

Guided setup (--configure-network)

This section moved to Opt-in Network Endpoints (LAN).

Firewall rules (--configure-firewall)

This section moved to Opt-in Network Endpoints (LAN).

Headless enable/disable + firewall (--enable-mcp / --enable-web)

This section moved to Opt-in Network Endpoints (LAN).

Store endpoint (viewer over the LAN)

This section moved to Opt-in Network Endpoints (LAN).

MCP endpoint (assistant over the LAN)

This section moved to Opt-in Network Endpoints (LAN).

Web endpoint (browser over the LAN)

This section moved to Opt-in Network Endpoints (LAN).

Level 2: agents change mute rules and custom alert rules

This section moved to Security and agent changes.

Per-server threshold overrides

This section covered a threshold value for one server or one database. It moved to Alerts & Notifications.