master
yaml 735 lines 28.5 KB
Raw
1 # Generated metadata.yaml for as400 module
2 plugin_name: ibm.d.plugin
3 modules:
4 - meta:
5 plugin_name: ibm.d.plugin
6 module_name: as400
7 monitored_instance:
8 name: IBM i (AS/400)
9 link: https://www.ibm.com/products/power-systems
10 categories:
11 - data-collection.operating-systems
12 icon_filename: "ibm-i.png"
13 related_resources:
14 integrations:
15 list: []
16 info_provided_to_referring_integrations:
17 description: ""
18 keywords:
19 - as400
20 overview:
21 data_collection:
22 metrics_description: |
23 Monitors IBM i (AS/400) systems using SQL services and CL commands to
24 expose CPU, memory, storage, job, and subsystem activity.
25
26 **Dependencies:**
27 - unixODBC 2.3+ with IBM i Access ODBC driver
28 - IBM i 7.2 or later with SQL services enabled
29
30 **Required Libraries:**
31 - libodbc.so (provided by unixODBC)
32 - IBM i Access Client Solutions
33
34 **Collection paths**
35
36 The collector executes queries in multiple tracks:
37
38 - **Fast path (5s)**: lightweight system status queries remain sequential on the main plugin thread.
39 - **Slow path (10s beat)**: heavier queries (per-queue metrics, subsystems, plan cache, etc.) run in a background worker with bounded concurrency.
40 - **Batch path (≥60s beat)**: optional long-period worker used for expensive aggregate queries such as queue totals. Disabled by default unless queue totals are explicitly enabled.
41
42 **CPU Collection Methods:**
43
44 The collector uses a hybrid approach for CPU utilization metrics to handle IBM i 7.4+ where
45 `AVERAGE_CPU_*` columns were deprecated:
46
47 1. **Primary Method - TOTAL_CPU_TIME**: Uses the monotonic `TOTAL_CPU_TIME` counter from
48 `QSYS2.SYSTEM_STATUS()` to calculate CPU utilization via delta-based calculation. This is
49 the most accurate method but requires `*JOBCTL` special authority. TOTAL_CPU_TIME is a
50 cumulative counter in nanoseconds representing CPU-seconds consumed, naturally in per-core
51 scale.
52
53 2. **Fallback Method - ELAPSED_CPU_USED**: If `*JOBCTL` authority is not available, falls back
54 to `ELAPSED_CPU_USED` with automatic reset detection. This method tracks when IBM i statistics
55 are reset (either manually or via `reset_statistics` configuration) and re-establishes a
56 baseline after detecting resets. The values are already in per-core scale.
57
58 3. **Legacy Method - AVERAGE_CPU_UTILIZATION**: For IBM i versions before 7.4, uses the now-
59 deprecated `AVERAGE_CPU_UTILIZATION` column, which IBM reports in the same per-core scale.
60
61 The collector automatically selects the appropriate method based on available permissions and
62 logs which method is being used.
63
64 **CPU Metric Scale:**
65
66 CPU utilization is reported using the "100% = 1 CPU core" semantic. This means:
67 - 100% indicates one CPU core is fully utilized
68 - 400% indicates four CPU cores are fully utilized
69 - Values are limited to 100% × ConfiguredCPUs, matching the partition's configured capacity
70
71 For shared LPARs, the metrics show absolute CPU consumption in per-core scale, not relative to
72 entitled capacity. For example, a shared LPAR entitled to 0.20 cores can show 150% utilization
73 when bursting above entitlement.
74
75 **Statistics Reset Behavior:**
76
77 The `reset_statistics` configuration option controls whether the collector resets IBM i system
78 statistics on each query via `SYSTEM_STATUS(RESET_STATISTICS=>'YES')`. When enabled:
79
80 - System-level statistics (CPU, memory pools, etc.) are reset after each collection cycle
81 - Matches legacy behavior but clears global statistics that other tools may rely on
82 - The ELAPSED_CPU_USED fallback method will detect and handle these resets automatically
83 - **Caution**: Enabling this affects all users and applications on the IBM i system
84
85 Default: `false` (statistics are not reset, using `RESET_STATISTICS=>'NO'`)
86
87 **Chart Gaps During Baseline Resets:**
88
89 The `as400.system_activity_cpu_rate` and `as400.system_activity_cpu_utilization` charts rely on
90 delta calculations. When the collector detects that IBM i reset these statistics—or when it is
91 still establishing the initial baseline—it intentionally skips a sample instead of emitting a zero
92 or spike. Netdata renders those skipped samples as small gaps, which is expected behaviour.
93
94 **Cardinality Management:**
95
96 To prevent performance issues from excessive metric creation, the collector enforces cardinality
97 limits on per-instance metrics (disks, subsystems, job queues, message queues, output queues,
98 active jobs, network interfaces, HTTP servers).
99
100 **How Limits Work:**
101 - The collector counts instances before collecting metrics
102 - If count exceeds the configured `max_*` limit, **collection is skipped entirely** for that category
103 - The collector logs a warning: `"[category] count (X) exceeds limit (Y), skipping collection"`
104 - No metrics are collected for that category until you adjust the configuration
105
106 **Configuration Options:**
107
108 Use **both** limit and selector options together to manage high-cardinality environments:
109
110 | Option | Purpose | Default |
111 |--------|---------|---------|
112 | `max_disks` | Maximum disk units to monitor | 100 |
113 | `max_subsystems` | Maximum subsystems to monitor | 100 |
114 | `max_job_queues` | Maximum job queues to monitor | 100 |
115 | `max_message_queues` | Maximum message queues to monitor | 100 |
116 | `max_output_queues` | Maximum output queues to monitor | 100 |
117 | `active_jobs` | Fully qualified active jobs to monitor (`JOB_NUMBER/USER/JOB_NAME`) | `[]` |
118 | `collect_disks_matching` | Glob pattern to filter disks (e.g., `"001* 002*"`) | `""` (match all) |
119 | `collect_subsystems_matching` | Glob pattern to filter subsystems (e.g., `"QINTER QBATCH"`) | `""` (match all) |
120 | `collect_job_queues_matching` | Glob pattern to filter job queues (e.g., `"QSYS/*"`) | `""` (match all) |
121
122 Optional batch-path controls:
123
124 | Option | Purpose | Default |
125 |--------|---------|---------|
126 | `batch_path` | Enables the long-period batch worker for aggregate queries | `false` |
127 | `batch_path_update_every` | Batch worker cadence (minimum 60s, recommend ≥600s in production) | `60s` |
128 | `batch_path_max_connections` | Maximum concurrent connections for batch queries | `1` |
129 | `collect_message_queue_totals` | Enables full-scan counting of all message queues and messages | `auto` (off) |
130 | `collect_job_queue_totals` | Enables aggregate counting of job queues and queued jobs | `auto` (off) |
131 | `collect_output_queue_totals` | Enables aggregate counting of output queues and spooled files | `auto` (off) |
132
133 > **Warning:** queue totals require scanning IBM i catalog views and can be very expensive on large systems. Leave these options disabled unless aggregate counts are absolutely necessary.
134
135
136 **Example Workflow:**
137
138 1. System has 500 disks, collector skips disk metrics (exceeds default limit of 100)
139 2. Check logs: `"disk count (500) exceeds limit (100), skipping per-disk metrics"`
140 3. Two options:
141 - **Option A**: Increase limit: `max_disks: 500` (collects all 500 disks)
142 - **Option B**: Use selector: `collect_disks_matching: "00[1-5]*"` (cherry-pick specific disks)
143
144 **Best Practices:**
145 - Use selectors to monitor only business-critical objects in large environments
146 - Set limits based on your Netdata server's capacity (each instance = multiple charts)
147 - Start with defaults and adjust based on actual usage patterns
148
149 **IBM i 7.2–7.3 Behavior Note (Message Queues):**
150
151 IBM i 7.4 introduced a message-queue table function that returns only the live backlog. On
152 7.2–7.3 systems we fall back to the `QSYS2.MESSAGE_QUEUE_INFO` view, which includes *all*
153 recorded messages (even those already processed/cleared from the queue). Aggregations—especially
154 `MAX(SEVERITY)`—therefore reflect the historical log, not just the outstanding backlog. This
155 behaviour is inherent to the IBM SQL service and can lead to higher-than-expected max severity
156 values on pre-7.4 systems.
157
158 Network interface metrics have a fixed internal limit of 50 instances, and HTTP server metrics are capped at 200 instances; these limits are currently not configurable.
159
160 method_description: |
161 The collector connects to IBM i (AS/400) and collects metrics via its monitoring interface.
162 supported_platforms:
163 include: []
164 exclude: []
165 multi_instance: true
166 additional_permissions:
167 description: ""
168 default_behavior:
169 auto_detection:
170 description: ""
171 limits:
172 description: ""
173 performance_impact:
174 description: ""
175 setup:
176 prerequisites:
177 list:
178 - title: Enable monitoring interface
179 description: |
180 Ensure the IBM i (AS/400) monitoring interface is accessible.
181 configuration:
182 file:
183 name: ibm.d/as400.conf
184 options:
185 description: |
186 Configuration options for the as400 collector.
187 folding:
188 title: Config options
189 enabled: true
190 list:
191 - name: update_every
192 description: Data collection frequency.
193 default_value: 1
194 required: false
195 - name: endpoint
196 description: Connection endpoint.
197 default_value: "dummy://localhost"
198 required: false
199 examples:
200 folding:
201 enabled: true
202 title: Config
203 list:
204 - name: Basic
205 description: Basic configuration example.
206 config: |
207 jobs:
208 - name: local
209 endpoint: dummy://localhost
210 troubleshooting:
211 problems:
212 list: []
213 alerts: []
214 metrics:
215 folding:
216 title: Metrics
217 enabled: false
218 description: ""
219 availability: []
220 scopes:
221 - name: activejob
222 description: These metrics refer to activejob instances.
223 labels:
224 - name: job_name
225 description: Job_name identifier
226 - name: job_status
227 description: Job_status identifier
228 - name: subsystem
229 description: Subsystem identifier
230 - name: job_type
231 description: Job_type identifier
232 metrics:
233 - name: as400.activejob_cpu
234 description: Active Job CPU Usage
235 unit: percentage
236 chart_type: line
237 dimensions:
238 - name: cpu
239 - name: as400.activejob_resources
240 description: Active Job Resources
241 unit: MiB
242 chart_type: stacked
243 dimensions:
244 - name: temp_storage
245 - name: as400.activejob_time
246 description: Active Job Elapsed Time
247 unit: seconds
248 chart_type: line
249 dimensions:
250 - name: cpu_time
251 - name: total_time
252 - name: as400.activejob_activity
253 description: Active Job Activity
254 unit: operations/s
255 chart_type: area
256 dimensions:
257 - name: disk_io
258 - name: interactive_transactions
259 - name: as400.activejob_threads
260 description: Active Job Thread Count
261 unit: threads
262 chart_type: line
263 dimensions:
264 - name: threads
265 - name: disk
266 description: These metrics refer to disk instances.
267 labels:
268 - name: disk_unit
269 description: Disk_unit identifier
270 - name: disk_type
271 description: Disk_type identifier
272 - name: disk_model
273 description: Disk_model identifier
274 - name: hardware_status
275 description: Hardware_status identifier
276 - name: disk_serial_number
277 description: Disk_serial_number identifier
278 metrics:
279 - name: as400.disk_busy
280 description: Disk Busy Percentage
281 unit: percentage
282 chart_type: line
283 dimensions:
284 - name: busy
285 - name: as400.disk_io_requests
286 description: Disk I/O Requests
287 unit: requests/s
288 chart_type: area
289 dimensions:
290 - name: read
291 - name: write
292 - name: as400.disk_space_usage
293 description: Disk Space Usage
294 unit: percentage
295 chart_type: line
296 dimensions:
297 - name: used
298 - name: as400.disk_capacity
299 description: Disk Capacity
300 unit: gigabytes
301 chart_type: stacked
302 dimensions:
303 - name: available
304 - name: used
305 - name: as400.disk_blocks
306 description: Disk Block Operations
307 unit: blocks/s
308 chart_type: area
309 dimensions:
310 - name: read
311 - name: write
312 - name: as400.disk_ssd_health
313 description: Disk SSD Health
314 unit: percentage
315 chart_type: line
316 dimensions:
317 - name: life_remaining
318 - name: as400.disk_ssd_age
319 description: Disk SSD Power On Days
320 unit: days
321 chart_type: line
322 dimensions:
323 - name: power_on_days
324 - name: httpserver
325 description: These metrics refer to httpserver instances.
326 labels:
327 - name: server
328 description: Server identifier
329 - name: function
330 description: Function identifier
331 metrics:
332 - name: as400.http_server_connections
333 description: HTTP Server Connections
334 unit: connections
335 chart_type: line
336 dimensions:
337 - name: normal
338 - name: ssl
339 - name: as400.http_server_threads
340 description: HTTP Server Threads
341 unit: threads
342 chart_type: line
343 dimensions:
344 - name: active
345 - name: idle
346 - name: as400.http_server_requests
347 description: HTTP Server Requests
348 unit: requests/s
349 chart_type: area
350 dimensions:
351 - name: requests
352 - name: responses
353 - name: rejected
354 - name: as400.http_server_bytes
355 description: HTTP Server Throughput
356 unit: bytes/s
357 chart_type: area
358 dimensions:
359 - name: received
360 - name: sent
361 - name: jobqueue
362 description: These metrics refer to jobqueue instances.
363 labels:
364 - name: job_queue
365 description: Job_queue identifier
366 - name: library
367 description: Library identifier
368 - name: status
369 description: Status identifier
370 metrics:
371 - name: as400.jobqueue_length
372 description: Job Queue Length
373 unit: jobs
374 chart_type: line
375 dimensions:
376 - name: jobs
377 - name: messagequeue
378 description: These metrics refer to messagequeue instances.
379 labels:
380 - name: library
381 description: Library identifier
382 - name: queue
383 description: Queue identifier
384 metrics:
385 - name: as400.message_queue_messages
386 description: Message Queue Messages
387 unit: messages
388 chart_type: stacked
389 dimensions:
390 - name: total
391 - name: informational
392 - name: inquiry
393 - name: diagnostic
394 - name: escape
395 - name: notify
396 - name: sender_copy
397 - name: as400.message_queue_severity
398 description: Message Queue Severity
399 unit: severity
400 chart_type: line
401 dimensions:
402 - name: max
403 - name: networkinterface
404 description: These metrics refer to networkinterface instances.
405 labels:
406 - name: interface
407 description: Interface identifier
408 - name: interface_type
409 description: Interface_type identifier
410 - name: connection_type
411 description: Connection_type identifier
412 - name: internet_address
413 description: Internet_address identifier
414 - name: network_address
415 description: Network_address identifier
416 - name: subnet_mask
417 description: Subnet_mask identifier
418 metrics:
419 - name: as400.network_interface_status
420 description: Network Interface Status
421 unit: status
422 chart_type: line
423 dimensions:
424 - name: active
425 - name: as400.network_interface_mtu
426 description: Network Interface MTU
427 unit: bytes
428 chart_type: line
429 dimensions:
430 - name: mtu
431 - name: global
432 description: These metrics refer to the entire monitored instance.
433 labels: []
434 metrics:
435 - name: netdata.plugin_ibm.as400_query_latency_fast
436 description: AS400 Query Latency (Fast Path)
437 unit: ms
438 chart_type: stacked
439 dimensions:
440 - name: count_disks
441 - name: count_http_servers
442 - name: count_network_interfaces
443 - name: detect_ibmi_version_primary
444 - name: detect_ibmi_version_fallback
445 - name: disk_instances
446 - name: disk_instances_enhanced
447 - name: disk_status
448 - name: http_server_info
449 - name: job_info
450 - name: memory_pools
451 - name: network_connections
452 - name: network_interfaces
453 - name: serial_number
454 - name: system_name
455 - name: system_activity
456 - name: system_model
457 - name: system_status
458 - name: temp_storage_named
459 - name: temp_storage_total
460 - name: technology_refresh_level
461 - name: active_job
462 - name: netdata.plugin_ibm.as400_query_latency_slow
463 description: AS400 Query Latency (Slow Path)
464 unit: ms
465 chart_type: stacked
466 dimensions:
467 - name: analyze_plan_cache
468 - name: count_subsystems
469 - name: subsystems
470 - name: message_queue_aggregates
471 - name: job_queues
472 - name: output_queue_info
473 - name: plan_cache_summary
474 - name: netdata.plugin_ibm.as400_query_latency_batch
475 description: AS400 Query Latency (Batch Path)
476 unit: ms
477 chart_type: stacked
478 dimensions:
479 - name: message_queue_totals
480 - name: job_queue_totals
481 - name: output_queue_totals
482 - name: outputqueue
483 description: These metrics refer to outputqueue instances.
484 labels:
485 - name: library
486 description: Library identifier
487 - name: queue
488 description: Queue identifier
489 - name: status
490 description: Status identifier
491 metrics:
492 - name: as400.output_queue_files
493 description: Output Queue Files
494 unit: files
495 chart_type: line
496 dimensions:
497 - name: files
498 - name: as400.output_queue_writers
499 description: Output Queue Writers
500 unit: writers
501 chart_type: line
502 dimensions:
503 - name: writers
504 - name: as400.output_queue_status
505 description: Output Queue Status
506 unit: state
507 chart_type: line
508 dimensions:
509 - name: released
510 - name: plancache
511 description: These metrics refer to plancache instances.
512 labels:
513 - name: metric
514 description: Metric identifier
515 metrics:
516 - name: as400.plan_cache_summary
517 description: Plan Cache Summary
518 unit: value
519 chart_type: line
520 dimensions:
521 - name: value
522 - name: queueoverview
523 description: These metrics refer to queueoverview instances.
524 labels:
525 - name: queue_type
526 description: Queue_type identifier
527 - name: item_type
528 description: Item_type identifier
529 metrics:
530 - name: as400.queues_count
531 description: Queue Counts
532 unit: queues
533 chart_type: line
534 dimensions:
535 - name: queues
536 - name: as400.queued_items
537 description: Queued Items
538 unit: items
539 chart_type: line
540 dimensions:
541 - name: items
542 - name: subsystem
543 description: These metrics refer to subsystem instances.
544 labels:
545 - name: subsystem
546 description: Subsystem identifier
547 - name: library
548 description: Library identifier
549 - name: status
550 description: Status identifier
551 metrics:
552 - name: as400.subsystem_jobs
553 description: Subsystem Jobs
554 unit: jobs
555 chart_type: line
556 dimensions:
557 - name: active
558 - name: maximum
559 - name: global
560 description: These metrics refer to the entire monitored instance.
561 labels: []
562 metrics:
563 - name: as400.cpu_utilization
564 description: CPU Utilization (100% = 1 CPU core)
565 unit: percentage
566 chart_type: line
567 dimensions:
568 - name: utilization
569 - name: as400.cpu_utilization_entitled
570 description: CPU Utilization (as % of entitlement)
571 unit: percentage
572 chart_type: line
573 dimensions:
574 - name: utilization
575 - name: as400.cpu_configuration
576 description: CPU Configuration
577 unit: cpus
578 chart_type: line
579 dimensions:
580 - name: configured
581 - name: as400.cpu_capacity
582 description: Current CPU Capacity
583 unit: percentage
584 chart_type: line
585 dimensions:
586 - name: capacity
587 - name: as400.total_jobs
588 description: Total Jobs in System
589 unit: jobs
590 chart_type: line
591 dimensions:
592 - name: total
593 - name: as400.active_jobs_by_type
594 description: Active Jobs by Type
595 unit: jobs
596 chart_type: stacked
597 dimensions:
598 - name: batch
599 - name: interactive
600 - name: active
601 - name: as400.job_queue_length
602 description: Job Queue Length
603 unit: jobs
604 chart_type: line
605 dimensions:
606 - name: waiting
607 - name: as400.main_storage_size
608 description: Main Storage Size
609 unit: bytes
610 chart_type: line
611 dimensions:
612 - name: total
613 - name: as400.temporary_storage
614 description: Temporary Storage
615 unit: MiB
616 chart_type: line
617 dimensions:
618 - name: current
619 - name: maximum
620 - name: as400.memory_pool_usage
621 description: Memory Pool Usage
622 unit: bytes
623 chart_type: stacked
624 dimensions:
625 - name: machine
626 - name: base
627 - name: interactive
628 - name: spool
629 - name: as400.memory_pool_defined
630 description: Memory Pool Defined Size
631 unit: bytes
632 chart_type: stacked
633 dimensions:
634 - name: machine
635 - name: base
636 - name: as400.memory_pool_reserved
637 description: Memory Pool Reserved Size
638 unit: bytes
639 chart_type: stacked
640 dimensions:
641 - name: machine
642 - name: base
643 - name: as400.memory_pool_threads
644 description: Memory Pool Threads
645 unit: threads
646 chart_type: line
647 dimensions:
648 - name: machine
649 - name: base
650 - name: as400.memory_pool_max_threads
651 description: Memory Pool Maximum Threads
652 unit: threads
653 chart_type: line
654 dimensions:
655 - name: machine
656 - name: base
657 - name: as400.disk_busy_average
658 description: Average Disk Busy Percentage
659 unit: percentage
660 chart_type: line
661 dimensions:
662 - name: busy
663 - name: as400.system_asp_usage
664 description: System ASP Usage
665 unit: percentage
666 chart_type: line
667 dimensions:
668 - name: used
669 - name: as400.system_asp_storage
670 description: System ASP Storage
671 unit: MiB
672 chart_type: line
673 dimensions:
674 - name: total
675 - name: as400.total_auxiliary_storage
676 description: Total Auxiliary Storage
677 unit: MiB
678 chart_type: line
679 dimensions:
680 - name: total
681 - name: as400.system_threads
682 description: System Threads
683 unit: threads
684 chart_type: line
685 dimensions:
686 - name: active
687 - name: per_processor
688 - name: as400.network_connections
689 description: Network Connections
690 unit: connections
691 chart_type: line
692 dimensions:
693 - name: remote
694 - name: total
695 - name: as400.network_connection_states
696 description: Network Connection States
697 unit: connections
698 chart_type: line
699 dimensions:
700 - name: listen
701 - name: close_wait
702 - name: as400.temp_storage_total
703 description: Temporary Storage Total
704 unit: bytes
705 chart_type: line
706 dimensions:
707 - name: current
708 - name: peak
709 - name: as400.system_activity_cpu_rate
710 description: System CPU Rate
711 unit: percentage
712 chart_type: line
713 dimensions:
714 - name: average
715 - name: as400.system_activity_cpu_utilization
716 description: System CPU Utilization
717 unit: percentage
718 chart_type: line
719 dimensions:
720 - name: average
721 - name: minimum
722 - name: maximum
723 - name: tempstoragebucket
724 description: These metrics refer to tempstoragebucket instances.
725 labels:
726 - name: bucket
727 description: Bucket identifier
728 metrics:
729 - name: as400.temp_storage_bucket
730 description: Temporary Storage Bucket Usage
731 unit: bytes
732 chart_type: line
733 dimensions:
734 - name: current
735 - name: peak