Create CONFIG-EXAMPLES.md with a switch interface example
Added a standard example for collecting interface metrics from switches or routers and tagging them properly. closes #1666
This commit is contained in:
Stian Øvrevåge
Cameron Sparr
parent
ca55c4a55d
commit
187a894fe9
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue