KVS Factor Stats Guide

View hourly pre-aggregated statistics for tKVS key factors — volume, recent trend, staleness, and sample data — in a single admin screen.

🖥️ Go to the KVS Factor Stats page →

📋 Overview

The KVS Factor Stats page displays pre-aggregated hourly statistics for tKVS key factors. It shows the volume of data recorded per factor, recent trend indicators, and staleness information — helping operators identify which factors are actively reporting and which may have stopped. The data comes from tKVSHourlyStat, a pre-aggregated hourly table, so the page loads quickly even for large tKVS datasets.

⚠️ This screen is admin-only. Access requires admin level uLevel >= 70.

🔍 Screen Layout

1. Top Header

• Page title/description: "KVS Factor Stats" (localized) with a description of what the page shows.
• Refresh button: immediately reloads statistics. The data is not cached (useCache: false) to ensure fresh results on every load.

2. Staleness Hint

A hint text below the button: "Rows highlighted when no new data for 24h+ (possible unnecessary/stale factor)."

3. Data Table

Each row represents one kFactor. Columns typically include:

Column	Description
Factor Name	kFactor identifier
Volume	Number of records in the aggregation window
Trend	Recent direction of the factor activity
Hours Since Last	Hours since the last data report (amber highlighted when ≥ 24h)
Sample	Sample data from the factor

• Amber highlight: Rows where hours_since_last >= 24 are highlighted in amber to flag potentially stale or unnecessary factors.
• Sorted: Typically by staleness (most stale first) or by volume.

🛠️ How to Use

1. Identify stale factors: Look for amber-highlighted rows where Hours Since Last is 24 or higher — these factors have stopped reporting.
2. Check factor health: A healthy factor should show recent trend data and Hours Since Last close to 0.
3. Review volume: Unusually high or low volumes may indicate issues with the reporting agent.
4. Click Refresh to reload with the latest data from tKVSHourlyStat.

💡 Notes

• No caching: The page intentionally uses useCache: false to always show current data. If page load is slow, it may indicate that the pKvsHourlyStatBuild aggregation is running synchronously on first access.
• Amber = 24h+ staleness: A factor with hours_since_last >= 24 may be legitimately inactive (e.g., a weekend-only process) or genuinely stale. Investigate the associated agent/script before marking it unnecessary.
• Pre-aggregated data: The source table tKVSHourlyStat is built by pKvsHourlyStatBuild. If the stats look wrong, check whether that SP is running on schedule.

API Reference

Command	Purpose	Backend SP
AdmKvsFactorStat	Fetch pre-aggregated kFactor hourly stats	pApiAdmKvsFactorStatbyAk

• Response is parsed via parseToTableData into headers + rows.
• RstVal = 200 means success; RstVal = 401 means auth/session issue.

Troubleshooting

Symptom	Cause	Resolution
Page loads very slowly	pKvsHourlyStatBuild running synchronously on first access after a long gap	Refresh again — subsequent loads use cached aggregation
All rows amber (24h+)	No factor is reporting	Check that tKVS ingestion agents are running
No data at all	SP may be failing or tKVSHourlyStat is empty	Check SP logs and tKVS source data
"Session expired" / 401	Auth token expired	Log in again
Stale rows even after refresh	The factor has genuinely stopped reporting	Investigate the associated agent/script; may indicate a dead worker

---

Version: 1.0 Last Updated: 2026-08-14 Source File: giipv3/public/help/kvs-stats.en.md