diff --git a/docs/sources/reference/components/prometheus/prometheus.exporter.snmp.md b/docs/sources/reference/components/prometheus/prometheus.exporter.snmp.md index 664263dcad..984aac9790 100644 --- a/docs/sources/reference/components/prometheus/prometheus.exporter.snmp.md +++ b/docs/sources/reference/components/prometheus/prometheus.exporter.snmp.md @@ -17,18 +17,6 @@ The `prometheus.exporter.snmp` component embeds ## Usage -```alloy -prometheus.exporter.snmp "LABEL" { - config_file = SNMP_CONFIG_FILE_PATH - - target "TARGET_NAME" { - address = TARGET_ADDRESS - } -} -``` - -or - ```alloy prometheus.exporter.snmp "LABEL" { config_file = SNMP_CONFIG_FILE_PATH @@ -50,7 +38,8 @@ Omitted fields take their default values. The `config_file` argument points to a YAML file defining which snmp_exporter modules to use. Refer to [snmp_exporter](https://github.com/prometheus/snmp_exporter/tree/{{< param "SNMP_VERSION" >}}?tab=readme-ov-file#configuration) for details on how to generate a configuration file. -The `config` argument must be a YAML document as string defining which SNMP modules and auths to use. +The `config` argument is an alternative to the `config_file` argument. +It must be a YAML document as string defining which SNMP modules and auths to use. `config` is typically loaded by using the exports of another component. For example, - `local.file.LABEL.content` @@ -74,7 +63,7 @@ The following blocks are supported inside the definition of | Hierarchy | Name | Description | Required | | ---------- | -------------- | ----------------------------------------------------------- | -------- | -| target | [target][] | Configures an SNMP target. | no | +| target | [target][] | (Deprecated) Configures an SNMP target. | no | | walk_param | [walk_param][] | SNMP connection profiles to override default SNMP settings. | no | [target]: #target-block @@ -82,6 +71,18 @@ The following blocks are supported inside the definition of ### target block +{{< admonition type="warning" >}} + +Using the `target` block is deprecated because it is less flexible than the `targets` argument: +* The value of the `targets` argument could come from another component such as `local.file` or `discovery.file`. +* The name of the `target` block cannot contain certain characters, + because it has to comply with Alloy syntax restrictions for [block labels][syntax-blocks]. +* With the `targets` argument you can also pass in additional labels. + +[syntax-blocks]: ../../../../get-started/configuration-syntax/syntax#blocks + +{{< /admonition >}} + The `target` block defines an individual SNMP target. The `target` block may be specified multiple times to define multiple targets. The label of the block is required and will be used in the target's `job` label. @@ -94,6 +95,19 @@ The `target` block may be specified multiple times to define multiple targets. T | `snmp_context` | `string` | Override the `context_name` parameter in the SNMP configuration file. | `""` | no | | `labels` | `map(string)` | Map of labels to apply to all metrics captured from the target. | `""` | no | +{{< collapse title="Deprecated example using the target block" >}} + +```alloy +prometheus.exporter.snmp "LABEL" { + config_file = SNMP_CONFIG_FILE_PATH + + target "TARGET_NAME" { + address = TARGET_ADDRESS + } +} +``` + +{{< /collapse >}} ### walk_param block @@ -127,102 +141,9 @@ debug information. `prometheus.exporter.snmp` does not expose any component-specific debug metrics. -## Example +## Examples -This example uses a [`prometheus.scrape` component][scrape] to collect metrics -from `prometheus.exporter.snmp`: - -```alloy -prometheus.exporter.snmp "example" { - config_file = "snmp_modules.yml" - - target "network_switch_1" { - address = "192.168.1.2" - module = "if_mib" - walk_params = "public" - labels = { - "env" = "dev", - } - } - - target "network_router_2" { - address = "192.168.1.3" - module = "mikrotik" - walk_params = "private" - } - - walk_param "private" { - retries = "2" - } - - walk_param "public" { - retries = "2" - } -} - -// Configure a prometheus.scrape component to collect SNMP metrics. -prometheus.scrape "demo" { - targets = prometheus.exporter.snmp.example.targets - forward_to = [ /* ... */ ] -} -``` - -This example uses an embedded configuration (with secrets): - -```alloy -local.file "snmp_config" { - filename = "snmp_modules.yml" - is_secret = true -} - -prometheus.exporter.snmp "example" { - config = local.file.snmp_config.content - - target "network_switch_1" { - address = "192.168.1.2" - module = "if_mib" - walk_params = "public" - } - - target "network_router_2" { - address = "192.168.1.3" - module = "mikrotik" - walk_params = "private" - } - - walk_param "private" { - retries = "2" - } - - walk_param "public" { - retries = "2" - } -} - -// Configure a prometheus.scrape component to collect SNMP metrics. -prometheus.scrape "demo" { - targets = prometheus.exporter.snmp.example.targets - forward_to = [prometheus.remote_write.demo.receiver] -} - -prometheus.remote_write "demo" { - endpoint { - url = - - basic_auth { - username = - password = - } - } -} -``` - -Replace the following: -- _``_: The URL of the Prometheus remote_write-compatible server to send metrics to. -- _``_: The username to use for authentication to the remote_write API. -- _``_: The password to use for authentication to the remote_write API. - -This example uses the alternative way to pass targets: +### Basic usage ```alloy prometheus.exporter.snmp "example" { @@ -260,6 +181,8 @@ prometheus.scrape "demo" { } ``` +### Targets coming from local.file + This example uses the [`local.file` component][file] to read targets from a YAML file and send them to the `prometheus.exporter.snmp` component: ```alloy @@ -300,6 +223,8 @@ The YAML file in this example looks like this: auth: public_v2 ``` +### Targets coming from discovery.file + This example uses the [`discovery.file` component][disc] to send targets to the `prometheus.exporter.snmp` component: ```alloy discovery.file "example" { @@ -334,6 +259,110 @@ The YAML file in this example looks like this: auth: public_v2 ``` +### Deprecated example using the target block + +This example uses a [`prometheus.scrape` component][scrape] to collect metrics +from `prometheus.exporter.snmp`: + +{{< collapse title="Basic example" >}} + +```alloy +prometheus.exporter.snmp "example" { + config_file = "snmp_modules.yml" + + target "network_switch_1" { + address = "192.168.1.2" + module = "if_mib" + walk_params = "public" + labels = { + "env" = "dev", + } + } + + target "network_router_2" { + address = "192.168.1.3" + module = "mikrotik" + walk_params = "private" + } + + walk_param "private" { + retries = "2" + } + + walk_param "public" { + retries = "2" + } +} + +// Configure a prometheus.scrape component to collect SNMP metrics. +prometheus.scrape "demo" { + targets = prometheus.exporter.snmp.example.targets + forward_to = [ /* ... */ ] +} +``` + +{{< /collapse >}} + +This example retrieves the SNMP YAML file as a secret, so that it is not displayed in the UI and in logs: + +{{< collapse title="Basic example using local.file" >}} + +```alloy +local.file "snmp_config" { + filename = "snmp_modules.yml" + is_secret = true +} + +prometheus.exporter.snmp "example" { + config = local.file.snmp_config.content + + target "network_switch_1" { + address = "192.168.1.2" + module = "if_mib" + walk_params = "public" + } + + target "network_router_2" { + address = "192.168.1.3" + module = "mikrotik" + walk_params = "private" + } + + walk_param "private" { + retries = "2" + } + + walk_param "public" { + retries = "2" + } +} + +// Configure a prometheus.scrape component to collect SNMP metrics. +prometheus.scrape "demo" { + targets = prometheus.exporter.snmp.example.targets + forward_to = [prometheus.remote_write.demo.receiver] +} + +prometheus.remote_write "demo" { + endpoint { + url = + + basic_auth { + username = + password = + } + } +} +``` + +{{< /collapse >}} + +Replace the following: +- _``_: The URL of the Prometheus remote_write-compatible server to send metrics to. +- _``_: The username to use for authentication to the remote_write API. +- _``_: The password to use for authentication to the remote_write API. + + [scrape]: ../prometheus.scrape/ [file]: ../../local/local.file/ [disc]: ../../discovery/discovery.file/