Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

expand upon example of using an index as a metric_tag #12438

Merged
merged 7 commits into from
Jul 12, 2022
66 changes: 40 additions & 26 deletions docs/developer/tutorials/snmp/profile-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ exampleColumn2 OBJECT-TYPE
-- ...
```

In profiles, tables can be specified as entries containing the `MIB`, `table` and `symbols` fields:
In profiles, tables can be specified as entries containing the `MIB`, `table` and `symbols` fields. The syntax for the value contained in each row is typically `<TABLE_OID>.1.<COLUMN_ID>.<INDEX>`:

```yaml
metrics:
Expand All @@ -166,7 +166,7 @@ metrics:
symbols:
# List of symbols ('columns') to retrieve.
# Same format as for a single OID.
# Each row in the table will emit these metrics.
# The value from each row (index) in the table will be collected `<TABLE_OID>.1.<COLUMN_ID>.<INDEX>`
- OID: 1.3.6.1.4.1.10.1.1
name: exampleColumn1
- OID: 1.3.6.1.4.1.10.1.2
Expand Down Expand Up @@ -278,36 +278,50 @@ External table indexes must be a subset of the indexes of the current table, or

##### Using an index

Important: "_index_" refers to one digit of the index part of the row OID. Example, if the column OID is `1.2.3.1.2` and the row OID is `1.2.3.1.2.7.8.9`, the full index is `7.8.9`. In this example, when using `index: 1`, we will refer to `7`, `index: 2` will refer to `8`, and so on.
Important: "_index_" refers to one digit of the index part of the row OID. For example, if the column OID is `1.2.3.1.2` and the row OID is `1.2.3.1.2.7.8.9`, the full index is `7.8.9`. In this example, `index: 1` refers to `7` and `index: 2` refers to `8`, and so on.

Here is specific example of an OID with multiple positions in the index ([OID ref](http://oidref.com/1.3.6.1.4.1.9.9.147.1.2.2.2.1)):

```
cfwConnectionStatEntry OBJECT-TYPE
SYNTAX CfwConnectionStatEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION
"An entry in the table, containing information about a
firewall statistic."
INDEX { cfwConnectionStatService, cfwConnectionStatType }
::= { cfwConnectionStatTable 1 }
```

The index in the case is a combination of `cfwConnectionStatService` and `cfwConnectionStatType`. Inspecting the `OBJECT-TYPE` of `cfwConnectionStatService` reveals the `SYNTAX` as `Services` ([OID ref](http://oidref.com/1.3.6.1.4.1.9.9.147.1.2.2.2.1.1)):

```
cfwConnectionStatService OBJECT-TYPE
SYNTAX Services
MAX-ACCESS not-accessible
STATUS current
DESCRIPTION
"The identification of the type of connection providing
statistics."
::= { cfwConnectionStatEntry 1 }
```
For example, when we fetch the value of `cfwConnectionStatValue`, the OID with the index is like `1.3.6.1.4.1.9.9.147.1.2.2.2.1.5.20.2` = `4087850099`, here the indexes are 20.2 (`1.3.6.1.4.1.9.9.147.1.2.2.2.1.5.<service type>.<stat type>`). Here is how we would specify this configuration in the yaml (as seen in the [corresponding profile](https://github.com/DataDog/integrations-core/blob/3a7b1d1877b7a0dfcd16e2ff856e636c8717ef5b/snmp/datadog_checks/snmp/data/profiles/_cisco-asa.yaml#L7-L18) packaged with the agent):

```yaml
metrics:
- MIB: CISCO-PROCESS-MIB
- MIB: CISCO-FIREWALL-MIB
table:
OID: 1.3.6.1.4.1.9.9.109.1.1.1
name: cpmCPUTotalTable
OID: 1.3.6.1.4.1.9.9.147.1.2.2.2
name: cfwConnectionStatTable
symbols:
- OID: 1.3.6.1.4.1.9.9.109.1.1.1.1.12
name: cpmCPUMemoryUsed
- OID: 1.3.6.1.4.1.9.9.147.1.2.2.2.1.5
name: cfwConnectionStatValue
metric_tags:
# This tagging method is more complex, so let's walk through an example...
#
# In CISCO-PROCESS-MIB, we can see that entries in the `cpmCPUTotalTable` are indexed by `cpmCPUTotalIndex`,
# which corresponds to some sort of CPU position for each row in the table:
#
# cpmCPUTotalEntry OBJECT-TYPE
# -- ...
# INDEX { cpmCPUTotalIndex } # <-- See?
#
# We want to tag metrics in this table by this CPU position.
#
# To do this, we look up the position of this OID in `INDEX`. Here we see it's in 1st position.
# So we can reference it here using `index: 1`.
# (If there were two OIDs in `INDEX`, and we wanted to use the one in 2nd position, then we would have used `index: 2`.)
#
# NOTE: currently only indexes that refer to a column in the same table are supported.
- tag: cpu
index: 1
- index: 1 // capture first index digit
tag: service_type
- index: 2 // capture second index digit
tag: stat_type
```

##### Mapping index to tag string value
Expand Down