Create a test copy of an ACC check definition for debug logging - Support and Troubleshooting

Create a test copy of an ACC check definition for debug logging .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } .kb-wrapper { font-family: 'Lato', sans-serif; font-size: 12pt; line-height: 1.7; color: #000000; max-width: 100%; } .kb-wrapper h2 { font-family: 'Lato', sans-serif; font-size: 14pt; font-weight: 900; color: #032D42; border-bottom: 2px solid #e8fce4; padding-bottom: 4px; margin-top: 28px; margin-bottom: 14px; } .kb-wrapper h3 { font-family: 'Lato', sans-serif; font-size: 12pt; font-weight: 900; color: #032D42; border-bottom: 2px solid #e8fce4; padding-bottom: 2px; margin-top: 20px; margin-bottom: 10px; } .kb-wrapper p { font-family: 'Lato', sans-serif; font-size: 12pt; margin: 0 0 12px; } .kb-wrapper ul { font-family: 'Lato', sans-serif; font-size: 12pt; padding-left: 24px; margin: 0 0 14px; } .kb-wrapper ul li { margin-bottom: 6px; } .kb-wrapper ol.steps { list-style: none; counter-reset: steps-counter; padding-left: 0; margin: 0 0 14px; } .kb-wrapper ol.steps > li { counter-increment: steps-counter; position: relative; padding-left: 42px; margin-bottom: 20px; min-height: 28px; } .kb-wrapper ol.steps > li::before { content: counter(steps-counter); position: absolute; left: 0; top: 2px; width: 26px; height: 26px; line-height: 26px; text-align: center; background-color: #032D42; color: #63DF4E; border-radius: 50%; font-weight: 900; font-size: 11px; font-family: 'Lato', sans-serif; } .kb-wrapper .callout-note { background: #e6f4ff; border-left: 4px solid #52B8FF; padding: 10px 14px; margin: 12px 0; border-radius: 0 4px 4px 0; font-family: 'Lato', sans-serif; font-size: 12pt; line-height: 1.6; } .kb-wrapper .callout-note strong { color: #032D42; } .kb-wrapper pre.code-block { background: #e6f0f5; color: #032D42; border: 1px solid #b8cfd8; padding: 10px 16px; border-radius: 4px; font-family: 'Courier New', Courier, monospace; font-size: 12px; overflow-x: auto; margin: 8px 0 16px; white-space: pre; } .kb-wrapper img { max-width: 100%; height: auto; margin: 12px 0 16px; display: block; } .kb-wrapper .related-links ul { list-style: disc; padding-left: 24px; margin: 0; } .kb-wrapper .related-links ul li { margin-bottom: 6px; } .kb-wrapper .related-links a { color: #032D42; font-family: 'Lato', sans-serif; font-size: 12pt; } Learn how to create a test copy of an Agent Client Collector (ACC) check definition with enhanced logging for debugging purposes. The default logs produced during check execution may not provide enough detail to debug a failure or partial data collection. Modifying existing check definitions directly can cause unintended consequences, such as skipped upgrades or unexpected changes to live policies.

Note: Not all checks support enhanced logging. Most ServiceNow-published checks in the Agent Client Collector Framework and Agent Client Collector for Visibility Content packages contain a configurable logger. Custom checks can use the same logging functionality. This process can also test changes to a check definition, such as different command arguments, options, and parameters.

Collect logs from the ACC log file, either directly from the host or using the UI actions on the agent form.

Create a copy of the check definition Go to Agent Client Collector > Configuration > Check Definitions [sn_agent_check_def]. Open the check definition you want to copy. In the form context menu, select Insert and Stay to create a copy. Label the copy as a test check. For example, add “TEST” to the name and update the description to indicate this is a debugging copy of the original check. Set the Check type to TestCheck to prevent results from being committed if the check runs through a policy. Verify that the Plugins and Configuration Files on the test copy match the original check. Note: All associated items should display a name. A sys_id in place of a name indicates a broken reference, which can cause check failure due to missing assets. Manually create any Check Parameter Definitions and Secure Check Parameter Definitions that were present on the original check. The Insert and Stay action does not copy these. Note: Not all checks require parameter definitions. Edit the check for debugging After creating the test copy, edit it to add debug logging. Change the log level using one of the following methods.

Option 1: Add the log level directly to the Command field Add the following string to the Command field:

--log_level=DEBUG Option 2: Add a check parameter definition To enable parameters inside the check, the check command must be configured to accept parameters. Add the following string to the Command field instead of directly defining the log level as done in option 1.

{ {.labels.params_log_level}} In this example, that would be:

sam_processor_without_osqueryd.rb { {.labels.params_log_level}} Create a check parameter definition with the name log_level and the default value DEBUG .

Note: Use Option 1 or Option 2, not both. Considerations for the Run check in Background option The Run check in Background option on a check definition controls whether the check runs in the background. When selected, the Test Check UI action is unavailable because background checks cannot send output to the MID Server.

Common examples include SAM background checks that populate marker files or local databases on a short interval, and the AzureMetrics check that collects metrics from Azure APIs.

When debugging a background check, the Test Check UI action is unavailable. Consider the following options for collecting results:

If the check needs to run only once, clear the Run check in Background option on the test copy and use Test Check . This changes the check behavior from the original, making it a less accurate test. If the check must continue running as a background check, configure a test policy containing the agents and the check definition. Alternatives Creating a test copy avoids skipped updates and prevents test options from being applied to live agents, but this is not the only way to debug or run a check with different options.

Create a test policy with a modified check instance Add debug options to the check instance when adding it to the policy. This approach is useful in the following scenarios:

Debugging on multiple agents at once, or investigating intermittent issues Debugging a background check that must continue to run as a background check The original check definition is not modified, so upgrades are still applied. A checkout and republish of the policy is required for every change. Check outputs are processed based on the Check Type definition.

Use the existing TestCheck OSQuery checks Use these for troubleshooting individual missing data items, such as running_processes. This option does not replace running a check with debug log level, but can quickly check individual sections of a discovery check after host-level changes, such as permission changes.

Related Links Debug ACC check execution on the agent and increase check log level