| 1 | plugin_name: go.d.plugin |
| 2 | modules: |
| 3 | - meta: |
| 4 | id: collector-go.d.plugin-sql |
| 5 | plugin_name: go.d.plugin |
| 6 | module_name: sql |
| 7 | monitored_instance: |
| 8 | name: SQL databases (generic) |
| 9 | link: https://en.wikipedia.org/wiki/SQL |
| 10 | categories: |
| 11 | - data-collection.databases |
| 12 | icon_filename: sql.svg |
| 13 | related_resources: |
| 14 | integrations: |
| 15 | list: [] |
| 16 | alternative_monitored_instances: [] |
| 17 | info_provided_to_referring_integrations: |
| 18 | description: "" |
| 19 | keywords: |
| 20 | - db |
| 21 | - database |
| 22 | - sql |
| 23 | - mysql |
| 24 | - maria |
| 25 | - postgres |
| 26 | - postgresql |
| 27 | - pgx |
| 28 | - oracle |
| 29 | - sqlserver |
| 30 | - mssql |
| 31 | - generic |
| 32 | overview: |
| 33 | multi_instance: true |
| 34 | data_collection: |
| 35 | metrics_description: | |
| 36 | Metrics and charts for this collector are **entirely defined by your SQL |
| 37 | configuration**. There is no fixed metric reference: each job can expose |
| 38 | different metrics depending on its `metrics` and `queries` blocks. |
| 39 | |
| 40 | To see what a specific job collects, open that job's dashboard in Netdata |
| 41 | and inspect the charts and dimensions it created. |
| 42 | |
| 43 | Jobs can also define **functions** that provide interactive table views in |
| 44 | Netdata's Live tab. A job can have metrics only, functions only, or both. |
| 45 | |
| 46 | :::tip |
| 47 | |
| 48 | To change what is collected, edit the `metrics` (and optional `queries`) |
| 49 | in the job configuration. After you save the changes, the updated set of |
| 50 | charts and metrics is reflected in Netdata after the next data collection. |
| 51 | |
| 52 | ::: |
| 53 | method_description: | |
| 54 | The collector connects to your database using Go’s **database/sql** package |
| 55 | and the selected driver: |
| 56 | |
| 57 | - `mysql` — MySQL / MariaDB |
| 58 | - `pgx` — PostgreSQL |
| 59 | - `oracle` — Oracle Database |
| 60 | - `sqlserver` — Microsoft SQL Server / Azure SQL |
| 61 | |
| 62 | For each metric block you define, it executes the SQL query (inline or via |
| 63 | `query_ref`), reads the result set, and maps it to Netdata charts and |
| 64 | dimensions. |
| 65 | |
| 66 | Additionally, you can define **functions** that expose SQL query results as |
| 67 | interactive table views in Netdata's Live tab. Functions support filtering, |
| 68 | sorting, and searching without creating persistent metrics. |
| 69 | |
| 70 | ### Result Processing Modes |
| 71 | |
| 72 | | Mode | How it works | Best used when | |
| 73 | |------------|------------------------------------------------------------------------------|-----------------------------------------------------| |
| 74 | | **columns**| Specific numeric columns from each row become dimensions on your charts. | The result set has stable, known column names. | |
| 75 | | **kv** | One column provides metric names (keys) and another provides their values. | The set of metrics is dynamic or key–value shaped. | |
| 76 | default_behavior: |
| 77 | auto_detection: |
| 78 | description: | |
| 79 | This is a **generic collector** and does **not** perform automatic detection. |
| 80 | |
| 81 | It does not create any jobs on its own — you must configure at least one |
| 82 | job before it can collect data. |
| 83 | limits: |
| 84 | description: | |
| 85 | There are no built-in limits on the number of queries or rows processed. |
| 86 | However, each metric block must define at least one chart, and each chart |
| 87 | must define at least one dimension. |
| 88 | |
| 89 | Keep your queries lightweight and scoped to the data you actually need |
| 90 | to avoid adding load on the database server. |
| 91 | performance_impact: |
| 92 | description: | |
| 93 | Performance impact depends entirely on the queries you configure and the |
| 94 | collection frequency (update_every). |
| 95 | |
| 96 | Prefer indexed reads, avoid full table scans or heavy aggregations, and |
| 97 | consider using database views tailored for monitoring. |
| 98 | additional_permissions: |
| 99 | description: "" |
| 100 | supported_platforms: |
| 101 | include: [] |
| 102 | exclude: [] |
| 103 | setup: |
| 104 | prerequisites: |
| 105 | list: |
| 106 | - title: Create a read-only database user |
| 107 | description: | |
| 108 | Create a dedicated user for Netdata with read-only privileges on the |
| 109 | views/tables used in your monitoring queries. |
| 110 | |
| 111 | For example, on a typical RDBMS you would: |
| 112 | |
| 113 | - Create a user. |
| 114 | - Grant SELECT on system metrics views or monitoring views. |
| 115 | |
| 116 | After creating the user and updating the configuration, restart the |
| 117 | Netdata Agent with `sudo systemctl restart netdata`, or the appropriate |
| 118 | method for your system. |
| 119 | - title: Allow Netdata to connect to the database |
| 120 | description: | |
| 121 | Ensure the Netdata host can reach the database via the configured DSN, |
| 122 | either using: |
| 123 | |
| 124 | - a local UNIX/TCP socket, or |
| 125 | - a network connection (hostname/IP and port). |
| 126 | |
| 127 | If the database is remote, make sure any firewalls or security groups |
| 128 | allow connections from the Netdata node. |
| 129 | configuration: |
| 130 | file: |
| 131 | name: go.d/sql.conf |
| 132 | options: |
| 133 | description: | |
| 134 | **Full Configuration Structure** |
| 135 | |
| 136 | ```yaml |
| 137 | # ---------- CONNECTION ---------- |
| 138 | driver: <mysql|pgx|oracle|sqlserver|azuresql> # REQUIRED. SQL driver. |
| 139 | dsn: "<connection string>" # REQUIRED. Driver-specific DSN/URL. |
| 140 | |
| 141 | # Optional connection settings |
| 142 | timeout: <seconds> # OPTIONAL. Query timeout. |
| 143 | cloud_auth: # OPTIONAL. Cloud auth for pgx/sqlserver/azuresql. |
| 144 | provider: <none|azure_ad> # OPTIONAL. Default: none. |
| 145 | azure_ad: |
| 146 | mode: <service_principal|managed_identity|default> |
| 147 | mode_service_principal: # REQUIRED for service_principal |
| 148 | tenant_id: "<tenant-id>" |
| 149 | client_id: "<client-id>" |
| 150 | client_secret: "<client-secret>" |
| 151 | mode_managed_identity: # OPTIONAL for managed_identity |
| 152 | client_id: "<client-id>" # Optional for user-assigned MI |
| 153 | |
| 154 | # Optional static labels applied to all charts |
| 155 | static_labels: |
| 156 | <label_key1>: <label_value> |
| 157 | <label_key2>: <label_value> |
| 158 | |
| 159 | # ---------- REUSABLE QUERIES ---------- |
| 160 | # Optional. Define reusable SQL queries referenced later via query_ref. |
| 161 | queries: |
| 162 | - id: <query_id> |
| 163 | query: | |
| 164 | SELECT ... |
| 165 | |
| 166 | # ---------- METRICS ---------- |
| 167 | # Each metric block runs one query and generates one or more charts. |
| 168 | metrics: |
| 169 | - id: <metric_block_id> # REQUIRED. Unique within this job. |
| 170 | |
| 171 | # Choose ONE of these: |
| 172 | query_ref: <query_id> # Use a reusable query |
| 173 | # OR |
| 174 | # query: | # Inline SQL |
| 175 | # SELECT ... |
| 176 | |
| 177 | mode: <columns|kv> # REQUIRED. How to interpret result rows. |
| 178 | |
| 179 | # KV mode settings (only when mode: kv) |
| 180 | kv_mode: |
| 181 | name_col: <column_name> # Column containing keys |
| 182 | value_col: <column_name> # Column containing numeric values |
| 183 | |
| 184 | # Optional: derive labels from row columns (creates per-label charts) |
| 185 | labels_from_row: |
| 186 | - source: <column_name> # Column name from result set |
| 187 | name: <label_key> # Label key exposed to Netdata |
| 188 | - source: <column_name> |
| 189 | name: <label_key> |
| 190 | |
| 191 | # Charts produced by this metric block |
| 192 | charts: |
| 193 | - title: "<Chart Title>" # REQUIRED. Shown in dashboards. |
| 194 | context: "<context.name>" # REQUIRED. Netdata context. |
| 195 | family: "<family>" # REQUIRED. Netdata chart family. |
| 196 | units: "<units>" # REQUIRED. Unit string for the chart. |
| 197 | type: <line|stacked|area> # OPTIONAL. Default: line. |
| 198 | algorithm: <absolute|incremental> # OPTIONAL. Default: absolute. |
| 199 | |
| 200 | dims: |
| 201 | # ---- COLUMNS MODE DIM ---- |
| 202 | # In mode: columns, `source` MUST be a numeric COLUMN name from the result set. |
| 203 | - name: <dim_id> # REQUIRED. Dimension id (unique within this chart). |
| 204 | source: <column_name> # REQUIRED. Numeric column to chart. |
| 205 | |
| 206 | # ---- KV MODE DIM ---- |
| 207 | # In mode: kv, `source` MUST be a KEY name (NOT a column). |
| 208 | # The collector finds the row where (row[kv_mode.name_col] == `source`) |
| 209 | # and uses row[kv_mode.value_col]. |
| 210 | - name: <dim_id> |
| 211 | source: <key_name> # REQUIRED. Key name resolved via kv_mode.name_col. |
| 212 | |
| 213 | # ---- STATUS DIM (one-hot 1/0) ---- |
| 214 | # Works in BOTH modes. Evaluates `status_when` against the resolved value: |
| 215 | # * columns mode: the value in the specified column for the row |
| 216 | # * kv mode: the value for the resolved key (row[kv_mode.value_col]) |
| 217 | - name: <dim_id> |
| 218 | source: <column_name_or_key_name> # Same interpretation as above, per mode. |
| 219 | status_when: # Exactly ONE of the following: |
| 220 | equals: <string|number|bool> # Active (1) if value == this literal. |
| 221 | # in: [ <v1>, <v2>, ... ] # Active if value is in the list. |
| 222 | # match: '^regex$' # Active if value matches this regex. |
| 223 | |
| 224 | # ---------- FUNCTIONS ---------- |
| 225 | # Set function_only: true if this job only provides functions (no metrics). |
| 226 | function_only: <true|false> # OPTIONAL. Default: false. |
| 227 | |
| 228 | # Expose SQL queries as interactive table views in Netdata's Live tab. |
| 229 | functions: |
| 230 | - id: <function_id> # REQUIRED. Unique identifier. |
| 231 | name: <display_name> # OPTIONAL. Derived from id if not set. |
| 232 | description: <help_text> # OPTIONAL. Shown in the UI. |
| 233 | query: | # REQUIRED. SQL to execute. |
| 234 | SELECT ... |
| 235 | timeout: <seconds> # OPTIONAL. Query timeout. |
| 236 | limit: <max_rows> # OPTIONAL. Default: 100. |
| 237 | default_sort: <column_name> # OPTIONAL. Initial sort column. |
| 238 | default_sort_desc: <true|false> # OPTIONAL. Default: true. |
| 239 | columns: # OPTIONAL. Override column metadata. |
| 240 | <column_name>: |
| 241 | type: <string|integer|float|boolean|duration|timestamp> |
| 242 | units: <unit_string> |
| 243 | tooltip: <hover_text> |
| 244 | visible: <true|false> |
| 245 | sortable: <true|false> |
| 246 | ``` |
| 247 | folding: |
| 248 | title: Config options |
| 249 | enabled: true |
| 250 | list: |
| 251 | - name: update_every |
| 252 | description: Data collection interval (seconds). |
| 253 | default_value: 1 |
| 254 | required: false |
| 255 | group: Collection |
| 256 | - name: autodetection_retry |
| 257 | description: Autodetection retry interval (seconds). Not used for this collector. Set 0 to disable. |
| 258 | default_value: 0 |
| 259 | required: false |
| 260 | group: Collection |
| 261 | |
| 262 | - name: driver |
| 263 | description: > |
| 264 | SQL driver to use. Supported values: `mysql`, `pgx`, `oracle`, `sqlserver`, `azuresql`. |
| 265 | default_value: mysql |
| 266 | required: true |
| 267 | group: Target |
| 268 | - name: dsn |
| 269 | description: > |
| 270 | Database connection string (DSN). The format depends on the selected driver ( |
| 271 | [MySQL](https://github.com/go-sql-driver/mysql#dsn-data-source-name), |
| 272 | [PostgreSQL](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS), |
| 273 | [MS SQL Server](https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn)). |
| 274 | default_value: "" |
| 275 | required: true |
| 276 | group: Target |
| 277 | - name: cloud_auth.provider |
| 278 | description: Cloud auth provider (`none` or `azure_ad`). Supported for `pgx`, `sqlserver`, and `azuresql`. |
| 279 | default_value: none |
| 280 | required: false |
| 281 | group: Cloud Auth |
| 282 | - name: cloud_auth.azure_ad.mode |
| 283 | description: Azure AD credential mode (`service_principal`, `managed_identity`, or `default`). Required when `cloud_auth.provider` is `azure_ad`. |
| 284 | default_value: "" |
| 285 | required: true |
| 286 | group: Cloud Auth/Azure |
| 287 | - name: cloud_auth.azure_ad.mode_service_principal.tenant_id |
| 288 | description: Azure tenant ID. Required for `service_principal` mode. |
| 289 | default_value: "" |
| 290 | required: false |
| 291 | group: Cloud Auth/Azure |
| 292 | - name: cloud_auth.azure_ad.mode_service_principal.client_id |
| 293 | description: Azure client ID. Required for `service_principal` mode. |
| 294 | default_value: "" |
| 295 | required: false |
| 296 | group: Cloud Auth/Azure |
| 297 | - name: cloud_auth.azure_ad.mode_service_principal.client_secret |
| 298 | description: Azure client secret for `service_principal` mode. |
| 299 | default_value: "" |
| 300 | required: false |
| 301 | group: Cloud Auth/Azure |
| 302 | - name: cloud_auth.azure_ad.mode_managed_identity.client_id |
| 303 | description: Optional client ID of a user-assigned managed identity (`managed_identity` mode). |
| 304 | default_value: "" |
| 305 | required: false |
| 306 | group: Cloud Auth/Azure |
| 307 | |
| 308 | - name: timeout |
| 309 | description: Query and connection check timeout (seconds). |
| 310 | default_value: 5 |
| 311 | required: false |
| 312 | group: Connection |
| 313 | |
| 314 | - name: static_labels |
| 315 | description: > |
| 316 | A map of static labels added to every chart created by this job. |
| 317 | Useful for tagging charts with environment, region, or role. |
| 318 | default_value: "{}" |
| 319 | required: false |
| 320 | group: Labels |
| 321 | |
| 322 | - name: queries |
| 323 | description: > |
| 324 | A list of reusable queries. Metric blocks can reference these via `query_ref` to avoid repeating SQL. See [Configuration Structure](#configuration) for details. |
| 325 | default_value: "[]" |
| 326 | required: false |
| 327 | group: Queries & Metrics |
| 328 | - name: metrics |
| 329 | description: > |
| 330 | A list of metric blocks. Each block defines how a query is executed and how its result is transformed into one or more charts. See [Configuration Structure](#configuration) for details. |
| 331 | default_value: "[]" |
| 332 | required: false |
| 333 | group: Queries & Metrics |
| 334 | |
| 335 | - name: functions |
| 336 | description: > |
| 337 | A list of SQL functions exposed as interactive table views in Netdata's Live tab. |
| 338 | Each function runs a SQL query and displays results in a filterable, sortable table. |
| 339 | See [Functions](#functions) for details. |
| 340 | default_value: "[]" |
| 341 | required: false |
| 342 | group: Functions |
| 343 | - name: functions[].id |
| 344 | description: Unique identifier for this function. |
| 345 | default_value: "" |
| 346 | required: true |
| 347 | group: Functions |
| 348 | - name: functions[].name |
| 349 | description: Display name shown in the UI. Auto-derived from ID if not set. |
| 350 | default_value: "" |
| 351 | required: false |
| 352 | group: Functions |
| 353 | - name: functions[].description |
| 354 | description: Help text shown in the UI. |
| 355 | default_value: "" |
| 356 | required: false |
| 357 | group: Functions |
| 358 | - name: functions[].query |
| 359 | description: SQL query to execute when this function is called. |
| 360 | default_value: "" |
| 361 | required: true |
| 362 | group: Functions |
| 363 | - name: functions[].timeout |
| 364 | description: Query timeout (seconds). Uses collector timeout if not set. |
| 365 | default_value: "" |
| 366 | required: false |
| 367 | group: Functions |
| 368 | - name: functions[].limit |
| 369 | description: Maximum rows to return. |
| 370 | default_value: 100 |
| 371 | required: false |
| 372 | group: Functions |
| 373 | - name: functions[].default_sort |
| 374 | description: Column name for initial sort order. |
| 375 | default_value: "" |
| 376 | required: false |
| 377 | group: Functions |
| 378 | - name: functions[].default_sort_desc |
| 379 | description: Sort in descending order by default. |
| 380 | default_value: true |
| 381 | required: false |
| 382 | group: Functions |
| 383 | - name: functions[].columns |
| 384 | description: > |
| 385 | Override auto-detected column metadata. Map of column name to settings |
| 386 | (type, units, tooltip, visible, sortable). |
| 387 | default_value: "{}" |
| 388 | required: false |
| 389 | group: Functions |
| 390 | - name: function_only |
| 391 | description: > |
| 392 | Set to true if this job only provides functions (no metrics). |
| 393 | When enabled, metrics configuration is not required and no charts are created. |
| 394 | default_value: false |
| 395 | required: false |
| 396 | group: Functions |
| 397 | |
| 398 | - name: vnode |
| 399 | description: Associates this data collection job with a Virtual Node. |
| 400 | default_value: "" |
| 401 | required: false |
| 402 | group: Virtual Node |
| 403 | examples: |
| 404 | folding: |
| 405 | title: Config |
| 406 | enabled: true |
| 407 | list: |
| 408 | - name: Azure SQL with service principal (azuresql) |
| 409 | description: | |
| 410 | SQL Server query example against Azure SQL using Microsoft Entra service principal authentication. |
| 411 | config: | |
| 412 | jobs: |
| 413 | - name: azure_sql_connections |
| 414 | driver: azuresql |
| 415 | dsn: "sqlserver://my-server.database.windows.net:1433?database=master" |
| 416 | timeout: 5 |
| 417 | cloud_auth: |
| 418 | provider: azure_ad |
| 419 | azure_ad: |
| 420 | mode: service_principal |
| 421 | mode_service_principal: |
| 422 | tenant_id: "00000000-0000-0000-0000-000000000000" |
| 423 | client_id: "11111111-1111-1111-1111-111111111111" |
| 424 | client_secret: "super-secret-value" |
| 425 | metrics: |
| 426 | - id: user_connections |
| 427 | mode: columns |
| 428 | query: | |
| 429 | SELECT COUNT(*) AS connections |
| 430 | FROM sys.dm_exec_sessions |
| 431 | WHERE is_user_process = 1; |
| 432 | charts: |
| 433 | - title: "Azure SQL user connections" |
| 434 | context: sql.azure_sql_user_connections |
| 435 | family: connections |
| 436 | units: sessions |
| 437 | dims: |
| 438 | - name: users |
| 439 | source: connections |
| 440 | |
| 441 | - name: Azure PostgreSQL with default credential (pgx) |
| 442 | description: | |
| 443 | PostgreSQL query example against Azure Database for PostgreSQL using the default Azure credential chain. |
| 444 | config: | |
| 445 | jobs: |
| 446 | - name: azure_pg_uptime |
| 447 | driver: pgx |
| 448 | dsn: 'postgresql://netdata@myserver.postgres.database.azure.com:5432/postgres?sslmode=require' |
| 449 | timeout: 5 |
| 450 | cloud_auth: |
| 451 | provider: azure_ad |
| 452 | azure_ad: |
| 453 | mode: default |
| 454 | metrics: |
| 455 | - id: uptime |
| 456 | mode: columns |
| 457 | query: | |
| 458 | SELECT EXTRACT(EPOCH FROM (now() - pg_postmaster_start_time())) AS uptime_seconds; |
| 459 | charts: |
| 460 | - title: "Azure PostgreSQL uptime" |
| 461 | context: sql.azure_pg_uptime |
| 462 | family: uptime |
| 463 | units: seconds |
| 464 | dims: |
| 465 | - name: uptime |
| 466 | source: uptime_seconds |
| 467 | |
| 468 | - name: Columns mode – per-database conflicts (with labels) |
| 469 | description: | |
| 470 | PostgreSQL example that collects database-level conflict counters from |
| 471 | `pg_stat_database_conflicts` and creates a separate chart instance per |
| 472 | database using `labels_from_row`. |
| 473 | |
| 474 | The query: |
| 475 | |
| 476 | ```sql |
| 477 | SELECT |
| 478 | datname, |
| 479 | confl_tablespace, |
| 480 | confl_lock, |
| 481 | confl_snapshot, |
| 482 | confl_bufferpin, |
| 483 | confl_deadlock |
| 484 | FROM pg_stat_database_conflicts; |
| 485 | ``` |
| 486 | |
| 487 | Example output: |
| 488 | |
| 489 | | datname | confl_tablespace | confl_lock | confl_snapshot | confl_bufferpin | confl_deadlock | |
| 490 | |------------|------------------|------------|----------------|-----------------|----------------| |
| 491 | | postgres | 0 | 0 | 0 | 0 | 0 | |
| 492 | | production | 0 | 0 | 0 | 0 | 0 | |
| 493 | |
| 494 | This configuration turns each row into a **chart instance** (one for |
| 495 | `db=postgres`, one for `db=production`) with five dimensions |
| 496 | (`confl_tablespace`, `confl_lock`, `confl_snapshot`, `confl_bufferpin`, |
| 497 | `confl_deadlock`). |
| 498 | config: | |
| 499 | jobs: |
| 500 | - name: pg_conflicts_per_db |
| 501 | driver: pgx |
| 502 | dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres' |
| 503 | timeout: 5 |
| 504 | |
| 505 | metrics: |
| 506 | - id: conflicts |
| 507 | mode: columns |
| 508 | query: | |
| 509 | SELECT |
| 510 | datname, |
| 511 | confl_tablespace, |
| 512 | confl_lock, |
| 513 | confl_snapshot, |
| 514 | confl_bufferpin, |
| 515 | confl_deadlock |
| 516 | FROM pg_stat_database_conflicts; |
| 517 | labels_from_row: |
| 518 | - source: datname |
| 519 | name: db |
| 520 | charts: |
| 521 | - title: "PostgreSQL conflicts" |
| 522 | context: sql.pg_conflicts |
| 523 | family: conflicts |
| 524 | units: conflicts |
| 525 | type: line |
| 526 | algorithm: absolute |
| 527 | dims: |
| 528 | - name: confl_tablespace |
| 529 | source: confl_tablespace |
| 530 | - name: confl_lock |
| 531 | source: confl_lock |
| 532 | - name: confl_snapshot |
| 533 | source: confl_snapshot |
| 534 | - name: confl_bufferpin |
| 535 | source: confl_bufferpin |
| 536 | - name: confl_deadlock |
| 537 | source: confl_deadlock |
| 538 | |
| 539 | - name: Columns mode – single numeric value (uptime) |
| 540 | description: | |
| 541 | PostgreSQL example that exposes a single numeric metric (server uptime in |
| 542 | seconds) as a one-dimension chart using columns mode. |
| 543 | |
| 544 | The query: |
| 545 | |
| 546 | ```sql |
| 547 | SELECT |
| 548 | EXTRACT( |
| 549 | EPOCH FROM (now() - pg_postmaster_start_time()) |
| 550 | ) AS uptime_seconds; |
| 551 | ``` |
| 552 | |
| 553 | Example output: |
| 554 | |
| 555 | | uptime_seconds | |
| 556 | |----------------| |
| 557 | | 50.867359 | |
| 558 | |
| 559 | This configuration maps the `uptime_seconds` column to a single |
| 560 | `uptime` dimension on the `sql.pg_uptime` chart. |
| 561 | config: | |
| 562 | jobs: |
| 563 | - name: pg_uptime |
| 564 | driver: pgx |
| 565 | dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres' |
| 566 | timeout: 5 |
| 567 | |
| 568 | metrics: |
| 569 | - id: uptime |
| 570 | mode: columns |
| 571 | query: | |
| 572 | SELECT |
| 573 | EXTRACT( |
| 574 | EPOCH FROM (now() - pg_postmaster_start_time()) |
| 575 | ) AS uptime_seconds; |
| 576 | charts: |
| 577 | - title: "PostgreSQL uptime" |
| 578 | context: sql.pg_uptime |
| 579 | family: uptime |
| 580 | units: seconds |
| 581 | type: line |
| 582 | algorithm: absolute |
| 583 | dims: |
| 584 | - name: uptime |
| 585 | source: uptime_seconds |
| 586 | |
| 587 | - name: KV mode – connection states as key/value pairs |
| 588 | description: | |
| 589 | PostgreSQL example that aggregates connection states from |
| 590 | `pg_stat_activity` and uses kv mode to map each state to a dimension. |
| 591 | |
| 592 | The query: |
| 593 | |
| 594 | ```sql |
| 595 | SELECT |
| 596 | state, |
| 597 | count(*) AS cnt |
| 598 | FROM pg_stat_activity |
| 599 | GROUP BY state; |
| 600 | ``` |
| 601 | |
| 602 | Example output: |
| 603 | |
| 604 | | state | cnt | |
| 605 | |------------------------------|-----| |
| 606 | | active | 1 | |
| 607 | | idle | 14 | |
| 608 | | idle in transaction | 7 | |
| 609 | | idle in transaction (aborted)| 1 | |
| 610 | | fastpath function call | 1 | |
| 611 | | disabled | 1 | |
| 612 | |
| 613 | With `mode: kv`, `state` becomes the **key** and `cnt` the **value**. |
| 614 | Each distinct `state` value is mapped to a chart dimension via `dims[*].source`. |
| 615 | config: | |
| 616 | jobs: |
| 617 | - name: pg_activity_states |
| 618 | driver: pgx |
| 619 | dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres' |
| 620 | timeout: 5 |
| 621 | |
| 622 | metrics: |
| 623 | - id: activity_states |
| 624 | mode: kv |
| 625 | query: | |
| 626 | SELECT |
| 627 | state, |
| 628 | count(*) AS cnt |
| 629 | FROM pg_stat_activity |
| 630 | GROUP BY state; |
| 631 | kv_mode: |
| 632 | name_col: state |
| 633 | value_col: cnt |
| 634 | charts: |
| 635 | - title: "PostgreSQL connection states" |
| 636 | context: sql.pg_activity_states |
| 637 | family: connections |
| 638 | units: connections |
| 639 | type: stacked |
| 640 | algorithm: absolute |
| 641 | dims: |
| 642 | - name: active |
| 643 | source: active |
| 644 | - name: idle |
| 645 | source: idle |
| 646 | - name: idle_in_transaction |
| 647 | source: "idle in transaction" |
| 648 | - name: idle_in_transaction_aborted |
| 649 | source: "idle in transaction (aborted)" |
| 650 | - name: fastpath_function_call |
| 651 | source: "fastpath function call" |
| 652 | - name: disabled |
| 653 | source: disabled |
| 654 | |
| 655 | - name: Columns mode – map state values to a status metric |
| 656 | description: | |
| 657 | Simple PostgreSQL example that turns a boolean-like state into a 0/1 |
| 658 | status metric using `status_when`. |
| 659 | |
| 660 | The query: |
| 661 | |
| 662 | ```sql |
| 663 | SELECT pg_is_in_recovery(); |
| 664 | ``` |
| 665 | |
| 666 | Example output: |
| 667 | |
| 668 | | pg_is_in_recovery | |
| 669 | |-------------------| |
| 670 | | f | |
| 671 | |
| 672 | This configuration creates a single chart with two status dimensions: |
| 673 | - `in_recovery` becomes **1 when the value is `"t"`** and **0 otherwise**. |
| 674 | - `not_in_recovery` becomes **1 when the value is `"f"`** and **0 otherwise**. |
| 675 | config: | |
| 676 | jobs: |
| 677 | - name: pg_recovery_status |
| 678 | driver: pgx |
| 679 | dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres' |
| 680 | timeout: 5 |
| 681 | |
| 682 | metrics: |
| 683 | - id: recovery_status |
| 684 | mode: columns |
| 685 | query: | |
| 686 | SELECT pg_is_in_recovery(); |
| 687 | charts: |
| 688 | - title: "PostgreSQL recovery status" |
| 689 | context: sql.pg_recovery_status |
| 690 | family: state |
| 691 | units: status |
| 692 | type: line |
| 693 | algorithm: absolute |
| 694 | dims: |
| 695 | - name: in_recovery |
| 696 | source: pg_is_in_recovery |
| 697 | status_when: |
| 698 | equals: "t" |
| 699 | - name: not_in_recovery |
| 700 | source: pg_is_in_recovery |
| 701 | status_when: |
| 702 | equals: "f" |
| 703 | |
| 704 | - name: Function-only mode – slow query analysis |
| 705 | description: | |
| 706 | PostgreSQL example that provides an interactive slow query analysis view |
| 707 | without collecting any time-series metrics. |
| 708 | |
| 709 | This is useful for ad-hoc troubleshooting via the Netdata **Live** tab. |
| 710 | The function queries `pg_stat_statements` to show the slowest queries |
| 711 | sorted by total execution time. |
| 712 | config: | |
| 713 | jobs: |
| 714 | - name: pg_slow_queries |
| 715 | driver: pgx |
| 716 | dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres' |
| 717 | timeout: 10 |
| 718 | function_only: true |
| 719 | |
| 720 | functions: |
| 721 | - id: slow-queries |
| 722 | name: Slow Queries |
| 723 | description: Top queries by total execution time from pg_stat_statements |
| 724 | query: | |
| 725 | SELECT |
| 726 | queryid, |
| 727 | LEFT(query, 100) AS query, |
| 728 | calls, |
| 729 | total_exec_time, |
| 730 | mean_exec_time, |
| 731 | rows |
| 732 | FROM pg_stat_statements |
| 733 | ORDER BY total_exec_time DESC |
| 734 | limit: 100 |
| 735 | default_sort: total_exec_time |
| 736 | default_sort_desc: true |
| 737 | columns: |
| 738 | total_exec_time: |
| 739 | type: duration |
| 740 | units: milliseconds |
| 741 | tooltip: Total time spent executing this query |
| 742 | mean_exec_time: |
| 743 | type: duration |
| 744 | units: milliseconds |
| 745 | tooltip: Average execution time per call |
| 746 | |
| 747 | - name: Combined metrics and functions |
| 748 | description: | |
| 749 | PostgreSQL example that collects time-series metrics AND provides |
| 750 | interactive function views in the same job. |
| 751 | |
| 752 | - The `metrics` block creates charts for connection states. |
| 753 | - The `functions` block provides an interactive activity view. |
| 754 | config: | |
| 755 | jobs: |
| 756 | - name: pg_combined |
| 757 | driver: pgx |
| 758 | dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres' |
| 759 | timeout: 5 |
| 760 | |
| 761 | # Time-series metrics |
| 762 | metrics: |
| 763 | - id: connections |
| 764 | mode: kv |
| 765 | query: | |
| 766 | SELECT state, count(*) AS cnt |
| 767 | FROM pg_stat_activity |
| 768 | GROUP BY state |
| 769 | kv_mode: |
| 770 | name_col: state |
| 771 | value_col: cnt |
| 772 | charts: |
| 773 | - title: "Connection states" |
| 774 | context: sql.pg_connections |
| 775 | family: connections |
| 776 | units: connections |
| 777 | type: stacked |
| 778 | dims: |
| 779 | - name: active |
| 780 | source: active |
| 781 | - name: idle |
| 782 | source: idle |
| 783 | |
| 784 | # Interactive functions |
| 785 | functions: |
| 786 | - id: active-sessions |
| 787 | name: Active Sessions |
| 788 | description: Currently running queries |
| 789 | query: | |
| 790 | SELECT |
| 791 | pid, |
| 792 | usename, |
| 793 | datname, |
| 794 | state, |
| 795 | query_start, |
| 796 | LEFT(query, 200) AS query |
| 797 | FROM pg_stat_activity |
| 798 | WHERE state = 'active' |
| 799 | limit: 50 |
| 800 | columns: |
| 801 | query_start: |
| 802 | type: timestamp |
| 803 | troubleshooting: |
| 804 | problems: |
| 805 | list: [] |
| 806 | alerts: [] |
| 807 | functions: |
| 808 | description: | |
| 809 | This collector supports user-defined SQL functions that expose query results as |
| 810 | interactive table views in Netdata's **Live** tab. Functions are configured per job |
| 811 | in the `functions` section of the job configuration. Since functions are entirely |
| 812 | user-defined, no predefined functions are listed here. |
| 813 | |
| 814 | In the Live tab, functions appear in a hierarchical menu: |
| 815 | |
| 816 | ``` |
| 817 | Databases |
| 818 | └── SQL |
| 819 | └── <job_name> |
| 820 | ├── <function_name_1> |
| 821 | └── <function_name_2> |
| 822 | ``` |
| 823 | |
| 824 | Each job creates its own group containing all functions defined for that job. |
| 825 | list: [] |
| 826 | metrics: |
| 827 | folding: |
| 828 | title: Metrics |
| 829 | enabled: false |
| 830 | description: | |
| 831 | Metrics and charts are **defined by your SQL queries and metric blocks** at runtime. They differ by database engine, schema, and configuration, and may include, for example, connection counts, cache hit ratios, row throughput, lock statistics, or custom business KPIs. Use the **Metrics** tab on the job’s dashboard to see exactly what is collected for that job. |
| 832 | |
| 833 | :::tip |
| 834 | |
| 835 | To change what is collected, edit the `metrics` (and optionally `queries`) sections in `go.d/sql.conf` for the corresponding job. Each change is reflected in Netdata charts after the next data collection. |
| 836 | |
| 837 | ::: |
| 838 | |
| 839 | availability: [] |
| 840 | scopes: [] |