[receiver/hostmetrics] Add system.network.bandwidth.limit metric

[emmayusufu]

Description

The network scraper exposes byte, packet, error, dropped, connection, and conntrack metrics, but nothing for link capacity. Consumers can derive byte rates from system.network.io but can't compute interface saturation without the NIC link speed.

This adds an optional, disabled-by-default system.network.bandwidth.limit gauge (unit By/s, attribute device). On Linux it reads the interface link speed from /sys/class/net/<device>/speed (honoring HOST_SYS) and converts Mbit/s to bytes/s. It's a no-op on other platforms, and interfaces that report -1 (virtual or down links) are skipped.

I scoped this to the bandwidth limit only. The utilization metric from the issue can follow once the limit lands, since it needs prev-sample delta tracking.

Link to tracking issue

Part of #49169

Testing

Added a unit test for the sysfs speed read (valid speed, -1, unparseable, missing interface). Regenerated with mdatagen; go test ./... and GOOS=linux go vet ./... pass.

Documentation

Regenerated documentation.md via mdatagen and added a changelog entry.

[github-actions]

Welcome, contributor! Thank you for your contribution to opentelemetry-collector-contrib.

Important reminders:

• Read our Contributing Guidelines.
• Sign the CLA if you haven't already.
• First-time contributors should have at most one PR not marked as draft until their first PR is merged.
• If your change isn't one of our priority components, reviews may take more time.
• Give reviewers at least a few days before pinging them for feedback.
• If you need help or struggle to move your PR forward:
  • Ask questions regarding general setup, development process, or contributor etiquette in #opentelemetry-new-contributors.
  • Raise technical or Collector-specific questions in #otel-collector-dev or a Collector SIG meeting.

[thompson-tomo]

We should be using network.interface.name & network.io.direction attributes.

[emmayusufu]

Thanks for the review.

For the interface attribute, I used device to match the rest of this scraper. Every metric in the network scraper, and the wider hostmetrics receiver, uses device, and there's no network.interface.name or migration gate in the receiver today, so putting semconv attributes on just this metric would leave it inconsistent with system.network.io, system.network.packets, and the others. Moving to network.interface.name looks like a receiver-wide migration with a feature gate for backward compatibility, rather than something to start on a single new metric. I can switch this one if you'd rather, but I leaned toward consistency.

On network.io.direction: system.network.bandwidth.limit is the interface's link capacity, which isn't directional. The directional metrics (io, packets, errors) carry direction, but link speed is the same for receive and transmit on a full-duplex link, so adding it would just duplicate the value. I left it off for that reason. If you have a per-direction capacity in mind, let me know and I'll add it.

[thompson-tomo]

Actually the guidance in the developers docs is to use the semconv and that is what alot of other scrapers/receivers do.

In relation to limit, the use cases is as described in https://opentelemetry.io/docs/specs/semconv/general/naming/#instrument-naming which is the limit metric pairs with usage metric to give utilization.

[emmayusufu]

Fair enough, you're right. nfsscraper already uses network.io.direction and ciscoos uses network.interface.name, so I've switched this metric to both to match the semconv guidance. Since link bandwidth on a full-duplex interface applies per direction, I emit it for transmit and receive, which also lets it pair cleanly with system.network.io for utilization. Pushed the update.