master
json 687 lines 25.8 KB
Raw
1 {
2 "jsonSchema": {
3 "$schema": "http://json-schema.org/draft-07/schema#",
4 "title": "SQL collector configuration.",
5 "type": "object",
6 "properties": {
7 "update_every": {
8 "title": "Update every",
9 "description": "How often to collect metrics from the database, in seconds.",
10 "type": "integer",
11 "minimum": 1,
12 "default": 1
13 },
14 "autodetection_retry": {
15 "title": "Detection retry",
16 "description": "How often Netdata retries failed automatic detection jobs, in seconds. Set to 0 to disable retries.",
17 "type": "integer",
18 "minimum": 0,
19 "default": 0
20 },
21 "driver": {
22 "title": "Driver",
23 "description": "SQL driver / database engine to use. Supported values: `mysql` (MySQL/MariaDB), `pgx` (PostgreSQL), `oracle` (OracleDB), `sqlserver` (Microsoft SQL Server), `azuresql` (Microsoft SQL Server with Azure AD).",
24 "type": "string",
25 "enum": [
26 "azuresql",
27 "mysql",
28 "pgx",
29 "oracle",
30 "sqlserver"
31 ],
32 "default": "mysql"
33 },
34 "dsn": {
35 "title": "DSN",
36 "description": "Database connection string (DSN). The format depends on the selected driver.",
37 "type": "string"
38 },
39 "timeout": {
40 "title": "Timeout",
41 "description": "Maximum time allowed for a single query and connection check, in seconds.",
42 "type": "number",
43 "minimum": 0,
44 "default": 5
45 },
46 "cloud_auth": {
47 "title": "Cloud auth",
48 "description": "Optional cloud authentication settings. `azure_ad` is supported when driver is `pgx`, `sqlserver`, or `azuresql`.",
49 "type": "object",
50 "properties": {
51 "provider": {
52 "title": "Provider",
53 "description": "Cloud auth provider. Use `none` to disable cloud authentication.",
54 "type": "string",
55 "enum": [
56 "none",
57 "azure_ad"
58 ],
59 "default": "none"
60 }
61 },
62 "dependencies": {
63 "provider": {
64 "oneOf": [
65 {
66 "properties": {
67 "provider": {
68 "const": "none"
69 }
70 }
71 },
72 {
73 "properties": {
74 "provider": {
75 "const": "azure_ad"
76 },
77 "azure_ad": {
78 "title": "Azure AD",
79 "description": "Microsoft Entra (Azure AD) settings used when provider is `azure_ad`.",
80 "type": "object",
81 "properties": {
82 "mode": {
83 "title": "Mode",
84 "description": "Azure AD credential mode.",
85 "type": "string",
86 "enum": [
87 "service_principal",
88 "managed_identity",
89 "default"
90 ],
91 "default": "default"
92 }
93 },
94 "dependencies": {
95 "mode": {
96 "oneOf": [
97 {
98 "properties": {
99 "mode": {
100 "const": "service_principal"
101 },
102 "mode_service_principal": {
103 "title": "Service Principal",
104 "description": "Service principal settings used when mode is `service_principal`.",
105 "type": "object",
106 "properties": {
107 "tenant_id": {
108 "title": "Tenant ID",
109 "description": "Azure tenant ID.",
110 "type": "string"
111 },
112 "client_id": {
113 "title": "Client ID",
114 "description": "Service principal client ID.",
115 "type": "string"
116 },
117 "client_secret": {
118 "title": "Client Secret",
119 "description": "Service principal client secret.",
120 "type": "string",
121 "sensitive": true
122 }
123 },
124 "required": [
125 "tenant_id",
126 "client_id",
127 "client_secret"
128 ]
129 }
130 },
131 "required": [
132 "mode_service_principal"
133 ]
134 },
135 {
136 "properties": {
137 "mode": {
138 "const": "managed_identity"
139 },
140 "mode_managed_identity": {
141 "title": "Managed Identity",
142 "description": "Managed identity settings used when mode is `managed_identity`.",
143 "type": "object",
144 "properties": {
145 "client_id": {
146 "title": "Client ID",
147 "description": "Optional client ID of a user-assigned managed identity.",
148 "type": "string"
149 }
150 }
151 }
152 }
153 },
154 {
155 "properties": {
156 "mode": {
157 "const": "default"
158 }
159 }
160 }
161 ]
162 }
163 },
164 "required": [
165 "mode"
166 ]
167 }
168 },
169 "required": [
170 "azure_ad"
171 ]
172 }
173 ]
174 }
175 }
176 },
177 "static_labels": {
178 "title": "Static labels",
179 "description": "Key/value labels automatically added to every chart created by this job (for example `env=prod`, `region=eu-west`).",
180 "type": "object",
181 "additionalProperties": {
182 "type": "string"
183 }
184 },
185 "queries": {
186 "title": "Reusable queries",
187 "description": "Optional list of reusable SQL queries that metric blocks can reference via `query_ref` to avoid repeating SQL text.",
188 "type": "array",
189 "items": {
190 "title": "Query",
191 "type": "object",
192 "properties": {
193 "id": {
194 "title": "ID",
195 "description": "Unique query identifier referenced from metric blocks using `query_ref` within this job.",
196 "type": "string"
197 },
198 "query": {
199 "title": "Query",
200 "description": "SQL statement text executed when this query is referenced.",
201 "type": "string"
202 }
203 },
204 "required": [
205 "id",
206 "query"
207 ]
208 }
209 },
210 "metrics": {
211 "title": "Metric blocks",
212 "description": "List of metric blocks. Each block runs one query and maps its result set into one or more Netdata charts.",
213 "type": "array",
214 "items": {
215 "title": "Metric block",
216 "type": "object",
217 "properties": {
218 "id": {
219 "title": "ID",
220 "description": "Metric block identifier. Must be unique within this job.",
221 "type": "string"
222 },
223 "query_ref": {
224 "title": "Query ref",
225 "description": "Reference to a reusable query defined in `queries`. Exactly one of `query_ref` or `query` must be set.",
226 "type": "string"
227 },
228 "query": {
229 "title": "Inline query",
230 "description": "Inline SQL statement for this metric block. Exactly one of `query_ref` or `query` must be set.",
231 "type": "string"
232 },
233 "mode": {
234 "title": "Mode",
235 "description": "How to interpret the result rows. `columns` treats selected columns as metrics. `kv` treats one column as metric name (key) and another as its value.",
236 "type": "string",
237 "enum": [
238 "columns",
239 "kv"
240 ],
241 "default": "columns"
242 },
243 "labels_from_row": {
244 "title": "Labels from row",
245 "description": "Optional labels derived from result columns. Each unique combination of label values produces a separate chart instance.",
246 "type": "array",
247 "items": {
248 "title": "Label from row",
249 "type": "object",
250 "properties": {
251 "source": {
252 "title": "Source column",
253 "description": "Name of the result column whose value will be used as the label value.",
254 "type": "string"
255 },
256 "name": {
257 "title": "Label key",
258 "description": "Label key/name added to the chart (for example `db`, `schema`, `table`).",
259 "type": "string"
260 }
261 },
262 "required": [
263 "source",
264 "name"
265 ]
266 }
267 },
268 "charts": {
269 "title": "Charts",
270 "description": "One or more Netdata charts generated from this metric block.",
271 "type": "array",
272 "items": {
273 "title": "Chart",
274 "type": "object",
275 "properties": {
276 "title": {
277 "title": "Title",
278 "description": "Human-friendly chart title shown in Netdata dashboards.",
279 "type": "string"
280 },
281 "context": {
282 "title": "Context",
283 "description": "Base metric context name for the chart. The collector will prefix it as `sql.<driver>_<context>` to form the full Netdata context. Contexts define the metric namespace, control alert templates, and group charts across jobs and nodes.",
284 "type": "string"
285 },
286 "family": {
287 "title": "Family",
288 "description": "Chart family used to organize charts in the Netdata UI. You can use '/' to create hierarchical grouping levels (e.g. `Database/Connections/Active`). Each level becomes a nested section in the dashboard.",
289 "type": "string"
290 },
291 "type": {
292 "title": "Type",
293 "description": "Visual type of the chart.",
294 "type": "string",
295 "enum": [
296 "line",
297 "stacked",
298 "area"
299 ],
300 "default": "line"
301 },
302 "units": {
303 "title": "Units",
304 "description": "Unit label for all dimensions in this chart (for example `queries/s`, `bytes`, `connections`).",
305 "type": "string"
306 },
307 "algorithm": {
308 "title": "Algorithm",
309 "description": "How Netdata interprets values: `absolute` for values that are already final, `incremental` for monotonically increasing counters.",
310 "type": "string",
311 "enum": [
312 "absolute",
313 "incremental"
314 ],
315 "default": "absolute"
316 },
317 "dims": {
318 "title": "Dimensions",
319 "description": "Definitions of the metrics (dimensions) that belong to this chart.",
320 "type": "array",
321 "items": {
322 "title": "Dimension",
323 "type": "object",
324 "properties": {
325 "name": {
326 "title": "Name",
327 "description": "Dimension identifier, unique within this chart. Also used as the legend name.",
328 "type": "string"
329 },
330 "source": {
331 "title": "Source",
332 "description": "In `columns` mode: the numeric result column to read. In `kv` mode: the key name that must match a value in `kv_mode.name_col`.",
333 "type": "string"
334 },
335 "status_when": {
336 "title": "Status when",
337 "description": "Optional condition that turns this dimension into a boolean 0/1 status metric. The dimension is 1 if any row matches the condition, otherwise 0.",
338 "type": "object",
339 "properties": {
340 "equals": {
341 "title": "Equals",
342 "description": "Use 1 when the value is exactly equal to this literal, otherwise 0. Only one of `equals`, `in`, or `match` may be set.",
343 "type": "string"
344 },
345 "in": {
346 "title": "In",
347 "description": "Use 1 when the value is equal to any element in this list, otherwise 0. Only one of `equals`, `in`, or `match` may be set.",
348 "type": "array",
349 "items": {
350 "type": "string"
351 }
352 },
353 "match": {
354 "title": "Match (regex)",
355 "description": "Use 1 when the value matches this regular expression, otherwise 0. Only one of `equals`, `in`, or `match` may be set.",
356 "type": "string"
357 }
358 }
359 }
360 },
361 "required": [
362 "name",
363 "source"
364 ]
365 }
366 }
367 },
368 "required": [
369 "title",
370 "context",
371 "family",
372 "units",
373 "dims"
374 ]
375 }
376 }
377 },
378 "required": [
379 "id",
380 "mode",
381 "charts"
382 ],
383 "dependencies": {
384 "mode": {
385 "oneOf": [
386 {
387 "properties": {
388 "mode": {
389 "const": "columns"
390 }
391 }
392 },
393 {
394 "properties": {
395 "mode": {
396 "const": "kv"
397 },
398 "kv_mode": {
399 "title": "KV mode",
400 "description": "Configuration for `kv` mode that tells the collector which columns hold the key and value.",
401 "type": "object",
402 "properties": {
403 "name_col": {
404 "title": "Name column",
405 "description": "Name of the result column that contains metric keys (for example `state`).",
406 "type": "string"
407 },
408 "value_col": {
409 "title": "Value column",
410 "description": "Name of the result column that contains numeric metric values for each key.",
411 "type": "string"
412 }
413 }
414 }
415 },
416 "required": [
417 "kv_mode"
418 ]
419 }
420 ]
421 }
422 }
423 }
424 },
425 "function_only": {
426 "title": "Function Only",
427 "description": "Set to true if this job only provides functions (no metrics). When enabled, metrics configuration is ignored and no charts are created.",
428 "type": "boolean",
429 "default": false
430 },
431 "functions": {
432 "title": "Functions",
433 "description": "SQL functions that expose query results as table views in the Netdata UI.",
434 "type": "array",
435 "items": {
436 "title": "Function",
437 "type": "object",
438 "properties": {
439 "id": {
440 "title": "ID",
441 "description": "Unique identifier for this function.",
442 "type": "string"
443 },
444 "name": {
445 "title": "Name",
446 "description": "Display name shown in the UI. Auto-derived from ID if empty.",
447 "type": "string"
448 },
449 "description": {
450 "title": "Description",
451 "description": "Help text shown in the UI.",
452 "type": "string"
453 },
454 "query": {
455 "title": "Query",
456 "description": "SQL query to execute when this function is called.",
457 "type": "string"
458 },
459 "timeout": {
460 "title": "Timeout",
461 "description": "Query timeout in seconds. Uses collector default if not set.",
462 "type": "number",
463 "minimum": 0
464 },
465 "limit": {
466 "title": "Row Limit",
467 "description": "Maximum rows to return.",
468 "type": "integer",
469 "minimum": 1,
470 "maximum": 10000,
471 "default": 100
472 },
473 "default_sort": {
474 "title": "Default Sort Column",
475 "description": "Column name for initial sort order.",
476 "type": "string"
477 },
478 "default_sort_desc": {
479 "title": "Sort Descending",
480 "description": "Sort in descending order by default.",
481 "type": "boolean",
482 "default": true
483 },
484 "columns": {
485 "title": "Column Overrides",
486 "description": "Override auto-detected column metadata.",
487 "type": "object",
488 "additionalProperties": {
489 "type": "object",
490 "properties": {
491 "type": {
492 "title": "Type",
493 "description": "Column data type.",
494 "type": "string",
495 "enum": ["string", "integer", "float", "boolean", "duration", "timestamp"]
496 },
497 "units": {
498 "title": "Units",
499 "description": "Unit label for the column (e.g., milliseconds, bytes).",
500 "type": "string"
501 },
502 "tooltip": {
503 "title": "Tooltip",
504 "description": "Hover text shown in the UI.",
505 "type": "string"
506 },
507 "visible": {
508 "title": "Visible",
509 "description": "Show column by default.",
510 "type": "boolean",
511 "default": true
512 },
513 "sortable": {
514 "title": "Sortable",
515 "description": "Allow sorting by this column.",
516 "type": "boolean",
517 "default": true
518 }
519 }
520 }
521 }
522 },
523 "required": ["id", "query"]
524 }
525 },
526 "vnode": {
527 "title": "Vnode",
528 "description": "Name of the Virtual Node this job should send its metrics to. Leave empty to use the local node.",
529 "type": "string"
530 }
531 },
532 "required": [
533 "driver",
534 "dsn"
535 ]
536 },
537 "uiSchema": {
538 "uiOptions": {
539 "fullPage": true
540 },
541 "ui:flavour": "tabs",
542 "ui:options": {
543 "tabs": [
544 {
545 "title": "Base",
546 "fields": [
547 "update_every",
548 "autodetection_retry",
549 "driver",
550 "dsn",
551 "timeout",
552 "vnode"
553 ]
554 },
555 {
556 "title": "Cloud Auth",
557 "fields": [
558 "cloud_auth"
559 ]
560 },
561 {
562 "title": "Metrics",
563 "fields": [
564 "metrics"
565 ]
566 },
567 {
568 "title": "Reusable Queries",
569 "fields": [
570 "queries"
571 ]
572 },
573 {
574 "title": "Static Labels",
575 "fields": [
576 "static_labels"
577 ]
578 },
579 {
580 "title": "Functions",
581 "fields": [
582 "function_only",
583 "functions"
584 ]
585 }
586 ]
587 },
588 "vnode": {
589 "ui:placeholder": "To use this option, first create a Virtual Node and then reference its name here."
590 },
591 "autodetection_retry": {
592 "ui:help": "This option determines how frequently (in seconds) Netdata will retry data collection jobs that failed initially; setting it to 0 disables this retry mechanism entirely."
593 },
594 "driver": {
595 "ui:widget": "radio",
596 "ui:options": {
597 "inline": true
598 }
599 },
600 "cloud_auth": {
601 "provider": {
602 "ui:widget": "radio",
603 "ui:options": {
604 "inline": true
605 }
606 },
607 "azure_ad": {
608 "mode": {
609 "ui:widget": "radio",
610 "ui:options": {
611 "inline": true
612 },
613 "ui:help": "Choose how Netdata gets Azure credentials.\n\n- `service_principal`: Use an Azure app / service principal. Requires `tenant_id`, `client_id`, and `client_secret` in `mode_service_principal`.\n- `managed_identity`: Use the managed identity attached to the Azure resource running Netdata. Set `mode_managed_identity.client_id` only for a user-assigned identity.\n- `default`: Use the Azure SDK `DefaultAzureCredential` chain. This automatically tries available Azure credential sources, such as environment-based credentials, managed identity, and local developer credentials.\n\nUse `service_principal` for explicit app credentials. Use `managed_identity` when Netdata runs on an Azure resource with an attached identity. Use `default` when you want Azure SDK auto-discovery or local development convenience."
614 },
615 "mode_service_principal": {
616 "client_secret": {
617 "ui:widget": "password"
618 }
619 }
620 }
621 },
622 "dsn": {
623 "ui:placeholder": "Enter the database connection string",
624 "ui:help": "**DSN format depends on the selected driver.**\n\n### MySQL / MariaDB\nFormat: `user:password@tcp(host:port)/dbname?param1=value1&paramN=valueN`\nExample:\n```\nroot:pass@tcp(127.0.0.1:3306)/\n```\n[MySQL DSN documentation](https://github.com/go-sql-driver/mysql#dsn-data-source-name)\n\n### PostgreSQL\nFormats: `postgresql://user:password@host:5432/dbname?param1=value1&paramN=valueN`\nExample:\n```\npostgresql://user:pass@localhost:5432/mydb\n```\n[PostgreSQL DSN documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS)\n\n### Oracle\nFormat: `oracle://username:password@host:port/service?param1=value1&paramN=valueN`\nExample:\n```\noracle://scott:tiger@db.example.com:1521/ORCLPDB1?ssl=off\n```\n\n### SQL Server / Azure SQL\nFormat: `sqlserver://username:password@host:port?database=dbname&param=value`\nExample:\n```\nsqlserver://sa:myStrong(!)Password@localhost:1433?database=master&connection+timeout=30\n```\n[SQL Server driver DSN documentation](https://github.com/microsoft/go-mssqldb#connection-parameters-and-dsn)\n\nWhen `cloud_auth.provider` is `azure_ad` with SQL Server drivers, keep DSN host/database settings and configure authentication in `cloud_auth.azure_ad`."
625 },
626 "static_labels": {
627 "ui:help": "Optional key/value labels added to every chart created by this job (for example env=prod, role=primary)."
628 },
629 "queries": {
630 "items": {
631 "query": {
632 "ui:widget": "textarea"
633 }
634 }
635 },
636 "metrics": {
637 "items": {
638 "ui:order": [
639 "id",
640 "query_ref",
641 "query",
642 "mode",
643 "kv_mode",
644 "labels_from_row",
645 "charts"
646 ],
647 "mode": {
648 "ui:widget": "radio",
649 "ui:options": {
650 "inline": true
651 }
652 },
653 "query": {
654 "ui:widget": "textarea"
655 },
656 "charts": {
657 "items": {
658 "type": {
659 "ui:widget": "radio",
660 "ui:options": {
661 "inline": true
662 }
663 }
664 }
665 }
666 }
667 },
668 "functions": {
669 "items": {
670 "ui:order": [
671 "id",
672 "name",
673 "description",
674 "query",
675 "timeout",
676 "limit",
677 "default_sort",
678 "default_sort_desc",
679 "columns"
680 ],
681 "query": {
682 "ui:widget": "textarea"
683 }
684 }
685 }
686 }
687 }