Usage Tracking & Reporting

Cirata Symphony tracks extension usage and converts it into units using the rates defined in the active license. Administrators can view summaries, explore historical trends in an interactive chart, and generate cryptographically signed reports.

How Usage is Reported

Extensions report usage by publishing messages to a NATS service. Each usage report includes:

• Extension prefix—identifies which extension generated the usage
• Dimensions—a set of named measurements (e.g., tables_replicated: 5, bytes_transferred_gb: 120.5)
• Account—the account that generated the usage (optional)

Symphony converts the raw dimensions into units using the unit rates from the active license and stores both the raw dimensions and the computed units. Each usage record also records the identifier of the license it was charged against.

If attribution rules have been configured, Symphony automatically assigns a business unit to matching records at the time of recording. The attribution method is tracked as Auto for rule-based assignments and Manual for administrator-assigned ones.

License Selection

When multiple licenses are active, Symphony uses a first-expiring-first strategy: for each usage report, only licenses that define a unit rate for the reporting extension are considered. Among those, usage is charged to the soonest-expiring license that still has remaining capacity, then overflows to the next. When two licenses share the same expiry date, the earlier-issued license is consumed first. This ensures earlier licenses are fully utilized before newer ones are drawn upon.

Viewing the Usage Dashboard

Navigate to Licensing > Usage to see the usage dashboard.

Summary Cards

Four cards at the top provide an at-a-glance overview:

Card	Description
Status	Current enforcement status (OK, Warning, or Unlicensed), color-coded green, yellow, or red. Below the status, colored dots show per-extension status: green for extensions covered by active licenses, amber for extensions covered only by grace-period licenses, and red for disabled or unlicensed extensions
Available Units	Total unit pool across all active and grace-period licenses that pass both signature and deployment key validation
Units Used	Total units consumed against valid licenses, shown as both an absolute value and a percentage of total licensed capacity
Units Remaining	Remaining capacity across all valid active licenses. When usage exceeds the licensed pool, this card switches to Units Over (red), showing the overage as a positive value

The cards and chart are consistent—both reflect only licenses that pass signature verification and deployment key validation. Licenses with an invalid signature or mismatched deployment key are excluded from all calculations. See Ongoing Validation for details.

Usage Chart

Below the summary cards, an interactive chart visualizes usage over time:

• Used area—a filled area showing cumulative unit consumption over time, drawn from the baseline upward
• Stacked areas—colored regions showing the remaining capacity contributed by each valid active license. The total remaining is traced by a green stroke line along the top. Only licenses that pass both signature and deployment key validation are included
• Warning overlay—orange shaded region marking periods where remaining units dropped below 10% of total capacity
• Unlicensed overlay—red shaded region marking periods where remaining capacity reached zero
• "Now" marker—a vertical dashed line indicating the current time, positioned with sub-bucket precision
• Zero line—a red dashed horizontal line marking y=0 on the remaining axis

The y-axis automatically scales to encompass all data, snapping to the next human-friendly axis marker beyond the highest used or capacity value in both the positive and negative directions.

Granularity

The chart automatically selects the time aggregation granularity based on the visible time span. Shorter spans use finer granularity (e.g., Hour or Day), while longer spans use coarser levels (Week, Month, or Year). As you zoom in or out, the granularity adjusts to show an appropriate level of detail.

Zoom and Navigation

• Drag to zoom—click and drag across the chart to zoom into a time range. The granularity is automatically adjusted to suit the selected range
• Scrollbar—a horizontal scrollbar below the chart shows the zoom position within the full dataset. Drag the thumb to pan, or drag either edge of the thumb to resize the visible window
• Scroll wheel—when zoomed in, use the mouse wheel to pan left and right
• Reset View—click the button at the bottom-left to return to the full, unzoomed view

Hover Tooltip

Hovering over the chart displays a tooltip with detailed information for that point in time:

• Per-extension cumulative unit consumption
• Available—total licensed capacity
• Used—cumulative units consumed (with a color indicator)
• Remaining—total remaining units (with a green color indicator)
• License breakdown—each active license showing its color, abbreviated identifier, issued-to-expiry date range, and remaining vs. total units

Filtering by Extension

Use the extension filter dropdown above the usage table to show records from a specific extension only. Select "All Extensions" to reset the filter.

The summary cards always reflect the totals across all extensions, regardless of the filter selection.

Extensions Tab

Navigate to Licensing > Extensions for a per-extension view of usage. The tab lists every extension Symphony knows about—anything with a usage record or in the current enforcement disabled-list—so the rows match the per-extension dots shown on the Usage tab's Status card.

Each row shows:

• Extension—the extension's display name
• Units Used—priceable units consumed against currently active licenses. An extension whose only records are charged to a license that has since retired shows 0 here, but it still appears with the appropriate status pill so it isn't silently dropped from the view
• Status—OK (green), Warning (amber, for grace-period coverage) or Unlicensed (red, for globally enforced or disabled extensions), using the same enforcement-derived logic as the Status card

On wider screens a pie chart appears to the left of the table, showing each extension's share of total unit usage. Clicking a slice or a row selects that extension and filters the Dimension breakdown table below to its dimensions.

Understanding Dimensions and Units

Each usage record stores two pieces of information:

• Dimensions—the raw measurements reported by the extension (e.g., tables_replicated: 5)
• Units—the computed license units, calculated by multiplying each dimension value by its corresponding rate from the license

For example, if the license defines tables_replicated at 0.5 units per table, then 5 tables replicated consumes 2.5 units.

If no unit rate is defined for a given extension, or if a reported dimension has no entry in the rate, the usage is recorded with 0 units consumed and the specific extension is added to the disabled extensions list. This does not affect the global enforcement state—only the uncovered extension is impacted. See Per-Extension Enforcement for details.

Generating Usage Reports

Symphony can generate a cryptographically signed usage report for verification by the vendor:

1. Navigate to Licensing > Usage.
2. Click Generate Usage Report.
3. A JSON file is downloaded containing the usage summary, detailed records, and a digital signature.

The report is signed using the instance's operator Ed25519 signing key. The vendor can verify the report's authenticity using the instance's public key, which is included in the report.

Report Contents

The signed report JSON includes:

Field	Description
report	JSON-encoded usage data (summary + detailed records)
signature	Base64-encoded Ed25519 signature
signing_key	The instance's public key for verification
generated_at	Timestamp when the report was generated

See Also

• Licensing—License management and unit rates
• Business Units & Attribution—Attribute usage to business units