Usage Analytics¶

Usage Analytics is an administrator dashboard that shows how Reports, Dashboards, Views, APIs, exports, and embedded content are used across AcuGIS Report Server.

It is an aggregated view of activity already captured by the Audit subsystem. It does not replace Auditing, and it does not introduce a second event log.

Application activity
        ↓
Audit events (source of truth)
        ↓
Usage Analytics aggregation APIs
        ↓
Administration → Usage Analytics

Open Administration → Usage Analytics (/admin/usage.php).

Required Edition¶

Usage Analytics requires feature usage_analytics and a platform administrator.

Runtime	Available
Open Source package	No. The routes are not compiled.
Professional package without a valid license	No. The denial uses Community Edition wording.
Licensed Professional	Yes

ACUGIS_EDITION does not grant this feature. Menu visibility is not sufficient. Every Usage Analytics API checks the feature and the administrator role.

Overview¶

The dashboard default period is Last 30 Days. KPI cards summarize:

KPI	Meaning
Report Executions	Report execute and export events
Dashboard Views	Meaningful Dashboard opens
View Opens	Meaningful saved View opens
Unique Users	Distinct users with usage activity (not admin-config noise)
Exports	Report export events
API Requests	Selective `/api/v1/*` request audits
Embedded Views	Content opens/views via embed channel
Failed Executions	Failed report execute/export events
Average Report Render Time	Average `duration_ms` for report execute/export

Where available, each card shows change versus the immediately preceding period of equal length. When the previous period had no data, the UI shows No previous data rather than a misleading percentage.

Date Ranges¶

Period	Notes
Today	From midnight UTC to now
Last 7 Days	Rolling window
Last 30 Days	Default
Last 90 Days	May approach retention limits
Custom Range	From / To dates; invalid ranges are rejected with a validation message

Changing the period refreshes KPIs, the activity chart, and loaded tables.

Filters¶

Use Filters to refine analytics by:

User (username)
Content type (report, dashboard, view)
Content ID
Folder ID
Activity type
Channel (embed or interactive)

Active filters appear as chips and can be cleared individually or all at once.

Activity Over Time¶

The chart uses server-side time buckets (hourly/daily/weekly/monthly depending on the selected window). Metric toggles control which series are displayed. Raw Audit rows are never sent to the browser for charting.

Content Usage¶

Most Used Content¶

Shows Reports, Dashboards, and Views ordered by usage, with unique users, last used time, average render time (where meaningful), and failure rate.

Deleted content keeps its historical Audit name but is not linked to a live page.

Least Used Content¶

Catalog-driven view for content with little or no usage. Modes include:

No usage in 30 days
No usage in 90 days
No usage in retained history

Important: Usage Analytics cannot claim lifetime Never used when Audit retention deletes older events. If retained history is insufficient for a requested window (for example, 180 days when retention is 90), the UI surfaces the backend’s history_insufficient message and labels rows as No usage in retained Audit history.

Content Drill-down¶

Click content for a detail view: totals, unique users, usage over time, render time (reports), failures, exports, and top users. Report-specific metrics are omitted for Dashboards/Views when not meaningful.

Report Performance¶

Identifies expensive or unreliable reports:

Executions
Average / P95 / slowest render time
Failures and failure rate
Last executed

Failures¶

Aggregated failures with latest sanitized error text. Use View in Audit to inspect individual events. Secrets are never shown.

User Activity¶

Per-user usage of reports, dashboards, views, exports, APIs, and embeds. SSO users appear as their normal mapped AcuGIS usernames. Deleted users remain visible via historical Audit identity.

Exports¶

Total exports, breakdown by format, most exported reports, and exporting users.

API Usage¶

Operational totals and a table of normalized routes (for example GET /api/v1/reports/{key}), failures, and average duration. This is not an API request log — use Auditing for event detail.

Admin Usage Analytics and Audit APIs are excluded from API usage counting to avoid self-referential noise.

Embedded Analytics¶

Token issuance counts and embedded consumption (views, report executions, dashboard views, failures), with optional breakdowns by content, origin, and issuer.

Never displayed:

emb_ embed tokens
jrs_ personal access tokens
session identifiers
Authorization headers

View in Audit¶

Tables and content detail provide View in Audit links into /admin/audit.php with period and filter parameters applied. Auditing remains the detailed event/history interface.

Audit vs Usage Analytics¶

	Auditing	Usage Analytics
Purpose	Individual security/admin/activity events	Aggregated operational usage
Audience	Investigate who did what	Understand what is used
Data	Raw `audit_log` rows	Aggregations over those rows
Retention	Controls history window	Bound by the same retention

Audit Retention¶

Usage Analytics history is limited by Audit retention:

Setting	Default
`JRS_AUDIT_RETENTION_DAYS` / `AUDIT_RETENTION_DAYS`	90

The dashboard shows Audit history available: N days from the live configuration. Missing older data means it is outside retained history — not that usage was zero.

Empty States¶

When no usage exists for the selected period:

No usage data is available for this period.

Usage Analytics will populate as Reports, Dashboards,
Views, APIs, and embedded content are used.

Individual sections use specific empty messages (for example, no failures or no embedded activity).