@cryptotaxi247 / netdata-1 / commits / 042e63994

Regenerate integrations docs (#19432)

Co-authored-by: ilyam8 <22274335+ilyam8@users.noreply.github.com>

Netdata bot committed Jan 17, 2025 at 09:30 UTC 042e63994c529313ac3a8cb7785a10430c4a5104
3 files changed +204
src/collectors/COLLECTORS.md
+2
@@ -849,6 +849,8 @@ If you don't see the app/service you'd like to monitor in this list:
849
850 - [OpenROADM devices](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/openroadm_devices.md)
851
852 +- [Optical modules](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/ethtool/integrations/optical_modules.md)
853 +
854 - [RIPE Atlas](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/ripe_atlas.md)
855
856 - [SONiC NOS](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/sonic_nos.md)
src/go/plugin/go.d/collector/ethtool/README.md new
+1
@@ -0,0 +1 @@
1 +integrations/optical_modules.md
\ No newline at end of file
src/go/plugin/go.d/collector/ethtool/integrations/optical_modules.md new
+201
@@ -0,0 +1,201 @@
1 +<!--startmeta
2 +custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/ethtool/README.md"
3 +meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/ethtool/metadata.yaml"
4 +sidebar_label: "Optical modules"
5 +learn_status: "Published"
6 +learn_rel_path: "Collecting Metrics/Networking Stack and Network Interfaces"
7 +most_popular: False
8 +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
9 +endmeta-->
10 +
11 +# Optical modules
12 +
13 +
14 +<img src="https://netdata.cloud/img/network-wired.svg" width="150"/>
15 +
16 +
17 +Plugin: go.d.plugin
18 +Module: ethtool
19 +
20 +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
21 +
22 +## Overview
23 +
24 +This collector monitors optical transceiver modules' diagnostic parameters (temperature, voltage, laser bias current, transmit/receive power levels) from network interfaces equipped with modules that support Digital Diagnostic Monitoring (DDM). It relies on the [`ethtool`](https://man7.org/linux/man-pages/man8/ethtool.8.html) CLI tool but avoids directly executing the binary. Instead, it utilizes `ndsudo`, a Netdata helper specifically designed to run privileged commands securely within the Netdata environment. This approach eliminates the need to use `sudo`, improving security and potentially simplifying permission management.
25 +
26 +
27 +
28 +
29 +This collector is only supported on the following platforms:
30 +
31 +- Linux
32 +
33 +This collector only supports collecting metrics from a single instance of this integration.
34 +
35 +
36 +### Default Behavior
37 +
38 +#### Auto-Detection
39 +
40 +This integration doesn't support auto-detection.
41 +
42 +#### Limits
43 +
44 +The default configuration for this integration does not impose any limits on data collection.
45 +
46 +#### Performance Impact
47 +
48 +The default configuration for this integration is not expected to impose a significant performance impact on the system.
49 +
50 +
51 +## Metrics
52 +
53 +Metrics grouped by *scope*.
54 +
55 +The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
56 +
57 +
58 +
59 +### Per Optical Transceiver Module
60 +
61 +Metrics collected from optical transceiver modules that support Digital Diagnostic Monitoring (DDM).
62 +
63 +Labels:
64 +
65 +| Label | Description |
66 +|:-----------|:----------------|
67 +| iface | Network interface name where the optical transceiver module is installed. |
68 +
69 +Metrics:
70 +
71 +| Metric | Dimensions | Unit |
72 +|:------|:----------|:----|
73 +| ethtool.optical_module_receiver_signal_power | rx_power | dBm |
74 +| ethtool.optical_module_laser_output_power | tx_power | dBm |
75 +| ethtool.optical_module_laser_bias_current | bias_current | mA |
76 +| ethtool.optical_module_temperature | temperature | Celsius |
77 +| ethtool.optical_module_voltage | voltage | Volts |
78 +
79 +
80 +
81 +## Alerts
82 +
83 +There are no alerts configured by default for this integration.
84 +
85 +
86 +## Setup
87 +
88 +### Prerequisites
89 +
90 +No action required.
91 +
92 +### Configuration
93 +
94 +#### File
95 +
96 +The configuration file name for this integration is `go.d/ethtool.conf`.
97 +
98 +
99 +You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-a-configuration-file-using-edit-config) script from the
100 +Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#the-netdata-config-directory).
101 +
102 +```bash
103 +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
104 +sudo ./edit-config go.d/ethtool.conf
105 +```
106 +#### Options
107 +
108 +The following options can be defined globally: update_every.
109 +
110 +
111 +<details open><summary>Config options</summary>
112 +
113 +| Name | Description | Default | Required |
114 +|:----|:-----------|:-------|:--------:|
115 +| update_every | Data collection frequency. | 10 | no |
116 +| timeout | Timeout for executing the binary, specified in seconds. | 2 | no |
117 +| optical_interfaces | Space-separated list of optical interface names which must have optical transceiver modules with [DDM](https://en.wikipedia.org/wiki/Small_Form-factor_Pluggable#Digital_diagnostics_monitoring). | | yes |
118 +
119 +</details>
120 +
121 +#### Examples
122 +
123 +##### Custom binary path
124 +
125 +The executable is not in the directories specified in the PATH environment variable.
126 +
127 +<details open><summary>Config</summary>
128 +
129 +```yaml
130 +jobs:
131 + - name: ethtool
132 + binary_path: /usr/local/sbin/ethtool
133 + optical_interfaces: "enp1s0 enp1s1 enp2s0"
134 +
135 +```
136 +</details>
137 +
138 +
139 +
140 +## Troubleshooting
141 +
142 +### Debug Mode
143 +
144 +**Important**: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.
145 +
146 +To troubleshoot issues with the `ethtool` collector, run the `go.d.plugin` with the debug option enabled. The output
147 +should give you clues as to why the collector isn't working.
148 +
149 +- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on
150 + your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.
151 +
152 + ```bash
153 + cd /usr/libexec/netdata/plugins.d/
154 + ```
155 +
156 +- Switch to the `netdata` user.
157 +
158 + ```bash
159 + sudo -u netdata -s
160 + ```
161 +
162 +- Run the `go.d.plugin` to debug the collector:
163 +
164 + ```bash
165 + ./go.d.plugin -d -m ethtool
166 + ```
167 +
168 +### Getting Logs
169 +
170 +If you're encountering problems with the `ethtool` collector, follow these steps to retrieve logs and identify potential issues:
171 +
172 +- **Run the command** specific to your system (systemd, non-systemd, or Docker container).
173 +- **Examine the output** for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.
174 +
175 +#### System with systemd
176 +
177 +Use the following command to view logs generated since the last Netdata service restart:
178 +
179 +```bash
180 +journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep ethtool
181 +```
182 +
183 +#### System without systemd
184 +
185 +Locate the collector log file, typically at `/var/log/netdata/collector.log`, and use `grep` to filter for collector's name:
186 +
187 +```bash
188 +grep ethtool /var/log/netdata/collector.log
189 +```
190 +
191 +**Note**: This method shows logs from all restarts. Focus on the **latest entries** for troubleshooting current issues.
192 +
193 +#### Docker Container
194 +
195 +If your Netdata runs in a Docker container named "netdata" (replace if different), use this command:
196 +
197 +```bash
198 +docker logs netdata 2>&1 | grep ethtool
199 +```
200 +
201 +