# `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](https://coralogix.com/docs/dataprime/index.md).

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**.
1. Select **Settings** in the top-right actions bar to open the Data Usage settings panel.
1. 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:

```dataprime
source system/"dataplan.usage_events"
```

Filter and aggregate like any other dataset:

```dataprime
source system/"dataplan.usage_events"
| filter $d.pillar == "logs" && $d.priority == "high"
| groupby $d.entity_type aggregate sum($d.units) as total_units
```

## Schema description

Each event represents a unit of team data usage aggregated for a given logical key and time bucket. Events are published by Coralogix's data usage exporter after unit ratios have been applied.

| Field                    | Type              | Description                                                                |
| ------------------------ | ----------------- | -------------------------------------------------------------------------- |
| `applicationname`        | string            | The application name associated with the usage event.                      |
| `subsystemname`          | string            | The subsystem name associated with the usage event.                        |
| `timestamp`              | string (ISO 8601) | The time the usage event was recorded.                                     |
| `pillar`                 | string            | The observability pillar (for example, `logs`, `metrics`, `traces`).       |
| `entity_type`            | string            | The entity type being metered (for example, `metrics`, `spans`).           |
| `feature_id`             | string            | The specific feature being metered (for example, `metrics_data_metering`). |
| `feature_group_id`       | string            | The feature group (for example, `metrics`, `logs`).                        |
| `measurement_type`       | string            | The type of measurement (for example, `processed_data_size`).              |
| `size`                   | number            | The raw size of the metered data, in bytes.                                |
| `units`                  | number            | The Coralogix units consumed by this event.                                |
| `cx_source`              | string            | The source of the data (for example, `User`).                              |
| `priority`               | string            | The TCO priority tier: `high`, `medium`, or `low` (lowercase).             |
| `severity`               | string            | The log severity level (lowercase, for example, `info`).                   |
| `bucket_duration_millis` | number            | The duration of the metering bucket, in milliseconds.                      |
| `bucket_duration_ms`     | number            | Alias for `bucket_duration_millis`.                                        |

Note

`severity` and `priority` values are lowercase strings (for example, `info`, `medium`). Do not use title case when filtering.

## Example queries

Total billed units per entity type for the last 24 hours:

```dataprime
source system/"dataplan.usage_events"
| filter $m.timestamp > now() - 24h
| groupby $d.entity_type aggregate sum($d.units) as units
```

Top-5 pillars by raw data volume sent:

```dataprime
source system/"dataplan.usage_events"
| groupby $d.pillar aggregate sum($d.size) as total_bytes
| orderby total_bytes desc
| limit 5
```

Olly token consumption split by token type:

```dataprime
source system/"dataplan.usage_events"
| filter $d.entity_type == "olly"
| groupby $d.token_type aggregate sum($d.size) as tokens
```

## 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.
- If the exporter cannot resolve a unit ratio for a record, the event is still published with `units` set to `0`.
- Event timestamps reflect the aggregation window's most recent sample; multiple raw events may be merged into a single usage event per logical key and day.

## Next steps

- Manage dataset access and retention in [Dataset management](https://coralogix.com/docs/user-guides/data-layer/dataset-management/dataset-management/index.md).
- Track alert activity alongside usage with [`alerts.history`](https://coralogix.com/docs/user-guides/data-layer/system_dataspace/alerts-history/index.md).
- Audit account actions with [`aaa.audit_events`](https://coralogix.com/docs/user-guides/data-layer/system_dataspace/aaa_audit-events/index.md).