Debug ACC check execution and increase check log level - Support and Troubleshooting

Debug ACC check execution and increase check log level .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 h3 { font-family: 'Lato', sans-serif; font-size: 12pt; font-weight: 900; color: #032D42; border-bottom: 2px solid #e8fce4; padding-bottom: 2px; margin-top: 24px; 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 .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 code { background: #e6f0f5; color: #032D42; border: 1px solid #b8cfd8; padding: 1px 5px; border-radius: 3px; font-family: 'Courier New', Courier, monospace; font-size: 11px; } .kb-wrapper table { width: 100%; border-collapse: collapse; margin: 0 0 16px; font-family: 'Lato', sans-serif; font-size: 12pt; } .kb-wrapper table th { background: #032D42; color: #ffffff; padding: 8px 12px; text-align: left; font-weight: 900; font-family: 'Lato', sans-serif; } .kb-wrapper table td { padding: 8px 12px; border-bottom: 1px solid #e0e0e0; vertical-align: top; } .kb-wrapper table tr:nth-child(even) td { background: #e8fce4; } .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; }

Troubleshoot Agent Client Collector (ACC) check execution issues by increasing the check log level and using alternative debugging methods. When a check produces unexpected results—such as a timeout, incomplete data, or a fatal exception—the default logs may not provide enough detail.

Agent log level and check log level Increasing the agent log level to debug improves logging for the following agent functions:

Asset Management Check Scheduling Agent-to-MID Server and ICS connection System Resource Monitoring Keep-Alive Agent debug logging does not affect the logs written by the check itself. Checks have a separate log level that must be configured independently. To get enhanced logging from a check, launch the check with an increased log level.

Note: The check must be configured to support enhanced logging. Most default ServiceNow-published checks contain enhanced logging options. Custom checks can use the logger by calling it in the custom Ruby script. Increase the check log level Control the check log level using parameters in the Command field, added either directly or as a parameter—for example:

--log_level=DEBUG Before increasing the log level on an existing check, consider the following:

Enhanced logging may break the payload structure and prevent successful processing. Enhanced logging fills the agent log more rapidly. Changing the log level may count as an update to the check, causing future skipped updates. Enhanced logging is often not needed for healthy checks. Avoid changing the log level on existing check definitions or check instances, as this can cause check run failures on agents that are not currently experiencing issues. Instead, create a test copy of the check and change the log level on the copy. The test copy can then be run directly or assigned to a test policy to control which agents run it.

For instructions on creating a test copy, see Create a test copy of an ACC check definition for debug logging .

Also consider running the test against both a functioning agent and the agent where the check fails. This comparison can help identify whether the issue is agent-specific.

Check logger reference The following shows how the logger is defined in the endpoint_discovery.rb check:

$logger = Logger.new(STDOUT) $logger. Level = options.log_level.nil? ? 'FATAL' : options.log_level Once the logger is defined, call it using the following syntax:

$logger.debug 'example Debug message' $logger.warn 'example Warning' The default log level for any check is defined in the Ruby script within the check definition. In the endpoint_discovery.rb script, the default log level is FATAL unless a different level is set in the check definition or check instance.

Use OSQuery test checks for targeted debugging Running a full check in debug log level is not always necessary. When the default logs clearly explain the issue, or when a specific section of the check payload—such as running_processes—returns empty results, use a TestCheck OSQuery check for targeted debugging.

The instance includes TestCheck OSQuery checks with names starting with TestCheck , for example, TestCheck - OSQuery [Windows] . Instructions for using these checks are in each check's description.

To run a targeted query:

Use one parameter at a time by setting the active flag on check parameter definitions. Add new check parameter definitions if needed. Common query examples:

Query Purpose SELECT * FROM processes Check process details. Highlights missing Debug Programs permissions when Parameters details are absent from most found processes. SELECT * FROM UserAssist Check last_used details for software installations. Highlights missing Windows registry permissions needed to read the UserAssist key. SELECT * FROM system_info Check system and hardware information. Use when hardware details are missing from a discovery check. Considerations for background checks Checks marked as background checks—such as many of the SAM background checks—are not designed to report output to the instance. The Test Check UI action is not available on the form for background checks, which makes them difficult to test.

When testing a background check, create a test copy of the check with an enhanced log level. Keep the following in mind:

If the test copy is not marked as a background check, the Test Check option is available but does not accurately emulate the original check run method. Add the test copy to a test policy and extract the agent logs directly. Related Links Create a test copy of an ACC check definition for debug logging