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.

Sign up for GitHub

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

SNMP exporter: Label targets block as deprecated #2274

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

SNMP exporter: Label targets block as deprecated #2274

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1ad906
SNMP exporter: Label targets block as deprecated
ptodev Dec 12, 2024
d4c6754
Put less emphasis on deprecated content
ptodev Dec 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 119 additions & 102 deletions docs/sources/reference/components/prometheus/prometheus.exporter.snmp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,25 +17,34 @@ The `prometheus.exporter.snmp` component embeds

## Usage

### Recommended usage

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to remove this and keep it just Usage to keep it consistent with the other topic layouts.

```alloy
prometheus.exporter.snmp "LABEL" {
config_file = SNMP_CONFIG_FILE_PATH

target "TARGET_NAME" {
address = TARGET_ADDRESS
}
targets = TARGET_LIST
}
```

or
### Deprecated usage
ptodev marked this conversation as resolved.
Show resolved Hide resolved

```alloy
prometheus.exporter.snmp "LABEL" {
config_file = SNMP_CONFIG_FILE_PATH
targets = TARGET_LIST

target "TARGET_NAME" {
address = TARGET_ADDRESS
}
}
```

Using the `target` block is deprecated because it is less flexible than the `targets` argument:
* 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.
ptodev marked this conversation as resolved.
Show resolved Hide resolved

[syntax-blocks]: ../../../../get-started/configuration-syntax/syntax#blocks

## Arguments

The following arguments can be used to configure the exporter's behavior.
Expand All @@ -50,7 +59,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`
Expand Down Expand Up @@ -127,102 +137,9 @@ debug information.
`prometheus.exporter.snmp` does not expose any component-specific
debug metrics.

## Example
## Examples using the targets argument (recommended)
ptodev marked this conversation as resolved.
Show resolved Hide resolved

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 = <PROMETHEUS_REMOTE_WRITE_URL>

basic_auth {
username = <USERNAME>
password = <PASSWORD>
}
}
}
```

Replace the following:
- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
- _`<USERNAME>`_: The username to use for authentication to the remote_write API.
- _`<PASSWORD>`_: 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" {
Expand Down Expand Up @@ -260,6 +177,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
Expand Down Expand Up @@ -300,6 +219,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" {
Expand Down Expand Up @@ -334,6 +255,102 @@ The YAML file in this example looks like this:
auth: public_v2
```

## Example using the target block (deprecated)
ptodev marked this conversation as resolved.
Show resolved Hide resolved

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 = <PROMETHEUS_REMOTE_WRITE_URL>

basic_auth {
username = <USERNAME>
password = <PASSWORD>
}
}
}
```

Replace the following:
- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus remote_write-compatible server to send metrics to.
- _`<USERNAME>`_: The username to use for authentication to the remote_write API.
- _`<PASSWORD>`_: The password to use for authentication to the remote_write API.


[scrape]: ../prometheus.scrape/
[file]: ../../local/local.file/
[disc]: ../../discovery/discovery.file/
Expand Down
Loading