4f4835e4a · cryptotaxi247/netdata-1

@@ -26,9 +26,12 @@ Metrics and charts for this collector are **entirely defined by your SQL

26 configuration**. There is no fixed metric reference: each job can expose

27 different metrics depending on its `metrics` and `queries` blocks.

28

29 -To see what a specific job collects, open that job’s dashboard in Netdata

29 +To see what a specific job collects, open that job's dashboard in Netdata

30 and inspect the charts and dimensions it created.

31

32 +Jobs can also define **functions** that provide interactive table views in

33 +Netdata's Top tab. A job can have metrics only, functions only, or both.

34 +

35 :::tip

36

37 To change what is collected, edit the `metrics` (and optional `queries`)

@@ -50,6 +53,10 @@ For each metric block you define, it executes the SQL query (inline or via

53 `query_ref`), reads the result set, and maps it to Netdata charts and

54 dimensions.

55

56 +Additionally, you can define **functions** that expose SQL query results as

57 +interactive table views in Netdata's Top tab. Functions support filtering,

58 +sorting, and searching without creating persistent metrics.

59 +

60 ### Result Processing Modes

61

62 | Mode | How it works | Best used when |

@@ -239,6 +246,29 @@ metrics:

246 equals: <string|number|bool> # Active (1) if value == this literal.

247 # in: [ <v1>, <v2>, ... ] # Active if value is in the list.

248 # match: '^regex$' # Active if value matches this regex.

249 +

250 +# ---------- FUNCTIONS ----------

251 +# Set function_only: true if this job only provides functions (no metrics).

252 +function_only: <true|false> # OPTIONAL. Default: false.

253 +

254 +# Expose SQL queries as interactive table views in Netdata's Top tab.

255 +functions:

256 + - id: <function_id> # REQUIRED. Unique identifier.

257 + name: <display_name> # OPTIONAL. Derived from id if not set.

258 + description: <help_text> # OPTIONAL. Shown in the UI.

259 + query: | # REQUIRED. SQL to execute.

260 + SELECT ...

261 + timeout: <seconds> # OPTIONAL. Query timeout.

262 + limit: <max_rows> # OPTIONAL. Default: 100.

263 + default_sort: <column_name> # OPTIONAL. Initial sort column.

264 + default_sort_desc: <true|false> # OPTIONAL. Default: true.

265 + columns: # OPTIONAL. Override column metadata.

266 + <column_name>:

268 + units: <unit_string>

269 + tooltip: <hover_text>

270 + visible: <true|false>

271 + sortable: <true|false>

272 ```

273

274

@@ -255,7 +285,18 @@ metrics:

285 | **Connection** | timeout | Query and connection check timeout (seconds). | 5 | no |

286 | **Labels** | static_labels | A map of static labels added to every chart created by this job. Useful for tagging charts with environment, region, or role. | {} | no |

287 | **Queries & Metrics** | queries | A list of reusable queries. Metric blocks can reference these via `query_ref` to avoid repeating SQL. See [Configuration Structure](#configuration) for details. | [] | no |

258 -| | metrics | 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. | [] | yes |

288 +| | metrics | 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. | [] | no |

289 +| **Functions** | functions | A list of SQL functions exposed as interactive table views in Netdata's Top tab. Each function runs a SQL query and displays results in a filterable, sortable table. See [Functions](#functions) for details. | [] | no |

290 +| | functions[].id | Unique identifier for this function. | | yes |

291 +| | functions[].name | Display name shown in the UI. Auto-derived from ID if not set. | | no |

292 +| | functions[].description | Help text shown in the UI. | | no |

293 +| | functions[].query | SQL query to execute when this function is called. | | yes |

294 +| | functions[].timeout | Query timeout (seconds). Uses collector timeout if not set. | | no |

295 +| | functions[].limit | Maximum rows to return. | 100 | no |

296 +| | functions[].default_sort | Column name for initial sort order. | | no |

297 +| | functions[].default_sort_desc | Sort in descending order by default. | yes | no |

298 +| | functions[].columns | Override auto-detected column metadata. Map of column name to settings (type, units, tooltip, visible, sortable). | {} | no |

299 +| | function_only | Set to true if this job only provides functions (no metrics). When enabled, metrics configuration is not required and no charts are created. | no | no |

301

302

@@ -563,6 +604,120 @@ jobs:

604 ```

605 </details>

606

607 +###### Function-only mode – slow query analysis

608 +

609 +PostgreSQL example that provides an interactive slow query analysis view

610 +without collecting any time-series metrics.

611 +

612 +This is useful for ad-hoc troubleshooting via the Netdata **Top** tab.

613 +The function queries `pg_stat_statements` to show the slowest queries

614 +sorted by total execution time.

615 +

616 +

617 +<details open><summary>Config</summary>

618 +

619 +```yaml

620 +jobs:

621 + - name: pg_slow_queries

622 + driver: pgx

623 + dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres'

624 + timeout: 10

625 + function_only: true

626 +

627 + functions:

628 + - id: slow-queries

629 + name: Slow Queries

630 + description: Top queries by total execution time from pg_stat_statements

631 + query: |

632 + SELECT

633 + queryid,

634 + LEFT(query, 100) AS query,

635 + calls,

636 + total_exec_time,

637 + mean_exec_time,

638 + rows

639 + FROM pg_stat_statements

640 + ORDER BY total_exec_time DESC

641 + limit: 100

642 + default_sort: total_exec_time

643 + default_sort_desc: true

644 + columns:

645 + total_exec_time:

646 + type: duration

647 + units: milliseconds

648 + tooltip: Total time spent executing this query

649 + mean_exec_time:

650 + type: duration

651 + units: milliseconds

652 + tooltip: Average execution time per call

653 +

654 +```

655 +</details>

656 +

657 +###### Combined metrics and functions

658 +

659 +PostgreSQL example that collects time-series metrics AND provides

660 +interactive function views in the same job.

661 +

662 +- The `metrics` block creates charts for connection states.

663 +- The `functions` block provides an interactive activity view.

664 +

665 +

666 +<details open><summary>Config</summary>

667 +

668 +```yaml

669 +jobs:

670 + - name: pg_combined

671 + driver: pgx

672 + dsn: 'postgresql://netdata:password@127.0.0.1:5432/postgres'

673 + timeout: 5

674 +

675 + # Time-series metrics

676 + metrics:

677 + - id: connections

678 + mode: kv

679 + query: |

680 + SELECT state, count(*) AS cnt

681 + FROM pg_stat_activity

682 + GROUP BY state

683 + kv_mode:

684 + name_col: state

685 + value_col: cnt

686 + charts:

687 + - title: "Connection states"

688 + context: sql.pg_connections

689 + family: connections

690 + units: connections

691 + type: stacked

692 + dims:

693 + - name: active

694 + source: active

695 + - name: idle

696 + source: idle

697 +

698 + # Interactive functions

699 + functions:

700 + - id: active-sessions

701 + name: Active Sessions

702 + description: Currently running queries

703 + query: |

704 + SELECT

705 + pid,

706 + usename,

707 + datname,

708 + state,

709 + query_start,

710 + LEFT(query, 200) AS query

711 + FROM pg_stat_activity

712 + WHERE state = 'active'

713 + limit: 50

714 + columns:

715 + query_start:

716 + type: timestamp

717 +

718 +```

719 +</details>

720 +

721

722

723 ## Troubleshooting

Regenerate integrations docs (#21670)