Skip to main content

Usage

Cirata Symphony includes a comprehensive usage tracking and attribution system that records how extensions consume licensed capacity, attributes that consumption to business units, and provides the data needed for internal chargeback and cost allocation.

How Usage Tracking Works​

When an extension performs work—replicating tables, processing events, transferring data—it reports dimensions to Symphony. Dimensions are named measurements specific to each extension, such as tables_replicated, bytes_transferred_gb, or events_processed.

Symphony converts these dimensions into units using the conversion rates defined in the active license. For example, a license might define that each replicated table consumes 1 unit, while each gigabyte transferred consumes 0.5 units. The total units consumed are tracked against the licensed capacity.

This flow is automatic: extensions call a single report_usage() function, and Symphony handles conversion, attribution, and enforcement.

Viewing Usage​

Navigate to the Licensing page and select the Usage tab. The dashboard shows:

  • Status—current enforcement state (OK, Warning, or Unlicensed)
  • Available Units—total licensed capacity
  • Units Used—total consumed across all extensions
  • Units Remaining—available capacity (switches to Units Over in red when usage exceeds the licensed pool)

The Extensions tab shows the same data broken down by extension: a sortable table with a per-extension status pill (mirroring the dots on the Usage tab's Status card) and, on wider screens, a pie chart of each extension's share of total unit usage. Clicking a slice or a row filters the dimension breakdown table below to that extension.

An interactive chart shows usage over time, with shaded regions indicating remaining capacity, warning thresholds (90%+), and enforced limits.

Below the chart, a table breaks down usage by extension, showing each extension's unit consumption.

You can also query usage metrics from the CLI:

cirata observability query_scalar_metrics licensing.usage.units

Enforcement​

Symphony enforces usage limits through a graduated system:

StateConditionEffect
OKUsage below 90% of licensed capacityNormal operation
WarningUsage at or above 90%, or a license is in its grace periodNormal operation; warning indicators appear for affected extensions
UnlicensedGrace period expired or no valid licenseExtensions that consume licensed capacity are disabled

Enforcement state is broadcast to all connected extensions in real time. Extensions can subscribe to enforcement updates and respond accordingly—for example, by pausing non-critical work when capacity is low.

Extensions that report dimensions not covered by any license are disabled independently of the global enforcement state.

Organisation and Attribution​

Usage can be attributed to business units—organisational groups such as departments, teams, or cost centres. Attribution can be performed manually on individual records or automatically via attribution rules that match usage based on the reporting extension and user account.

See Organization for details on setting up business units and attribution rules.

Cost Allocation​

The Attribution tab provides aggregated views of usage by business unit, suitable for internal cost allocation and billing. Reports can be grouped by extension, business unit, or time period.

See Cost Attribution for details on attribution reporting and cost allocation.

For Extension Developers​

Extensions report usage through the Symphony client libraries:

  • Python—await ext.report_usage({"tables_replicated": 5})
  • Java—runtime.reportUsage(Map.of("tables_replicated", 5))
  • Go—client.ReportUsage(map[string]float64{"tables_replicated": 5})

The response includes the number of units consumed and the current enforcement state, allowing extensions to adapt their behaviour.

See the Extension Development guide for implementation details.

See Also​