diff --git a/plugins/inputs/snmp/CONFIG-EXAMPLES.md b/plugins/inputs/snmp/CONFIG-EXAMPLES.md new file mode 100644 index 000000000..a0a52eeb3 --- /dev/null +++ b/plugins/inputs/snmp/CONFIG-EXAMPLES.md @@ -0,0 +1,65 @@ +Here are a few configuration examples for different use cases. + +### Switch/router interface metrics + +This setup will collect data on all interfaces from three different tables, `IF-MIB::ifTable`, `IF-MIB::ifXTable` and `EtherLike-MIB::dot3StatsTable`. It will also add the name from `IF-MIB::ifDescr` and use that as a tag. Depending on your needs and preferences you can easily use `IF-MIB::ifName` or `IF-MIB::ifAlias` instead or in addition. The values of these are typically: + + IF-MIB::ifName = Gi0/0/0 + IF-MIB::ifDescr = GigabitEthernet0/0/0 + IF-MIB::ifAlias = ### LAN ### + +This configuration also collects the hostname from the device (`RFC1213-MIB::sysName.0`) and adds as a tag. So each metric will both have the configured host/IP as `agent_host` as well as the device self-reported hostname as `hostname` and the name of the host that has collected these metrics as `host`. + +Here is the configuration that you add to your `telegraf.conf`: + +``` +[[inputs.snmp]] + agents = [ "host.example.com" ] + version = 2 + community = "public" + + [[inputs.snmp.field]] + name = "hostname" + oid = "RFC1213-MIB::sysName.0" + is_tag = true + + [[inputs.snmp.field]] + name = "uptime" + oid = "DISMAN-EXPRESSION-MIB::sysUpTimeInstance" + + # IF-MIB::ifTable contains counters on input and output traffic as well as errors and discards. + [[inputs.snmp.table]] + name = "interface" + inherit_tags = [ "hostname" ] + oid = "IF-MIB::ifTable" + + # Interface tag - used to identify interface in metrics database + [[inputs.snmp.table.field]] + name = "ifDescr" + oid = "IF-MIB::ifDescr" + is_tag = true + + # IF-MIB::ifXTable contains newer High Capacity (HC) counters that do not overflow as fast for a few of the ifTable counters + [[inputs.snmp.table]] + name = "interface" + inherit_tags = [ "hostname" ] + oid = "IF-MIB::ifXTable" + + # Interface tag - used to identify interface in metrics database + [[inputs.snmp.table.field]] + name = "ifDescr" + oid = "IF-MIB::ifDescr" + is_tag = true + + # EtherLike-MIB::dot3StatsTable contains detailed ethernet-level information about what kind of errors have been logged on an interface (such as FCS error, frame too long, etc) + [[inputs.snmp.table]] + name = "interface" + inherit_tags = [ "hostname" ] + oid = "EtherLike-MIB::dot3StatsTable" + + # Interface tag - used to identify interface in metrics database + [[inputs.snmp.table.field]] + name = "ifDescr" + oid = "IF-MIB::ifDescr" + is_tag = true +``` diff --git a/plugins/inputs/snmp/README.md b/plugins/inputs/snmp/README.md index f8dbc7a31..473f2a52b 100644 --- a/plugins/inputs/snmp/README.md +++ b/plugins/inputs/snmp/README.md @@ -4,6 +4,8 @@ The SNMP input plugin gathers metrics from SNMP agents. ## Configuration: +See additional SNMP plugin configuration examples [here](./CONFIG-EXAMPLES.md). + ### Example: SNMP data: @@ -67,7 +69,7 @@ Resulting output: #### Configuration via MIB: -This example uses the SNMP data above, but is configured via the MIB. +This example uses the SNMP data above, but is configured via the MIB. The example MIB file can be found in the `testdata` directory. See the [MIB lookups](#mib-lookups) section for more information. Telegraf config: @@ -95,58 +97,58 @@ Resulting output: ### Config parameters -* `agents`: Default: `[]` +* `agents`: Default: `[]` List of SNMP agents to connect to in the form of `IP[:PORT]`. If `:PORT` is unspecified, it defaults to `161`. -* `version`: Default: `2` +* `version`: Default: `2` SNMP protocol version to use. -* `community`: Default: `"public"` +* `community`: Default: `"public"` SNMP community to use. -* `max_repetitions`: Default: `50` +* `max_repetitions`: Default: `50` Maximum number of iterations for repeating variables. -* `sec_name`: +* `sec_name`: Security name for authenticated SNMPv3 requests. -* `auth_protocol`: Values: `"MD5"`,`"SHA"`,`""`. Default: `""` +* `auth_protocol`: Values: `"MD5"`,`"SHA"`,`""`. Default: `""` Authentication protocol for authenticated SNMPv3 requests. -* `auth_password`: +* `auth_password`: Authentication password for authenticated SNMPv3 requests. -* `sec_level`: Values: `"noAuthNoPriv"`,`"authNoPriv"`,`"authPriv"`. Default: `"noAuthNoPriv"` +* `sec_level`: Values: `"noAuthNoPriv"`,`"authNoPriv"`,`"authPriv"`. Default: `"noAuthNoPriv"` Security level used for SNMPv3 messages. -* `context_name`: +* `context_name`: Context name used for SNMPv3 requests. -* `priv_protocol`: Values: `"DES"`,`"AES"`,`""`. Default: `""` +* `priv_protocol`: Values: `"DES"`,`"AES"`,`""`. Default: `""` Privacy protocol used for encrypted SNMPv3 messages. -* `priv_password`: +* `priv_password`: Privacy password used for encrypted SNMPv3 messages. -* `name`: +* `name`: Output measurement name. #### Field parameters: -* `oid`: +* `oid`: OID to get. May be a numeric or textual OID. * `oid_index_suffix`: The OID sub-identifier to strip off so that the index can be matched against other fields in the table. -* `name`: +* `name`: Output field/tag name. If not specified, it defaults to the value of `oid`. If `oid` is numeric, an attempt to translate the numeric OID into a texual OID will be made. -* `is_tag`: +* `is_tag`: Output this field as a tag. -* `conversion`: Values: `"float(X)"`,`"float"`,`"int"`,`""`. Default: `""` +* `conversion`: Values: `"float(X)"`,`"float"`,`"int"`,`""`. Default: `""` Converts the value according to the given specification. - `float(X)`: Converts the input value into a float and divides by the Xth power of 10. Efficively just moves the decimal left X places. For example a value of `123` with `float(2)` will result in `1.23`. @@ -156,14 +158,14 @@ Converts the value according to the given specification. - `ipaddr`: Converts the value to an IP address. #### Table parameters: -* `oid`: +* `oid`: Automatically populates the table's fields using data from the MIB. -* `name`: +* `name`: Output measurement name. If not specified, it defaults to the value of `oid`. If `oid` is numeric, an attempt to translate the numeric OID into a texual OID will be made. -* `inherit_tags`: +* `inherit_tags`: Which tags to inherit from the top-level config and to use in the output of this table's measurement. ### MIB lookups