Regenerate integrations.js (#18016)
Co-authored-by: ilyam8 <22274335+ilyam8@users.noreply.github.com>
Netdata bot committed
Jun 26, 2024 at 13:08 UTC
f7c6ba2ca2e206273e24b9431554068a8aae6f5d
3 files changed
+128
-71
integrations/integrations.js
+3
-3
@@ -16027,11 +16027,11 @@ export const integrations = [
16027
},
16028
"most_popular": true
16029
},
16030
- "overview": "# SNMP devices\n\nPlugin: go.d.plugin\nModule: snmp\n\n## Overview\n\nThis collector monitors any SNMP devices and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.\n\nIt supports:\n\n- all SNMP versions: SNMPv1, SNMPv2c and SNMPv3.\n- any number of SNMP devices.\n- each SNMP device can be used to collect data for any number of charts.\n- each chart may have any number of dimensions.\n- each SNMP device may have a different update frequency.\n- each SNMP device will accept one or more batches to report values (you can set `max_request_size` per SNMP server, to control the size of batches).\n\nKeep in mind that many SNMP switches and routers are very slow. They may not be able to report values per second.\n`go.d.plugin` reports the time it took for the SNMP device to respond when executed in the debug mode.\n\nAlso, if many SNMP clients are used on the same SNMP device at the same time, values may be skipped.\nThis is a problem of the SNMP device, not this collector. In this case, consider reducing the frequency of data collection (increasing `update_every`).\n\n\n\n\nThis collector is supported on all platforms.\n\nThis collector supports collecting metrics from multiple instances of this integration, including remote instances.\n\n\n### Default Behavior\n\n#### Auto-Detection\n\nThis integration doesn't support auto-detection.\n\n#### Limits\n\nThe default configuration for this integration does not impose any limits on data collection.\n\n#### Performance Impact\n\nThe default configuration for this integration is not expected to impose a significant performance impact on the system.\n",
16031
- "setup": "## Setup\n\n### Prerequisites\n\n#### Find OIDs\n\nUse `snmpwalk`, like this:\n\n```sh\nsnmpwalk -t 20 -O fn -v 2c -c public 192.0.2.1\n```\n\n- `-t 20` is the timeout in seconds.\n- `-O fn` will display full OIDs in numeric format.\n- `-v 2c` is the SNMP version.\n- `-c public` is the SNMP community.\n- `192.0.2.1` is the SNMP device.\n\n\n\n### Configuration\n\n#### File\n\nThe configuration file name for this integration is `go.d/snmp.conf`.\n\n\nYou can edit the configuration file using the `edit-config` script from the\nNetdata [config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory).\n\n```bash\ncd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata\nsudo ./edit-config go.d/snmp.conf\n```\n#### Options\n\nThe following options can be defined globally: update_every, autodetection_retry.\n\n\n{% details open=true summary=\"Config options\" %}\n| Name | Description | Default | Required |\n|:----|:-----------|:-------|:--------:|\n| update_every | Data collection frequency. | 1 | no |\n| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |\n| hostname | Target ipv4 address. | 127.0.0.1 | yes |\n| community | SNMPv1/2 community string. | public | no |\n| options.version | SNMP version. Available versions: 1, 2, 3. | 2 | no |\n| options.port | Target port. | 161 | no |\n| options.retries | Retries to attempt. | 1 | no |\n| options.timeout | SNMP request/response timeout. | 10 | no |\n| options.max_request_size | Maximum number of OIDs allowed in one one SNMP request. | 60 | no |\n| user.name | SNMPv3 user name. | | no |\n| user.name | Security level of SNMPv3 messages. | | no |\n| user.auth_proto | Security level of SNMPv3 messages. | | no |\n| user.name | Authentication protocol for SNMPv3 messages. | | no |\n| user.auth_key | Authentication protocol pass phrase. | | no |\n| user.priv_proto | Privacy protocol for SNMPv3 messages. | | no |\n| user.priv_key | Privacy protocol pass phrase. | | no |\n| charts | List of charts. | [] | yes |\n| charts.id | Chart ID. Used to uniquely identify the chart. | | yes |\n| charts.title | Chart title. | Untitled chart | no |\n| charts.units | Chart units. | num | no |\n| charts.family | Chart family. | charts.id | no |\n| charts.type | Chart type (line, area, stacked). | line | no |\n| charts.priority | Chart priority. | 70000 | no |\n| charts.multiply_range | Used when you need to define many charts using incremental OIDs. | [] | no |\n| charts.dimensions | List of chart dimensions. | [] | yes |\n| charts.dimensions.oid | Collected metric OID. | | yes |\n| charts.dimensions.name | Dimension name. | | yes |\n| charts.dimensions.algorithm | Dimension algorithm (absolute, incremental). | absolute | no |\n| charts.dimensions.multiplier | Collected value multiplier, applied to convert it properly to units. | 1 | no |\n| charts.dimensions.divisor | Collected value divisor, applied to convert it properly to units. | 1 | no |\n\n##### user.auth_proto\n\nThe security of an SNMPv3 message as per RFC 3414 (`user.level`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|------------------------------------------|\n| none | 1 | no message authentication or encryption |\n| authNoPriv | 2 | message authentication and no encryption |\n| authPriv | 3 | message authentication and encryption |\n\n\n##### user.name\n\nThe digest algorithm for SNMPv3 messages that require authentication (`user.auth_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------|\n| none | 1 | no message authentication |\n| md5 | 2 | MD5 message authentication (HMAC-MD5-96) |\n| sha | 3 | SHA message authentication (HMAC-SHA-96) |\n| sha224 | 4 | SHA message authentication (HMAC-SHA-224) |\n| sha256 | 5 | SHA message authentication (HMAC-SHA-256) |\n| sha384 | 6 | SHA message authentication (HMAC-SHA-384) |\n| sha512 | 7 | SHA message authentication (HMAC-SHA-512) |\n\n\n##### user.priv_proto\n\nThe encryption algorithm for SNMPv3 messages that require privacy (`user.priv_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------------------------------------|\n| none | 1 | no message encryption |\n| des | 2 | ES encryption (CBC-DES) |\n| aes | 3 | 128-bit AES encryption (CFB-AES-128) |\n| aes192 | 4 | 192-bit AES encryption (CFB-AES-192) with \"Blumenthal\" key localization |\n| aes256 | 5 | 256-bit AES encryption (CFB-AES-256) with \"Blumenthal\" key localization |\n| aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with \"Reeder\" key localization |\n| aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with \"Reeder\" key localization |\n\n\n{% /details %}\n#### Examples\n\n##### SNMPv1/2\n\nIn this example:\n\n- the SNMP device is `192.0.2.1`.\n- the SNMP version is `2`.\n- the SNMP community is `public`.\n- we will update the values every 10 seconds.\n- we define 2 charts `bandwidth_port1` and `bandwidth_port2`, each having 2 dimensions: `in` and `out`.\n\n> **SNMPv1**: just set `options.version` to 1.\n> **Note**: the algorithm chosen is `incremental`, because the collected values show the total number of bytes transferred, which we need to transform into kbps. To chart gauges (e.g. temperature), use `absolute` instead.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - id: \"bandwidth_port2\"\n title: \"Switch Bandwidth for port 2\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.2\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.2\"\n multiplier: -8\n divisor: 1000\n\n```\n{% /details %}\n##### SNMPv3\n\nTo use SNMPv3:\n\n- use `user` instead of `community`.\n- set `options.version` to 3.\n\nThe rest of the configuration is the same as in the SNMPv1/2 example.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n options:\n version: 3\n user:\n name: username\n level: authPriv\n auth_proto: sha256\n auth_key: auth_protocol_passphrase\n priv_proto: aes256\n priv_key: priv_protocol_passphrase\n\n```\n{% /details %}\n##### Multiply range\n\nIf you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option.\n\nThis is like the SNMPv1/2 example, but the option will multiply the current chart from 1 to 24 inclusive, producing 24 charts in total for the 24 ports of the switch `192.0.2.1`.\n\nEach of the 24 new charts will have its id (1-24) appended at:\n\n- its chart unique `id`, i.e. `bandwidth_port_1` to `bandwidth_port_24`.\n- its title, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`.\n- its `oid` (for all dimensions), i.e. dimension in will be `1.3.6.1.2.1.2.2.1.10.1` to `1.3.6.1.2.1.2.2.1.10.24`.\n- its `priority` will be incremented for each chart so that the charts will appear on the dashboard in this order.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port\"\n title: \"Switch Bandwidth for port\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n multiply_range: [1, 24]\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16\"\n multiplier: -8\n divisor: 1000\n\n```\n{% /details %}\n##### Multiple devices with a common configuration\n\nYAML supports [anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases). \nThe `&` defines and names an anchor, and the `*` uses it. `<<: *anchor` means, inject the anchor, then extend. We can use anchors to share the common configuration for multiple devices.\n\nThe following example:\n\n- adds an `anchor` to the first job.\n- injects (copies) the first job configuration to the second and updates `name` and `hostname` parameters.\n- injects (copies) the first job configuration to the third and updates `name` and `hostname` parameters.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - &anchor\n name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - <<: *anchor\n name: switch2\n hostname: \"192.0.2.2\"\n - <<: *anchor\n name: switch3\n hostname: \"192.0.2.3\"\n\n```\n{% /details %}\n",
16030
+ "overview": "# SNMP devices\n\nPlugin: go.d.plugin\nModule: snmp\n\n## Overview\n\nThis SNMP collector discovers and gathers statistics for network interfaces on SNMP-enabled devices:\n\n- Traffic\n- Packets (unicast, multicast, broadcast)\n- Errors\n- Discards\n- Administrative and operational status\n\nAdditionally, it collects overall device uptime.\n\nIt is compatible with all SNMP versions (v1, v2c, and v3) and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.\n\n**For advanced users**:\n\n- You can manually specify custom OIDs (Object Identifiers) to retrieve specific data points beyond the default metrics.\n- However, defining custom charts with dimensions for these OIDs requires manual configuration.\n\n\n\n\nThis collector is supported on all platforms.\n\nThis collector supports collecting metrics from multiple instances of this integration, including remote instances.\n\n\n### Default Behavior\n\n#### Auto-Detection\n\nThis integration doesn't support auto-detection.\n\n#### Limits\n\nThe default configuration for this integration does not impose any limits on data collection.\n\n#### Performance Impact\n\n**Performance Considerations**:\n\n- **Device limitations**: Many SNMP switches and routers have limited processing power. They might not be able to report data as frequently as desired. You can monitor response times using go.d.plugin in debug mode to identify potential bottlenecks.\n\n- **Concurrent access**: If multiple collectors or tools access the same SNMP device simultaneously, data points might be skipped. This is a limitation of the device itself, not this collector. To mitigate this, consider increasing the collection interval (update_every) to reduce the frequency of requests.\n\n",
16031
+ "setup": "## Setup\n\n### Prerequisites\n\nNo action required.\n\n### Configuration\n\n#### File\n\nThe configuration file name for this integration is `go.d/snmp.conf`.\n\n\nYou can edit the configuration file using the `edit-config` script from the\nNetdata [config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory).\n\n```bash\ncd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata\nsudo ./edit-config go.d/snmp.conf\n```\n#### Options\n\nThe following options can be defined globally: update_every, autodetection_retry.\n\n\n{% details open=true summary=\"Config options\" %}\n| Name | Description | Default | Required |\n|:----|:-----------|:-------|:--------:|\n| update_every | Data collection frequency. | 10 | no |\n| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |\n| hostname | Target ipv4 address. | | yes |\n| community | SNMPv1/2 community string. | public | no |\n| options.version | SNMP version. Available versions: 1, 2, 3. | 2 | no |\n| options.port | Target port. | 161 | no |\n| options.retries | Retries to attempt. | 1 | no |\n| options.timeout | SNMP request/response timeout. | 5 | no |\n| options.max_repetitions | Controls how many SNMP variables to retrieve in a single GETBULK request. | 25 | no |\n| options.max_request_size | Maximum number of OIDs allowed in a single GET request. | 60 | no |\n| user.name | SNMPv3 user name. | | no |\n| user.name | Security level of SNMPv3 messages. | | no |\n| user.auth_proto | Security level of SNMPv3 messages. | | no |\n| user.name | Authentication protocol for SNMPv3 messages. | | no |\n| user.auth_key | Authentication protocol pass phrase. | | no |\n| user.priv_proto | Privacy protocol for SNMPv3 messages. | | no |\n| user.priv_key | Privacy protocol pass phrase. | | no |\n| charts | List of charts. | [] | yes |\n| charts.id | Chart ID. Used to uniquely identify the chart. | | yes |\n| charts.title | Chart title. | Untitled chart | no |\n| charts.units | Chart units. | num | no |\n| charts.family | Chart family. | charts.id | no |\n| charts.type | Chart type (line, area, stacked). | line | no |\n| charts.priority | Chart priority. | 70000 | no |\n| charts.multiply_range | Used when you need to define many charts using incremental OIDs. | [] | no |\n| charts.dimensions | List of chart dimensions. | [] | yes |\n| charts.dimensions.oid | Collected metric OID. | | yes |\n| charts.dimensions.name | Dimension name. | | yes |\n| charts.dimensions.algorithm | Dimension algorithm (absolute, incremental). | absolute | no |\n| charts.dimensions.multiplier | Collected value multiplier, applied to convert it properly to units. | 1 | no |\n| charts.dimensions.divisor | Collected value divisor, applied to convert it properly to units. | 1 | no |\n\n##### user.auth_proto\n\nThe security of an SNMPv3 message as per RFC 3414 (`user.level`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|------------------------------------------|\n| none | 1 | no message authentication or encryption |\n| authNoPriv | 2 | message authentication and no encryption |\n| authPriv | 3 | message authentication and encryption |\n\n\n##### user.name\n\nThe digest algorithm for SNMPv3 messages that require authentication (`user.auth_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------|\n| none | 1 | no message authentication |\n| md5 | 2 | MD5 message authentication (HMAC-MD5-96) |\n| sha | 3 | SHA message authentication (HMAC-SHA-96) |\n| sha224 | 4 | SHA message authentication (HMAC-SHA-224) |\n| sha256 | 5 | SHA message authentication (HMAC-SHA-256) |\n| sha384 | 6 | SHA message authentication (HMAC-SHA-384) |\n| sha512 | 7 | SHA message authentication (HMAC-SHA-512) |\n\n\n##### user.priv_proto\n\nThe encryption algorithm for SNMPv3 messages that require privacy (`user.priv_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------------------------------------|\n| none | 1 | no message encryption |\n| des | 2 | ES encryption (CBC-DES) |\n| aes | 3 | 128-bit AES encryption (CFB-AES-128) |\n| aes192 | 4 | 192-bit AES encryption (CFB-AES-192) with \"Blumenthal\" key localization |\n| aes256 | 5 | 256-bit AES encryption (CFB-AES-256) with \"Blumenthal\" key localization |\n| aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with \"Reeder\" key localization |\n| aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with \"Reeder\" key localization |\n\n\n{% /details %}\n#### Examples\n\n##### SNMPv1/2\n\nIn this example:\n\n- the SNMP device is `192.0.2.1`.\n- the SNMP version is `2`.\n- the SNMP community is `public`.\n- we will update the values every 10 seconds.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n community: public\n options:\n version: 2\n\n```\n{% /details %}\n##### SNMPv3\n\nTo use SNMPv3:\n\n- use `user` instead of `community`.\n- set `options.version` to 3.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n options:\n version: 3\n user:\n name: username\n level: authPriv\n auth_proto: sha256\n auth_key: auth_protocol_passphrase\n priv_proto: aes256\n priv_key: priv_protocol_passphrase\n\n```\n{% /details %}\n##### Custom OIDs\n\nIn this example:\n\n- the SNMP device is `192.0.2.1`.\n- the SNMP version is `2`.\n- the SNMP community is `public`.\n- we will update the values every 10 seconds.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - id: \"bandwidth_port2\"\n title: \"Switch Bandwidth for port 2\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.2\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.2\"\n multiplier: -8\n divisor: 1000\n\n```\n{% /details %}\n##### Custom OIDs with multiply range\n\nIf you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option.\n\nThis is like the SNMPv1/2 example, but the option will multiply the current chart from 1 to 24 inclusive, producing 24 charts in total for the 24 ports of the switch `192.0.2.1`.\n\nEach of the 24 new charts will have its id (1-24) appended at:\n\n- its chart unique `id`, i.e. `bandwidth_port_1` to `bandwidth_port_24`.\n- its title, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`.\n- its `oid` (for all dimensions), i.e. dimension in will be `1.3.6.1.2.1.2.2.1.10.1` to `1.3.6.1.2.1.2.2.1.10.24`.\n- its `priority` will be incremented for each chart so that the charts will appear on the dashboard in this order.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port\"\n title: \"Switch Bandwidth for port\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n multiply_range: [1, 24]\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16\"\n multiplier: -8\n divisor: 1000\n\n```\n{% /details %}\n##### Multiple devices with a common configuration\n\nYAML supports [anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases). \nThe `&` defines and names an anchor, and the `*` uses it. `<<: *anchor` means, inject the anchor, then extend. We can use anchors to share the common configuration for multiple devices.\n\nThe following example:\n\n- adds an `anchor` to the first job.\n- injects (copies) the first job configuration to the second and updates `name` and `hostname` parameters.\n- injects (copies) the first job configuration to the third and updates `name` and `hostname` parameters.\n\n\n{% details open=true summary=\"Config\" %}\n```yaml\njobs:\n - &anchor\n name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - <<: *anchor\n name: switch2\n hostname: \"192.0.2.2\"\n - <<: *anchor\n name: switch3\n hostname: \"192.0.2.3\"\n\n```\n{% /details %}\n",
16032
"troubleshooting": "## Troubleshooting\n\n### Debug Mode\n\nTo troubleshoot issues with the `snmp` collector, run the `go.d.plugin` with the debug option enabled. The output\nshould give you clues as to why the collector isn't working.\n\n- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on\n your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.\n\n ```bash\n cd /usr/libexec/netdata/plugins.d/\n ```\n\n- Switch to the `netdata` user.\n\n ```bash\n sudo -u netdata -s\n ```\n\n- Run the `go.d.plugin` to debug the collector:\n\n ```bash\n ./go.d.plugin -d -m snmp\n ```\n\n### Getting Logs\n\nIf you're encountering problems with the `snmp` collector, follow these steps to retrieve logs and identify potential issues:\n\n- **Run the command** specific to your system (systemd, non-systemd, or Docker container).\n- **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.\n\n#### System with systemd\n\nUse the following command to view logs generated since the last Netdata service restart:\n\n```bash\njournalctl _SYSTEMD_INVOCATION_ID=\"$(systemctl show --value --property=InvocationID netdata)\" --namespace=netdata --grep snmp\n```\n\n#### System without systemd\n\nLocate the collector log file, typically at `/var/log/netdata/collector.log`, and use `grep` to filter for collector's name:\n\n```bash\ngrep snmp /var/log/netdata/collector.log\n```\n\n**Note**: This method shows logs from all restarts. Focus on the **latest entries** for troubleshooting current issues.\n\n#### Docker Container\n\nIf your Netdata runs in a Docker container named \"netdata\" (replace if different), use this command:\n\n```bash\ndocker logs netdata 2>&1 | grep snmp\n```\n\n",
16033
"alerts": "## Alerts\n\nThere are no alerts configured by default for this integration.\n",
16034
- "metrics": "## Metrics\n\nThe metrics that will be collected are defined in the configuration file.\n",
16034
+ "metrics": "## Metrics\n\nMetrics grouped by *scope*.\n\nThe scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.\n\nThe metrics that will be collected are defined in the configuration file.\n\n### Per snmp device\n\nThese metrics refer to the SNMP device.\n\nLabels:\n\n| Label | Description |\n|:-----------|:----------------|\n| sysName | SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5)). |\n\nMetrics:\n\n| Metric | Dimensions | Unit |\n|:------|:----------|:----|\n| snmp.device_uptime | uptime | seconds |\n\n### Per network interface\n\nNetwork interfaces of the SNMP device being monitored. These metrics refer to each interface.\n\nLabels:\n\n| Label | Description |\n|:-----------|:----------------|\n| sysName | SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5)). |\n| ifDescr | Network interface description (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.2)). |\n| ifName | Network interface name (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.31.1.1.1.1)). |\n| ifType | Network interface type (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.3)). |\n\nMetrics:\n\n| Metric | Dimensions | Unit |\n|:------|:----------|:----|\n| snmp.device_net_interface_traffic | received, sent | kilobits/s |\n| snmp.device_net_interface_unicast | received, sent | packets/s |\n| snmp.device_net_interface_multicast | received, sent | packets/s |\n| snmp.device_net_interface_broadcast | received, sent | packets/s |\n| snmp.device_net_interface_errors | inbound, outbound | errors/s |\n| snmp.device_net_interface_discards | inbound, outbound | discards/s |\n| snmp.device_net_interface_admin_status | up, down, testing | status |\n| snmp.device_net_interface_oper_status | up, down, testing, unknown, dormant, not_present, lower_layer_down | status |\n\n",
16035
"integration_type": "collector",
16036
"id": "go.d.plugin-snmp-SNMP_devices",
16037
"edit_link": "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/snmp/metadata.yaml",
integrations/integrations.json
+3
-3
@@ -16025,11 +16025,11 @@
16025
},
16026
"most_popular": true
16027
},
16028
- "overview": "# SNMP devices\n\nPlugin: go.d.plugin\nModule: snmp\n\n## Overview\n\nThis collector monitors any SNMP devices and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.\n\nIt supports:\n\n- all SNMP versions: SNMPv1, SNMPv2c and SNMPv3.\n- any number of SNMP devices.\n- each SNMP device can be used to collect data for any number of charts.\n- each chart may have any number of dimensions.\n- each SNMP device may have a different update frequency.\n- each SNMP device will accept one or more batches to report values (you can set `max_request_size` per SNMP server, to control the size of batches).\n\nKeep in mind that many SNMP switches and routers are very slow. They may not be able to report values per second.\n`go.d.plugin` reports the time it took for the SNMP device to respond when executed in the debug mode.\n\nAlso, if many SNMP clients are used on the same SNMP device at the same time, values may be skipped.\nThis is a problem of the SNMP device, not this collector. In this case, consider reducing the frequency of data collection (increasing `update_every`).\n\n\n\n\nThis collector is supported on all platforms.\n\nThis collector supports collecting metrics from multiple instances of this integration, including remote instances.\n\n\n### Default Behavior\n\n#### Auto-Detection\n\nThis integration doesn't support auto-detection.\n\n#### Limits\n\nThe default configuration for this integration does not impose any limits on data collection.\n\n#### Performance Impact\n\nThe default configuration for this integration is not expected to impose a significant performance impact on the system.\n",
16029
- "setup": "## Setup\n\n### Prerequisites\n\n#### Find OIDs\n\nUse `snmpwalk`, like this:\n\n```sh\nsnmpwalk -t 20 -O fn -v 2c -c public 192.0.2.1\n```\n\n- `-t 20` is the timeout in seconds.\n- `-O fn` will display full OIDs in numeric format.\n- `-v 2c` is the SNMP version.\n- `-c public` is the SNMP community.\n- `192.0.2.1` is the SNMP device.\n\n\n\n### Configuration\n\n#### File\n\nThe configuration file name for this integration is `go.d/snmp.conf`.\n\n\nYou can edit the configuration file using the `edit-config` script from the\nNetdata [config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory).\n\n```bash\ncd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata\nsudo ./edit-config go.d/snmp.conf\n```\n#### Options\n\nThe following options can be defined globally: update_every, autodetection_retry.\n\n\n| Name | Description | Default | Required |\n|:----|:-----------|:-------|:--------:|\n| update_every | Data collection frequency. | 1 | no |\n| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |\n| hostname | Target ipv4 address. | 127.0.0.1 | yes |\n| community | SNMPv1/2 community string. | public | no |\n| options.version | SNMP version. Available versions: 1, 2, 3. | 2 | no |\n| options.port | Target port. | 161 | no |\n| options.retries | Retries to attempt. | 1 | no |\n| options.timeout | SNMP request/response timeout. | 10 | no |\n| options.max_request_size | Maximum number of OIDs allowed in one one SNMP request. | 60 | no |\n| user.name | SNMPv3 user name. | | no |\n| user.name | Security level of SNMPv3 messages. | | no |\n| user.auth_proto | Security level of SNMPv3 messages. | | no |\n| user.name | Authentication protocol for SNMPv3 messages. | | no |\n| user.auth_key | Authentication protocol pass phrase. | | no |\n| user.priv_proto | Privacy protocol for SNMPv3 messages. | | no |\n| user.priv_key | Privacy protocol pass phrase. | | no |\n| charts | List of charts. | [] | yes |\n| charts.id | Chart ID. Used to uniquely identify the chart. | | yes |\n| charts.title | Chart title. | Untitled chart | no |\n| charts.units | Chart units. | num | no |\n| charts.family | Chart family. | charts.id | no |\n| charts.type | Chart type (line, area, stacked). | line | no |\n| charts.priority | Chart priority. | 70000 | no |\n| charts.multiply_range | Used when you need to define many charts using incremental OIDs. | [] | no |\n| charts.dimensions | List of chart dimensions. | [] | yes |\n| charts.dimensions.oid | Collected metric OID. | | yes |\n| charts.dimensions.name | Dimension name. | | yes |\n| charts.dimensions.algorithm | Dimension algorithm (absolute, incremental). | absolute | no |\n| charts.dimensions.multiplier | Collected value multiplier, applied to convert it properly to units. | 1 | no |\n| charts.dimensions.divisor | Collected value divisor, applied to convert it properly to units. | 1 | no |\n\n##### user.auth_proto\n\nThe security of an SNMPv3 message as per RFC 3414 (`user.level`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|------------------------------------------|\n| none | 1 | no message authentication or encryption |\n| authNoPriv | 2 | message authentication and no encryption |\n| authPriv | 3 | message authentication and encryption |\n\n\n##### user.name\n\nThe digest algorithm for SNMPv3 messages that require authentication (`user.auth_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------|\n| none | 1 | no message authentication |\n| md5 | 2 | MD5 message authentication (HMAC-MD5-96) |\n| sha | 3 | SHA message authentication (HMAC-SHA-96) |\n| sha224 | 4 | SHA message authentication (HMAC-SHA-224) |\n| sha256 | 5 | SHA message authentication (HMAC-SHA-256) |\n| sha384 | 6 | SHA message authentication (HMAC-SHA-384) |\n| sha512 | 7 | SHA message authentication (HMAC-SHA-512) |\n\n\n##### user.priv_proto\n\nThe encryption algorithm for SNMPv3 messages that require privacy (`user.priv_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------------------------------------|\n| none | 1 | no message encryption |\n| des | 2 | ES encryption (CBC-DES) |\n| aes | 3 | 128-bit AES encryption (CFB-AES-128) |\n| aes192 | 4 | 192-bit AES encryption (CFB-AES-192) with \"Blumenthal\" key localization |\n| aes256 | 5 | 256-bit AES encryption (CFB-AES-256) with \"Blumenthal\" key localization |\n| aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with \"Reeder\" key localization |\n| aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with \"Reeder\" key localization |\n\n\n#### Examples\n\n##### SNMPv1/2\n\nIn this example:\n\n- the SNMP device is `192.0.2.1`.\n- the SNMP version is `2`.\n- the SNMP community is `public`.\n- we will update the values every 10 seconds.\n- we define 2 charts `bandwidth_port1` and `bandwidth_port2`, each having 2 dimensions: `in` and `out`.\n\n> **SNMPv1**: just set `options.version` to 1.\n> **Note**: the algorithm chosen is `incremental`, because the collected values show the total number of bytes transferred, which we need to transform into kbps. To chart gauges (e.g. temperature), use `absolute` instead.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - id: \"bandwidth_port2\"\n title: \"Switch Bandwidth for port 2\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.2\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.2\"\n multiplier: -8\n divisor: 1000\n\n```\n##### SNMPv3\n\nTo use SNMPv3:\n\n- use `user` instead of `community`.\n- set `options.version` to 3.\n\nThe rest of the configuration is the same as in the SNMPv1/2 example.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n options:\n version: 3\n user:\n name: username\n level: authPriv\n auth_proto: sha256\n auth_key: auth_protocol_passphrase\n priv_proto: aes256\n priv_key: priv_protocol_passphrase\n\n```\n##### Multiply range\n\nIf you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option.\n\nThis is like the SNMPv1/2 example, but the option will multiply the current chart from 1 to 24 inclusive, producing 24 charts in total for the 24 ports of the switch `192.0.2.1`.\n\nEach of the 24 new charts will have its id (1-24) appended at:\n\n- its chart unique `id`, i.e. `bandwidth_port_1` to `bandwidth_port_24`.\n- its title, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`.\n- its `oid` (for all dimensions), i.e. dimension in will be `1.3.6.1.2.1.2.2.1.10.1` to `1.3.6.1.2.1.2.2.1.10.24`.\n- its `priority` will be incremented for each chart so that the charts will appear on the dashboard in this order.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port\"\n title: \"Switch Bandwidth for port\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n multiply_range: [1, 24]\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16\"\n multiplier: -8\n divisor: 1000\n\n```\n##### Multiple devices with a common configuration\n\nYAML supports [anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases). \nThe `&` defines and names an anchor, and the `*` uses it. `<<: *anchor` means, inject the anchor, then extend. We can use anchors to share the common configuration for multiple devices.\n\nThe following example:\n\n- adds an `anchor` to the first job.\n- injects (copies) the first job configuration to the second and updates `name` and `hostname` parameters.\n- injects (copies) the first job configuration to the third and updates `name` and `hostname` parameters.\n\n\n```yaml\njobs:\n - &anchor\n name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - <<: *anchor\n name: switch2\n hostname: \"192.0.2.2\"\n - <<: *anchor\n name: switch3\n hostname: \"192.0.2.3\"\n\n```\n",
16028
+ "overview": "# SNMP devices\n\nPlugin: go.d.plugin\nModule: snmp\n\n## Overview\n\nThis SNMP collector discovers and gathers statistics for network interfaces on SNMP-enabled devices:\n\n- Traffic\n- Packets (unicast, multicast, broadcast)\n- Errors\n- Discards\n- Administrative and operational status\n\nAdditionally, it collects overall device uptime.\n\nIt is compatible with all SNMP versions (v1, v2c, and v3) and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.\n\n**For advanced users**:\n\n- You can manually specify custom OIDs (Object Identifiers) to retrieve specific data points beyond the default metrics.\n- However, defining custom charts with dimensions for these OIDs requires manual configuration.\n\n\n\n\nThis collector is supported on all platforms.\n\nThis collector supports collecting metrics from multiple instances of this integration, including remote instances.\n\n\n### Default Behavior\n\n#### Auto-Detection\n\nThis integration doesn't support auto-detection.\n\n#### Limits\n\nThe default configuration for this integration does not impose any limits on data collection.\n\n#### Performance Impact\n\n**Performance Considerations**:\n\n- **Device limitations**: Many SNMP switches and routers have limited processing power. They might not be able to report data as frequently as desired. You can monitor response times using go.d.plugin in debug mode to identify potential bottlenecks.\n\n- **Concurrent access**: If multiple collectors or tools access the same SNMP device simultaneously, data points might be skipped. This is a limitation of the device itself, not this collector. To mitigate this, consider increasing the collection interval (update_every) to reduce the frequency of requests.\n\n",
16029
+ "setup": "## Setup\n\n### Prerequisites\n\nNo action required.\n\n### Configuration\n\n#### File\n\nThe configuration file name for this integration is `go.d/snmp.conf`.\n\n\nYou can edit the configuration file using the `edit-config` script from the\nNetdata [config directory](/docs/netdata-agent/configuration/README.md#the-netdata-config-directory).\n\n```bash\ncd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata\nsudo ./edit-config go.d/snmp.conf\n```\n#### Options\n\nThe following options can be defined globally: update_every, autodetection_retry.\n\n\n| Name | Description | Default | Required |\n|:----|:-----------|:-------|:--------:|\n| update_every | Data collection frequency. | 10 | no |\n| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |\n| hostname | Target ipv4 address. | | yes |\n| community | SNMPv1/2 community string. | public | no |\n| options.version | SNMP version. Available versions: 1, 2, 3. | 2 | no |\n| options.port | Target port. | 161 | no |\n| options.retries | Retries to attempt. | 1 | no |\n| options.timeout | SNMP request/response timeout. | 5 | no |\n| options.max_repetitions | Controls how many SNMP variables to retrieve in a single GETBULK request. | 25 | no |\n| options.max_request_size | Maximum number of OIDs allowed in a single GET request. | 60 | no |\n| user.name | SNMPv3 user name. | | no |\n| user.name | Security level of SNMPv3 messages. | | no |\n| user.auth_proto | Security level of SNMPv3 messages. | | no |\n| user.name | Authentication protocol for SNMPv3 messages. | | no |\n| user.auth_key | Authentication protocol pass phrase. | | no |\n| user.priv_proto | Privacy protocol for SNMPv3 messages. | | no |\n| user.priv_key | Privacy protocol pass phrase. | | no |\n| charts | List of charts. | [] | yes |\n| charts.id | Chart ID. Used to uniquely identify the chart. | | yes |\n| charts.title | Chart title. | Untitled chart | no |\n| charts.units | Chart units. | num | no |\n| charts.family | Chart family. | charts.id | no |\n| charts.type | Chart type (line, area, stacked). | line | no |\n| charts.priority | Chart priority. | 70000 | no |\n| charts.multiply_range | Used when you need to define many charts using incremental OIDs. | [] | no |\n| charts.dimensions | List of chart dimensions. | [] | yes |\n| charts.dimensions.oid | Collected metric OID. | | yes |\n| charts.dimensions.name | Dimension name. | | yes |\n| charts.dimensions.algorithm | Dimension algorithm (absolute, incremental). | absolute | no |\n| charts.dimensions.multiplier | Collected value multiplier, applied to convert it properly to units. | 1 | no |\n| charts.dimensions.divisor | Collected value divisor, applied to convert it properly to units. | 1 | no |\n\n##### user.auth_proto\n\nThe security of an SNMPv3 message as per RFC 3414 (`user.level`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|------------------------------------------|\n| none | 1 | no message authentication or encryption |\n| authNoPriv | 2 | message authentication and no encryption |\n| authPriv | 3 | message authentication and encryption |\n\n\n##### user.name\n\nThe digest algorithm for SNMPv3 messages that require authentication (`user.auth_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------|\n| none | 1 | no message authentication |\n| md5 | 2 | MD5 message authentication (HMAC-MD5-96) |\n| sha | 3 | SHA message authentication (HMAC-SHA-96) |\n| sha224 | 4 | SHA message authentication (HMAC-SHA-224) |\n| sha256 | 5 | SHA message authentication (HMAC-SHA-256) |\n| sha384 | 6 | SHA message authentication (HMAC-SHA-384) |\n| sha512 | 7 | SHA message authentication (HMAC-SHA-512) |\n\n\n##### user.priv_proto\n\nThe encryption algorithm for SNMPv3 messages that require privacy (`user.priv_proto`):\n\n| String value | Int value | Description |\n|:------------:|:---------:|-------------------------------------------------------------------------|\n| none | 1 | no message encryption |\n| des | 2 | ES encryption (CBC-DES) |\n| aes | 3 | 128-bit AES encryption (CFB-AES-128) |\n| aes192 | 4 | 192-bit AES encryption (CFB-AES-192) with \"Blumenthal\" key localization |\n| aes256 | 5 | 256-bit AES encryption (CFB-AES-256) with \"Blumenthal\" key localization |\n| aes192c | 6 | 192-bit AES encryption (CFB-AES-192) with \"Reeder\" key localization |\n| aes256c | 7 | 256-bit AES encryption (CFB-AES-256) with \"Reeder\" key localization |\n\n\n#### Examples\n\n##### SNMPv1/2\n\nIn this example:\n\n- the SNMP device is `192.0.2.1`.\n- the SNMP version is `2`.\n- the SNMP community is `public`.\n- we will update the values every 10 seconds.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n community: public\n options:\n version: 2\n\n```\n##### SNMPv3\n\nTo use SNMPv3:\n\n- use `user` instead of `community`.\n- set `options.version` to 3.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n options:\n version: 3\n user:\n name: username\n level: authPriv\n auth_proto: sha256\n auth_key: auth_protocol_passphrase\n priv_proto: aes256\n priv_key: priv_protocol_passphrase\n\n```\n##### Custom OIDs\n\nIn this example:\n\n- the SNMP device is `192.0.2.1`.\n- the SNMP version is `2`.\n- the SNMP community is `public`.\n- we will update the values every 10 seconds.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: 192.0.2.1\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - id: \"bandwidth_port2\"\n title: \"Switch Bandwidth for port 2\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.2\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.2\"\n multiplier: -8\n divisor: 1000\n\n```\n##### Custom OIDs with multiply range\n\nIf you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option.\n\nThis is like the SNMPv1/2 example, but the option will multiply the current chart from 1 to 24 inclusive, producing 24 charts in total for the 24 ports of the switch `192.0.2.1`.\n\nEach of the 24 new charts will have its id (1-24) appended at:\n\n- its chart unique `id`, i.e. `bandwidth_port_1` to `bandwidth_port_24`.\n- its title, i.e. `Switch Bandwidth for port 1` to `Switch Bandwidth for port 24`.\n- its `oid` (for all dimensions), i.e. dimension in will be `1.3.6.1.2.1.2.2.1.10.1` to `1.3.6.1.2.1.2.2.1.10.24`.\n- its `priority` will be incremented for each chart so that the charts will appear on the dashboard in this order.\n\n\n```yaml\njobs:\n - name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port\"\n title: \"Switch Bandwidth for port\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n multiply_range: [1, 24]\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16\"\n multiplier: -8\n divisor: 1000\n\n```\n##### Multiple devices with a common configuration\n\nYAML supports [anchors](https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases). \nThe `&` defines and names an anchor, and the `*` uses it. `<<: *anchor` means, inject the anchor, then extend. We can use anchors to share the common configuration for multiple devices.\n\nThe following example:\n\n- adds an `anchor` to the first job.\n- injects (copies) the first job configuration to the second and updates `name` and `hostname` parameters.\n- injects (copies) the first job configuration to the third and updates `name` and `hostname` parameters.\n\n\n```yaml\njobs:\n - &anchor\n name: switch\n update_every: 10\n hostname: \"192.0.2.1\"\n community: public\n options:\n version: 2\n charts:\n - id: \"bandwidth_port1\"\n title: \"Switch Bandwidth for port 1\"\n units: \"kilobits/s\"\n type: \"area\"\n family: \"ports\"\n dimensions:\n - name: \"in\"\n oid: \"1.3.6.1.2.1.2.2.1.10.1\"\n algorithm: \"incremental\"\n multiplier: 8\n divisor: 1000\n - name: \"out\"\n oid: \"1.3.6.1.2.1.2.2.1.16.1\"\n multiplier: -8\n divisor: 1000\n - <<: *anchor\n name: switch2\n hostname: \"192.0.2.2\"\n - <<: *anchor\n name: switch3\n hostname: \"192.0.2.3\"\n\n```\n",
16030
"troubleshooting": "## Troubleshooting\n\n### Debug Mode\n\nTo troubleshoot issues with the `snmp` collector, run the `go.d.plugin` with the debug option enabled. The output\nshould give you clues as to why the collector isn't working.\n\n- Navigate to the `plugins.d` directory, usually at `/usr/libexec/netdata/plugins.d/`. If that's not the case on\n your system, open `netdata.conf` and look for the `plugins` setting under `[directories]`.\n\n ```bash\n cd /usr/libexec/netdata/plugins.d/\n ```\n\n- Switch to the `netdata` user.\n\n ```bash\n sudo -u netdata -s\n ```\n\n- Run the `go.d.plugin` to debug the collector:\n\n ```bash\n ./go.d.plugin -d -m snmp\n ```\n\n### Getting Logs\n\nIf you're encountering problems with the `snmp` collector, follow these steps to retrieve logs and identify potential issues:\n\n- **Run the command** specific to your system (systemd, non-systemd, or Docker container).\n- **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.\n\n#### System with systemd\n\nUse the following command to view logs generated since the last Netdata service restart:\n\n```bash\njournalctl _SYSTEMD_INVOCATION_ID=\"$(systemctl show --value --property=InvocationID netdata)\" --namespace=netdata --grep snmp\n```\n\n#### System without systemd\n\nLocate the collector log file, typically at `/var/log/netdata/collector.log`, and use `grep` to filter for collector's name:\n\n```bash\ngrep snmp /var/log/netdata/collector.log\n```\n\n**Note**: This method shows logs from all restarts. Focus on the **latest entries** for troubleshooting current issues.\n\n#### Docker Container\n\nIf your Netdata runs in a Docker container named \"netdata\" (replace if different), use this command:\n\n```bash\ndocker logs netdata 2>&1 | grep snmp\n```\n\n",
16031
"alerts": "## Alerts\n\nThere are no alerts configured by default for this integration.\n",
16032
- "metrics": "## Metrics\n\nThe metrics that will be collected are defined in the configuration file.\n",
16032
+ "metrics": "## Metrics\n\nMetrics grouped by *scope*.\n\nThe scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.\n\nThe metrics that will be collected are defined in the configuration file.\n\n### Per snmp device\n\nThese metrics refer to the SNMP device.\n\nLabels:\n\n| Label | Description |\n|:-----------|:----------------|\n| sysName | SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5)). |\n\nMetrics:\n\n| Metric | Dimensions | Unit |\n|:------|:----------|:----|\n| snmp.device_uptime | uptime | seconds |\n\n### Per network interface\n\nNetwork interfaces of the SNMP device being monitored. These metrics refer to each interface.\n\nLabels:\n\n| Label | Description |\n|:-----------|:----------------|\n| sysName | SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5)). |\n| ifDescr | Network interface description (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.2)). |\n| ifName | Network interface name (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.31.1.1.1.1)). |\n| ifType | Network interface type (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.3)). |\n\nMetrics:\n\n| Metric | Dimensions | Unit |\n|:------|:----------|:----|\n| snmp.device_net_interface_traffic | received, sent | kilobits/s |\n| snmp.device_net_interface_unicast | received, sent | packets/s |\n| snmp.device_net_interface_multicast | received, sent | packets/s |\n| snmp.device_net_interface_broadcast | received, sent | packets/s |\n| snmp.device_net_interface_errors | inbound, outbound | errors/s |\n| snmp.device_net_interface_discards | inbound, outbound | discards/s |\n| snmp.device_net_interface_admin_status | up, down, testing | status |\n| snmp.device_net_interface_oper_status | up, down, testing, unknown, dormant, not_present, lower_layer_down | status |\n\n",
16033
"integration_type": "collector",
16034
"id": "go.d.plugin-snmp-SNMP_devices",
16035
"edit_link": "https://github.com/netdata/netdata/blob/master/src/go/collectors/go.d.plugin/modules/snmp/metadata.yaml",
src/go/collectors/go.d.plugin/modules/snmp/integrations/snmp_devices.md
+122
-65
@@ -21,22 +21,22 @@ Module: snmp
21
22
## Overview
23
24
-This collector monitors any SNMP devices and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.
24
+This SNMP collector discovers and gathers statistics for network interfaces on SNMP-enabled devices:
25
26
-It supports:
26
+- Traffic
27
+- Packets (unicast, multicast, broadcast)
28
+- Errors
29
+- Discards
30
+- Administrative and operational status
31
28
-- all SNMP versions: SNMPv1, SNMPv2c and SNMPv3.
29
-- any number of SNMP devices.
30
-- each SNMP device can be used to collect data for any number of charts.
31
-- each chart may have any number of dimensions.
32
-- each SNMP device may have a different update frequency.
33
-- each SNMP device will accept one or more batches to report values (you can set `max_request_size` per SNMP server, to control the size of batches).
32
+Additionally, it collects overall device uptime.
33
35
-Keep in mind that many SNMP switches and routers are very slow. They may not be able to report values per second.
36
-`go.d.plugin` reports the time it took for the SNMP device to respond when executed in the debug mode.
34
+It is compatible with all SNMP versions (v1, v2c, and v3) and uses the [gosnmp](https://github.com/gosnmp/gosnmp) package.
35
38
-Also, if many SNMP clients are used on the same SNMP device at the same time, values may be skipped.
39
-This is a problem of the SNMP device, not this collector. In this case, consider reducing the frequency of data collection (increasing `update_every`).
36
+**For advanced users**:
37
+
38
+- You can manually specify custom OIDs (Object Identifiers) to retrieve specific data points beyond the default metrics.
39
+- However, defining custom charts with dimensions for these OIDs requires manual configuration.
40
41
42
@@ -58,39 +58,77 @@ The default configuration for this integration does not impose any limits on dat
58
59
#### Performance Impact
60
61
-The default configuration for this integration is not expected to impose a significant performance impact on the system.
61
+**Performance Considerations**:
62
+
63
+- **Device limitations**: Many SNMP switches and routers have limited processing power. They might not be able to report data as frequently as desired. You can monitor response times using go.d.plugin in debug mode to identify potential bottlenecks.
64
+
65
+- **Concurrent access**: If multiple collectors or tools access the same SNMP device simultaneously, data points might be skipped. This is a limitation of the device itself, not this collector. To mitigate this, consider increasing the collection interval (update_every) to reduce the frequency of requests.
66
+
67
68
69
## Metrics
70
71
+Metrics grouped by *scope*.
72
+
73
+The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.
74
+
75
The metrics that will be collected are defined in the configuration file.
76
77
+### Per snmp device
78
69
-## Alerts
79
+These metrics refer to the SNMP device.
80
71
-There are no alerts configured by default for this integration.
81
+Labels:
82
83
+| Label | Description |
84
+|:-----------|:----------------|
85
+| sysName | SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5)). |
86
74
-## Setup
87
+Metrics:
88
76
-### Prerequisites
89
+| Metric | Dimensions | Unit |
90
+|:------|:----------|:----|
91
+| snmp.device_uptime | uptime | seconds |
92
78
-#### Find OIDs
93
+### Per network interface
94
80
-Use `snmpwalk`, like this:
95
+Network interfaces of the SNMP device being monitored. These metrics refer to each interface.
96
82
-```sh
83
-snmpwalk -t 20 -O fn -v 2c -c public 192.0.2.1
84
-```
97
+Labels:
98
+
99
+| Label | Description |
100
+|:-----------|:----------------|
101
+| sysName | SNMP device's system name (OID: [1.3.6.1.2.1.1.5](https://oidref.com/1.3.6.1.2.1.1.5)). |
102
+| ifDescr | Network interface description (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.2)). |
103
+| ifName | Network interface name (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.31.1.1.1.1)). |
104
+| ifType | Network interface type (OID: [1.3.6.1.2.1.2.2.1.2](https://cric.grenoble.cnrs.fr/Administrateurs/Outils/MIBS/?oid=1.3.6.1.2.1.2.2.1.3)). |
105
+
106
+Metrics:
107
86
-- `-t 20` is the timeout in seconds.
87
-- `-O fn` will display full OIDs in numeric format.
88
-- `-v 2c` is the SNMP version.
89
-- `-c public` is the SNMP community.
90
-- `192.0.2.1` is the SNMP device.
108
+| Metric | Dimensions | Unit |
109
+|:------|:----------|:----|
110
+| snmp.device_net_interface_traffic | received, sent | kilobits/s |
111
+| snmp.device_net_interface_unicast | received, sent | packets/s |
112
+| snmp.device_net_interface_multicast | received, sent | packets/s |
113
+| snmp.device_net_interface_broadcast | received, sent | packets/s |
114
+| snmp.device_net_interface_errors | inbound, outbound | errors/s |
115
+| snmp.device_net_interface_discards | inbound, outbound | discards/s |
116
+| snmp.device_net_interface_admin_status | up, down, testing | status |
117
+| snmp.device_net_interface_oper_status | up, down, testing, unknown, dormant, not_present, lower_layer_down | status |
118
119
120
121
+## Alerts
122
+
123
+There are no alerts configured by default for this integration.
124
+
125
+
126
+## Setup
127
+
128
+### Prerequisites
129
+
130
+No action required.
131
+
132
### Configuration
133
134
#### File
@@ -114,15 +152,16 @@ The following options can be defined globally: update_every, autodetection_retry
152
153
| Name | Description | Default | Required |
154
|:----|:-----------|:-------|:--------:|
117
-| update_every | Data collection frequency. | 1 | no |
155
+| update_every | Data collection frequency. | 10 | no |
156
| autodetection_retry | Recheck interval in seconds. Zero means no recheck will be scheduled. | 0 | no |
119
-| hostname | Target ipv4 address. | 127.0.0.1 | yes |
157
+| hostname | Target ipv4 address. | | yes |
158
| community | SNMPv1/2 community string. | public | no |
159
| options.version | SNMP version. Available versions: 1, 2, 3. | 2 | no |
160
| options.port | Target port. | 161 | no |
161
| options.retries | Retries to attempt. | 1 | no |
124
-| options.timeout | SNMP request/response timeout. | 10 | no |
125
-| options.max_request_size | Maximum number of OIDs allowed in one one SNMP request. | 60 | no |
162
+| options.timeout | SNMP request/response timeout. | 5 | no |
163
+| options.max_repetitions | Controls how many SNMP variables to retrieve in a single GETBULK request. | 25 | no |
164
+| options.max_request_size | Maximum number of OIDs allowed in a single GET request. | 60 | no |
165
| user.name | SNMPv3 user name. | | no |
166
| user.name | Security level of SNMPv3 messages. | | no |
167
| user.auth_proto | Security level of SNMPv3 messages. | | no |
@@ -198,10 +237,58 @@ In this example:
237
- the SNMP version is `2`.
238
- the SNMP community is `public`.
239
- we will update the values every 10 seconds.
201
-- we define 2 charts `bandwidth_port1` and `bandwidth_port2`, each having 2 dimensions: `in` and `out`.
240
203
-> **SNMPv1**: just set `options.version` to 1.
204
-> **Note**: the algorithm chosen is `incremental`, because the collected values show the total number of bytes transferred, which we need to transform into kbps. To chart gauges (e.g. temperature), use `absolute` instead.
241
+
242
+<details open><summary>Config</summary>
243
+
244
+```yaml
245
+jobs:
246
+ - name: switch
247
+ update_every: 10
248
+ hostname: 192.0.2.1
249
+ community: public
250
+ options:
251
+ version: 2
252
+
253
+```
254
+</details>
255
+
256
+##### SNMPv3
257
+
258
+To use SNMPv3:
259
+
260
+- use `user` instead of `community`.
261
+- set `options.version` to 3.
262
+
263
+
264
+<details open><summary>Config</summary>
265
+
266
+```yaml
267
+jobs:
268
+ - name: switch
269
+ update_every: 10
270
+ hostname: 192.0.2.1
271
+ options:
272
+ version: 3
273
+ user:
274
+ name: username
275
+ level: authPriv
276
+ auth_proto: sha256
277
+ auth_key: auth_protocol_passphrase
278
+ priv_proto: aes256
279
+ priv_key: priv_protocol_passphrase
280
+
281
+```
282
+</details>
283
+
284
+##### Custom OIDs
285
+
286
+In this example:
287
+
288
+- the SNMP device is `192.0.2.1`.
289
+- the SNMP version is `2`.
290
+- the SNMP community is `public`.
291
+- we will update the values every 10 seconds.
292
293
294
<details open><summary>Config</summary>
@@ -249,37 +336,7 @@ jobs:
336
```
337
</details>
338
252
-##### SNMPv3
253
-
254
-To use SNMPv3:
255
-
256
-- use `user` instead of `community`.
257
-- set `options.version` to 3.
258
-
259
-The rest of the configuration is the same as in the SNMPv1/2 example.
260
-
261
-
262
-<details open><summary>Config</summary>
263
-
264
-```yaml
265
-jobs:
266
- - name: switch
267
- update_every: 10
268
- hostname: 192.0.2.1
269
- options:
270
- version: 3
271
- user:
272
- name: username
273
- level: authPriv
274
- auth_proto: sha256
275
- auth_key: auth_protocol_passphrase
276
- priv_proto: aes256
277
- priv_key: priv_protocol_passphrase
278
-
279
-```
280
-</details>
281
-
282
-##### Multiply range
339
+##### Custom OIDs with multiply range
340
341
If you need to define many charts using incremental OIDs, you can use the `charts.multiply_range` option.
342