[metricbeat] [system] add NTP metricset

[tommyers-elastic]

Proposed commit message

Add new Network Time Protocol (NTP) metricset to the system integration.

This is a simple wrapper around an SNTP client which allows monitoring of system clock offset compared to the configured NTP server.

Example test configuration:

metricbeat.modules:
  - module: system
    metricsets: 
     - ntp
    ntp:
      servers: ["0.pool.ntp.org", "1.pool.ntp.org", "2.pool.ntp.org", "3.pool.ntp.org"]
      timeout: 2s
      version: 4

Checklist

• My code follows the style guidelines of this project
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have made corresponding change to the default configuration files
• I have added tests that prove my fix is effective or that my feature works
• I have added an entry in CHANGELOG.next.asciidoc or CHANGELOG-developer.next.asciidoc.

[github-actions]

🤖 GitHub comments

Expand to view the GitHub comments

Just comment with:

• run docs-build : Re-trigger the docs validation. (use unformatted text in the comment!)

[mergify]

This pull request does not have a backport label.
If this is a bug or security fix, could you label this PR @tommyers-elastic? 🙏.
For such, you'll need to label your PR with:

• The upcoming major version of the Elastic Stack
• The upcoming minor version of the Elastic Stack (if you're not pushing a breaking change)

To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-8./d is the label to automatically backport to the 8./d branch. /d is the digit
• backport-active-all is the label that automatically backports to all active branches.
• backport-active-8 is the label that automatically backports to all active minor branches for the 8 major.
• backport-active-9 is the label that automatically backports to all active minor branches for the 9 major.

[mykola-elastic]

Even though it is in "draft" and the checks are not yet fixed, it looks quite good to me

[mergify]

This pull request is now in conflicts. Could you fix it? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b system/ntp upstream/system/ntp
git merge upstream/main
git push upstream system/ntp

[elasticmachine]

Pinging @elastic/integrations (Team:Integrations)

[elasticmachine]

Pinging @elastic/elastic-agent-data-plane (Team:Elastic-Agent-Data-Plane)

[github-actions]

🔍 Preview links for changed docs

• docs/reference/metricbeat/metricbeat-metricset-system-ntp.md
• docs/reference/metricbeat/exported-fields-system.md
• docs/reference/metricbeat/metricbeat-module-system.md
• docs/reference/metricbeat/metricbeat-modules.md

[stefans-elastic]

lgtm

[AndersonQ]

I'm trying to test it but it does not work for me.
As you can see in my comments, it seems to me you're not setting the host correctly.

this is how I tested:

• build metricbeat: go build .
• run it go run . --strict.perms=false -e -c ./metricbeat-anderson.yml
• my confg:

path.home: /tmp/beats/home
metricbeat.modules:
  - module: system
    period: 1s
    metricsets:
      - ntp
    ntp.hosts: ["localhost", "pool.ntp.org"]

output.file:
  path: /tmp/beats/home
  filename: "output-metricbeat"

logging.level: debug
logging.metrics:
  level: debug

What I'm gerring:

{"log.level":"error","@timestamp":"2025-07-11T16:17:30.550+0200","log.logger":"system.ntp","log.origin":{"function":"github.com/elastic/beats/v7/metricbeat/mb/module.(*metricSetWrapper).handleFetchError","file.name":"module/wrapper.go","file.line":335},"message":"Error fetching data for metricset system.ntp: error querying NTP server : address string is empty","service.name":"metricbeat","ecs.version":"1.6.0"}
{"log.level":"error","@timestamp":"2025-07-11T16:17:31.551+0200","log.logger":"system.ntp","log.origin":{"function":"github.com/elastic/beats/v7/metricbeat/mb/module.(*metricSetWrapper).handleFetchError","file.name":"module/wrapper.go","file.line":335},"message":"Error fetching data for metricset system.ntp: error querying NTP server : address string is empty","service.name":"metricbeat","ecs.version":"1.6.0"}
{"log.level":"error","@timestamp":"2025-07-11T16:17:32.551+0200","log.logger":"system.ntp","log.origin":{"function":"github.com/elastic/beats/v7/metricbeat/mb/module.(*metricSetWrapper).handleFetchError","file.name":"module/wrapper.go","file.line":335},"message":"Error fetching data for metricset system.ntp: error querying NTP server : address string is empty","service.name":"metricbeat","ecs.version":"1.6.0"}
{"log.level":"error","@timestamp":"2025-07-11T16:17:33.551+0200","log.logger":"system.ntp","log.origin":{"function":"github.com/elastic/beats/v7/metricbeat/mb/module.(*metricSetWrapper).handleFetchError","file.name":"module/wrapper.go","file.line":335},"message":"Error fetching data for metricset system.ntp: error querying NTP server : address string is empty","service.name":"metricbeat","ecs.version":"1.6.0"}
{"log.level":"error","@timestamp":"2025-07-11T16:17:34.550+0200","log.logger":"system.ntp","log.origin":{"function":"github.com/elastic/beats/v7/metricbeat/mb/module.(*metricSetWrapper).handleFetchError","file.name":"module/wrapper.go","file.line":335},"message":"Error fetching data for metricset system.ntp: error querying NTP server : address string is empty","service.name":"metricbeat","ecs.version":"1.6.0"}
{"log.level":"error","@timestamp":"2025-07-11T16:17:35.551+0200","log.logger":"system.ntp","log.origin":{"function":"github.com/elastic/beats/v7/metricbeat/mb/module.(*metricSetWrapper).handleFetchError","file.name":"module/wrapper.go","file.line":335},"message":"Error fetching data for metricset system.ntp: error querying NTP server : address string is empty","service.name":"metricbeat","ecs.version":"1.6.0"}

Could you please add a the section "How to test this PR locally" to facilitate others testing it?

[mergify]

This pull request is now in conflicts. Could you fix it? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b system/ntp upstream/system/ntp
git merge upstream/main
git push upstream system/ntp

[tommyers-elastic]

@AndersonQ the hosts config should not be prefixed

metricbeat.modules:
  - module: system
    period: 1s
    metricsets: ["ntp"]
    hosts: ["0.pool.ntp.org", "1.pool.ntp.org"]

i'll update this - because i see now that if you configured multiple metricsets here it errors out (see output below if you also configure cpu). the NTP config needs to be namespaced.

Exiting: host parsing failed for system-cpu: hosts must be empty for system

[AndersonQ]

@AndersonQ the hosts config should not be prefixed

metricbeat.modules:
  - module: system
    period: 1s
    metricsets: ["ntp"]
    hosts: ["0.pool.ntp.org", "1.pool.ntp.org"]

i'll update this - because i see now that if you configured multiple metricsets here it errors out (see output below if you also configure cpu). the NTP config needs to be namespaced.

Exiting: host parsing failed for system-cpu: hosts must be empty for system

ok, let me know when it's ready for re-review

[tommyers-elastic]

@AndersonQ we should be good to go

[AndersonQ]

looks good now. If all tests pass, it's good

[colleenmcginnis]

Some small suggestions (and big, but not blocking, thoughts) below.

[colleenmcginnis]

Definition lists look good now!

[lalit-satapathy]

Code owner approvals.