Choose a Checkmk data source program only when replacing agent output

Bottom line: Decide replacement versus supplemental data collection before configuring a data source program; a program replaces regular output while special agents can supplement it.

Source fact: what the authority says

The Checkmk data-source-program guide executes a configured command in place of the ordinary host-agent connection and expects agent data on standard output. A data source program replaces regular agent output, whereas special agents can supplement that output. The guide permits one data source program per host and multiple special agents from Checkmk 2.4.0 onward. A nonzero program result discards its complete data output, sets Check_MK to CRIT using standard-error information and leaves the other services at their previous states.

What the source does not establish

This article selects replacement versus supplementary collection, not a transport-security or extension-compatibility guarantee. It does not treat a retained old service state as a fresh successful query or approve execution of an arbitrary collection command.

Applicability questions

• Should the new source replace ordinary agent data or supplement it?
• Which regular sections must remain available for the host?
• What installed Checkmk version and collection rules govern the choice?
• How will a failed retrieval be distinguished from fresh successful data?

DSE recommendation: controlled next steps

The following steps are DSE recommendations based on the cited source.

DSE recommends writing the intended relationship between the normal agent and the proposed integration before selecting a mechanism. Inventory the sections that must remain, those deliberately replaced and the additional observations sought. Have the monitoring owner approve that population instead of choosing a data source program merely because a command already exists.

For an alternative transport of the ordinary response, review the configured program and its permitted inputs as the replacement path. For supplemental API observations, assess the documented special-agent route against the installed version. Keep execution privileges, endpoint credentials and transport security in their separate approved design reviews.

Preserve the actual matching host rule and collection setting in the proposed test record. Ask the implementer to provide a harmless representative response and an explicit failure case. Keep secret values out of command transcripts, and avoid introducing a production integration as an exploratory executable without an owner.

Review failure handling with the responder before rollout. Identify which retrieval result and service state will be investigated when the program fails. Keep the age of retained observations visible; do not relabel an unchanged service display as a newly successful query or broaden privileges simply to hide an error.

Verification and evidence

Proposed verification: use a disposable monitored host with known harmless regular sections. Compare the approved replacement or supplemental arrangement with the written section inventory, retaining the actual collection configuration and retrieved response. Verify the normal path separately from the integration’s own data.

Exercise an authorized failure fixture and retain its exit category, sanitized diagnostic and actual service observations. Compare these with the previous successful sample without inventing a recovery result. Have the owner accept both data coverage and failure visibility before scheduling the real integration, and keep application correctness outside this collection-mechanism test.

Official references

• Checkmk — Data source programs — official product documentation; confirm the installed release and configuration.

Source review completed October 30, 2026. Recheck the official documentation and deployment-specific applicability before a production change.