ACC advanced metering: SAM software total usage data collection and configuration<!-- /*NS Branding Styles*/ --> .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:#000;max-width:100%} .kb-wrapper p{margin:0 0 12px 0} .kb-wrapper ul{margin:0 0 12px 0;padding-left:24px} .kb-wrapper li{margin-bottom:8px} .kb-wrapper h2{font-size:14pt;font-weight:900;border-bottom:2px solid #e8fce4;padding-bottom:4px;margin:28px 0 10px 0} .kb-wrapper h3{font-size:12pt;font-weight:900;border-bottom:2px solid #e8fce4;padding-bottom:4px;margin:20px 0 8px 0} .kb-wrapper .note{border-left:4px solid #52B8FF;background:#e6f4ff;padding:10px 14px;margin:14px 0} .kb-wrapper .warning{border-left:4px solid #e6a817;background:#fff4e0;padding:10px 14px;margin:14px 0} .kb-wrapper code{background:#e6f0f5;color:#032D42;border:1px solid #b8cfd8;padding:1px 4px;border-radius:3px;font-family:monospace;font-size:11pt} .kb-wrapper pre{background:#e6f0f5;color:#032D42;border:1px solid #b8cfd8;padding:12px 16px;overflow-x:auto;font-family:monospace;font-size:11pt;line-height:1.5;margin:10px 0 16px 0;border-radius:3px} .kb-wrapper ol.steps{list-style:none;padding:0;counter-reset:step-counter} .kb-wrapper ol.steps>li{counter-increment:step-counter;display:flex;align-items:flex-start;margin-bottom:16px;list-style:none} .kb-wrapper ol.steps>li::before{content:counter(step-counter);flex-shrink:0;width:28px;height:28px;border-radius:50%;background:#032D42;color:#63DF4E;font-weight:900;font-size:11pt;text-align:center;line-height:28px;display:block;margin-right:16px} .kb-wrapper ol.steps>li>div{flex:1} .kb-wrapper ol.sub-steps{list-style:lower-alpha;padding-left:24px;margin:10px 0 4px 0} .kb-wrapper table{width:100%;border-collapse:collapse;margin:14px 0;font-size:12pt} .kb-wrapper th{background:#032D42;color:#fff;padding:9px 12px;text-align:left;font-weight:700} .kb-wrapper td{padding:8px 12px;border-bottom:1px solid #ddd;vertical-align:top} .kb-wrapper tr:nth-child(even) td{background:#e8fce4} .kb-wrapper p.disclaimer{font-size:10pt;font-style:italic} Summary This article describes how the Agent Client Collector (ACC) SAM Advanced Metering feature collects process-level software usage data on managed endpoints and how that data is processed on the ServiceNow instance to support SAM Professional license reclamation. SAM Advanced Metering runs as part of the installed_software_with_sam_metering check. It collects per-user, per-process elapsed usage time for installed software and writes that data to a staging table. SAM Professional reclamation rules use this staging data to identify underused software licenses eligible for reclamation. The same check module also collects basic metering (last-used timestamps per software entry). Basic metering and SAM Advanced Metering produce separate data structures in the same check result. Plugin and dependency requirements The ACC Visibility Content plugin (com.sn_acc_vis_content) requires the following plugins to be active before it is activated: PluginRolecom.agent-nowACC lifecycle, MID Server setup, policy engine, and agent tablescom.snc.discovery.ip_basedIP-based Discovery platformcom.sn_cmdb_ci_classCI class definitions The SAM Professional plugin (com.snc.samp) must also be active for usage data to be written to the staging table. How SAM Advanced Metering works When the ACC agent runs the installed_software_with_sam_metering check, it collects process-level usage data and sends it to the ServiceNow instance as the sam_advanced payload. The instance then attempts to match each entry against installed software records and write usage data to a staging table. ACC Agent (on monitored endpoint) | +-- installed_software_with_sam_metering check | | | +-- osqueryd mode (default) | | Reads osqueryd.snapshots.log → builds marker.json accumulator | | | +-- Non-osqueryd mode | Reads agent SQLite database | +-- sam_advanced payload → ServiceNow instance (via MID Server) | +-- Lookup: samp_sw_product_process (process name → SAM product) +-- Lookup: cmdb_sam_sw_install (installed software on CI) +-- Check: samp_m2m_rule_product (reclamation rules) +-- Write: sn_acc_vis_content_sam_software_usage_staging Data collection modes SAM Advanced Metering operates in one of two modes. The mode determines how the agent collects process usage data on the endpoint. osqueryd mode (default) The osqueryd daemon runs continuously on the endpoint, loaded with the sam-metering.conf configuration pack. Every 300 seconds, the pack runs a snapshot SQL query against the processes table and writes results to osqueryd.snapshots.log. When the main check fires, the agent reads osqueryd.snapshots.log and builds an accumulator file (marker.json), keyed by username → process_name → pid-start_time. The file tracks cumulative elapsed time across check runs. The delta since the last accumulator is sent to the instance as the sam_advanced payload. Non-osqueryd mode Inactive by default. A background check runs every 480 seconds, reads usage metrics from the agent's local SQLite database, aggregates the data, and clears the source table. When the main check fires, it reads from the SQLite database instead of osqueryd.snapshots.log. Switching between modes The mode is controlled by the sn_acc_vis_content.enable_sam_collection_without_osqueryd system property: Property valueModePolicy active on instancefalse (default)osquerydSAM background policytrueNon-osquerydSAM background policy (Non OsqueryD) When you update this property, a business rule automatically activates or deactivates the appropriate policy. Do not manually activate the non-osqueryd policy without first setting the property — this property controls how the main check finds the agent's locally stored usage information. How collected data is processed on the instance When the check result reaches the instance, the sam_advanced payload is processed as follows. Each step is a silent skip if data is not found — the absence of records in the staging table is the only indicator of failure. Verify that the SAM Professional plugin (com.snc.samp) is active. If not active, processing stops and nothing is written.For each entry (user name, process name, elapsed time) in the payload: Look up the process name in the Process-to-Product Mappings [samp_sw_product_process] table. If no match is found, skip the entry.Look up the matched SAM product in the Software Installation [cmdb_sam_sw_install] table for the agent CI. If no installation record exists, skip the entry.Unless sn_acc_vis_content.disable_sam_reclamation_rules_for_licensable_softwares is set to true, check the Reclamation Rules [samp_m2m_rule_product] table. If no reclamation rule exists for the product, skip the entry.Write the entry to the Software Usage Staging [sn_acc_vis_content_sam_software_usage_staging] table. Setup requirements Verify the following before SAM Advanced Metering is expected to produce staging records. Instance com.agent-now plugin is activecom.snc.discovery.ip_based plugin is activecom.snc.samp (SAM Professional) plugin is activecom.sn_acc_vis_content plugin is active Policies SAM metering policies are active and assigned to the correct CI classes (cmdb_ci_computer)For osqueryd mode: osqueryd is installed on endpointsFor non-osqueryd mode: sn_acc_vis_content.enable_sam_collection_without_osqueryd is set to true Data Process-to-Product Mappings [samp_sw_product_process] table is populated with the process names for target softwareSoftware Installation [cmdb_sam_sw_install] records exist for the target CIsReclamation rules exist in the Reclamation Rules [samp_m2m_rule_product] table for target software products — or sn_acc_vis_content.disable_sam_reclamation_rules_for_licensable_softwares is set to true Agent allow-list requirements The following scripts must be present in the agent allow-list (check-allow-list.json) for the check to run: ScriptRequired argument patternsam_processor.rbNo argument pattern requiredsam_processor_without_osqueryd.rbNo argument pattern requiredendpoint_discovery.rbMust include --select=...installed_software_with_sam_metering... (regex-validated) Relevant system properties PropertyDefaultDescriptionsn_acc_vis_content.enable_sam_collection_without_osquerydfalseSwitches between osqueryd mode (false) and non-osqueryd mode (true). Updating this property triggers the business rule that activates or deactivates the appropriate SAM policy.sn_acc_vis_content.enable_license_key_discoveryfalseWhen set to true, also collects software license keys during the check.sn_acc_vis_content.disable_sam_reclamation_rules_for_licensable_softwaresfalseWhen set to true, writes staging data for all licensable software regardless of whether a reclamation rule exists for that product.sn_agent.config_publish.max_payload_size15000000Maximum payload size in bytes for configuration publish probes sent to agents.sn_agent.mid.agent_expiration_sec259200Agent cache lifetime in seconds (default: three days). Relevant tables TablePurposesn_acc_vis_content_sam_software_usage_stagingSAM Advanced Metering output — process usage per user per CIsamp_sw_product_processProcess name to SAM product mappings — must be populated for staging writes to occurcmdb_sam_sw_installSoftware Installation records — matched against CI during instance-side processingsamp_m2m_rule_productSAM reclamation rules — required for staging writes unless the property override is set Related links ACC-V: Trouble shooting guide for SAM Total Usage Metric Using push-based Discovery and SAM together ACC basic metering: data collection and last-used timestamp processing