Open in ChatGPTOpen in Claude

dataplan.usage_events

The dataplan.usage_events dataset stores aggregated data usage events for your team. Each event captures a unit of ingestion after ratios have been applied, letting you query your team's consumption alongside any other data in Coralogix using DataPrime.

Use this dataset to analyze usage trends, build custom dashboards and alerts on top of raw usage events, and correlate consumption with other telemetry, without relying solely on the Data Usage page.

Enable the dataset

The dataset is exposed through Coralogix's dataset management and is populated only when ingestion is enabled for dataplan.usage_events.

1. In the navigation bar, select Settings, then Data Usage.
2. Select Settings in the top-right actions bar to open the Data Usage settings panel.
3. In the data.usage.history row, select Enable data.usage.history. Coralogix takes you to Dataspace management, where you can enable write access for the dataplan.usage_events system dataset.

Once ingestion is enabled, new usage events are written to the dataset as they are aggregated. You can return to the settings panel to open the dataset directly in Explore with View dataset in Explore.

Query the dataset

Query dataplan.usage_events using DataPrime:

source system/"dataplan.usage_events"

Filter and aggregate like any other dataset:

source system/"dataplan.usage_events"
| filter $d.cxLabels.pillar == "logs"
| groupby $d.userLabels.applicationname aggregate sum($d.measurement.consumedCxUnits) as units

Schema description

Each event represents one aggregated bucket of team data usage for a given logical key and time window, published by Coralogix's data usage exporter after unit ratios have been applied. All field names, and the keys of both label maps, use camelCase.

Field	Type	Required	Description
$d	object	Yes	Aggregated usage records exported by data-usage into the system usage_events dataset. All field names and both label maps use camelCase on the wire.
$d.bucketDurationNs	integer	Yes	Duration of the aggregated usage bucket, in nanoseconds.
$d.bucketTimeStartNs	integer	Yes	Start of the aggregated usage bucket, in epoch nanoseconds. This is the event's only time field.
$d.cxLabels	map	Yes	Coralogix-owned labels. Always present: pillar, entityType, priority, featureId, and featureGroupId. May also include severity, dataSpace, dataSet, tcoPolicyId, tcoPolicyName, parsingRuleName, and for Olly usage model and tokenType.
$d.cxLabels.<key>	string	No
$d.measurement	object	Yes
$d.measurement.consumedCxUnits	number	Yes	Billable Coralogix units consumed by the raw measured value.
$d.measurement.kind	string	Yes	Measurement kind, for example processed_data_size, egress_data_size, events, samples, tokens, or olly.
$d.measurement.unit	string	Yes	Unit for the raw measured value, for example bytes, events, samples, or tokens.
$d.measurement.value	integer	Yes	Raw measured value for the bucket.
$d.userLabels	map	Yes	Customer-owned labels, carried through from ingestion. May include applicationname and subsystemname alongside any custom tags the customer sends.
$d.userLabels.<key>	string	No
$l	map	Yes	User labels: free-form string-to-string map
$l.<key>	string	No
$m	object	Yes	Engine metadata
$m.cxEventId	string (uuid)	Yes	Globally unique event id
$m.ingressTimestamp	string (date-time)	Yes	Time the event was ingested
$m.priorityClass	string	Yes	Defines the feature-set enabled for the event One of: high, medium, low.
$m.severity	string	Yes	Event severity level One of: Verbose, Debug, Info, Warning, Error, Critical.
$m.timestamp	string (date-time)	Yes	Event timestamp

Note

$d.cxLabels and $d.userLabels are dynamic string maps: reference an individual label as $d.cxLabels.<key> or $d.userLabels.<key> (for example, $d.cxLabels.pillar). Label values for severity and priority are lowercase.

Example queries

Consumed Coralogix units by pillar:

source system/"dataplan.usage_events"
| groupby $d.cxLabels.pillar aggregate sum($d.measurement.consumedCxUnits) as units
| orderby units desc

Raw bytes ingested by application over the selected time range:

source system/"dataplan.usage_events"
| filter $d.measurement.kind == "processed_data_size"
| groupby $d.userLabels.applicationname aggregate sum($d.measurement.value) as total_bytes
| orderby total_bytes desc
| limit 5

Notes and limits

• dataplan.usage_events is a system dataset maintained by Coralogix. Like other system datasets, events count toward your daily quota; volumes are typically small compared to your user data.
• Each event is one aggregated bucket; multiple raw events may be merged into a single usage event per logical key and time window.

Next steps

• Manage dataset access and retention in Dataset management.
• Track quota activity with dataplan.quota_events.
• Audit account actions with aaa.audit_events.