> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JFR events

Atoti implements some custom Java Flight Recording events, that are captured when using the [Java Flight Recorder](https://docs.oracle.com/en/java/javase/25/docs/api/jdk.jfr/jdk/jfr/FlightRecorder.html).

<Warning>
  Those events are public facing, and allow low-level debugging, but are susceptible to change at any version (major, minor, bugfix).
</Warning>

All Atoti events share a flat `atoti.*` namespace (following Oracle's [JFR naming guidelines](https://docs.oracle.com/en/java/javase/22/jfapi/guidelines-naming-and-labeling-events.html)).
Grouping is conveyed through the `@Category` attribute rather than dotted sub-namespaces.

## How to use

It is possible to activate/deactivate an event when launching a JFR. It is recommended to use a configuration files, see `jfr --help configure`.

For example:

```xml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
<configuration label="Custom" version="2.0">

    <event name="atoti.CubeCommit">
        <setting name="enabled">true</setting>
    </event>

    <event name="atoti.HierarchyCommit">
        <setting name="enabled">true</setting>
    </event>
</configuration>
```

Then when launching the java process, the argument `-XX:StartFlightRecording:filename=myFileName.jfr,settings=myCustomSettings.jfc` must be supplied.

To limit the number of events recorded, several JFR options can be used:

* `period`
* `threshold`
* `throttle` (starting with Java 25)

It is also possible to scrub an existing JFR from an event to reduce its size via the scrub command, see `jfr --help scrub`.

## Available events

| Event name                             | Event Label                        | Default                 | Meaning                                                                             | Documentation                                                                        |
| -------------------------------------- | ---------------------------------- | ----------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `atoti.MemoryAllocation`               | `Memory Allocation`                | Disabled                | Off-heap memory allocation                                                          | [Off-Heap Memory Monitoring](off-heap_memory)                                        |
| `atoti.MemoryRelease`                  | `Memory Release`                   | Disabled                | Off-heap memory freeing                                                             | [Off-Heap Memory Monitoring](off-heap_memory)                                        |
| `atoti.AggregatesContributionTask`     | `Aggregates Contribution Task`     | Disabled (since 6.1.17) | Task that aggregates the updates from the database into the collectors              |                                                                                      |
| `atoti.ConflatedTransactionProcessing` | `Conflated Transaction Processing` | Enabled                 | Conflation of several epochs by the continuous query engine                         | [Conflating Continuous Query Engine](../cube/continuous_query_engine#conflating-cqe) |
| `atoti.ContributionTask`               | `Contribution Task`                | Disabled (since 6.1.17) | Task that merges the contribution collectors into the aggregate provider            |                                                                                      |
| `atoti.RemovalTask`                    | `Removal Task`                     | Disabled (since 6.1.17) | Task that merges the removal collectors into the aggregate provider                 |                                                                                      |
| `atoti.CubeCommit`                     | `Cube Commit`                      | Enabled                 | Commit event on a cube                                                              |                                                                                      |
| `atoti.HierarchyCommit`                | `Hierarchy Commit`                 | Disabled (since 6.1.17) | Commit event on a hierarchy                                                         |                                                                                      |
| `atoti.HierarchyPipelineTask`          | `Hierarchy Pipeline Task`          | Disabled (since 6.1.17) | Task that performs contributions from a source partition to one or more hierarchies |                                                                                      |
| `atoti.MembersExtraction`              | `Members Extraction`               | Disabled (since 6.1.17) | Task that extracts and dictionarizes hierarchy members from fact records            |                                                                                      |
| `atoti.StorePartitionWork`             | `Store Partition Work`             | Disabled (since 6.1.15) | Work type performed on a store partition                                            |                                                                                      |