// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= Events
:javaFile: {javaCodeDir}/Events.java

:events_url: {javadoc_base_url}/org/apache/ignite/events


This page describes different event types, when and where they are generated, and how you can use them.

You can always find the most complete and up to date list of events in the javadoc:org.apache.ignite.events.EventType[] javadoc.

== General Information

All events implement the `Event` interface.
You may want to cast each event to the specific class to get extended information about the action the event was triggered by.
For example, the 'cache update' action triggers an event that is an instance of the `CacheEvent` class, which contains the information about the data that was modified, the ID of the subject that triggered the event, etc.


All events contain information about the node where the event was generated.
For example, when you execute an `IgniteClosure` job, the `EVT_JOB_STARTED` and `EVT_JOB_FINISHED` events contain the information about the node where the closure was executed.

[source, java]
----
include::{javaFile}[tags=get-node,indent=0]
----
////
When an event is generated by another event, the second event will contain the information about the first event.
For example, the cache rebalancing event can be triggered by
The rebalancing event will contain the information about the cause
////


[CAUTION]
====
[discrete]
=== Event Ordering

The order of events in the event listener is not guaranteed to be the same as the order in which they were generated.

====

=== SubjectID

Some events contain the `subjectID` field, which represents the ID of the entity that initiated the action:

* When the action is initiated by a server or client node, the `subjectID` is the ID of that node.
* When the action is done by a thin client, JDBC/ODBC/REST client, the `subjectID` is generated when the client connects to the cluster and remains the same as long as the client is connected to the cluster.

Check the specific event class to learn if the `subjectID` field is present.


== Cluster State Changed Events

Cluster state changed events are instances of the javadoc:org.apache.ignite.events.ClusterStateChangeEvent[] class.

The cluster state changed events are generated when the cluster state changes, which happens either on auto-activation, or when a user changes the state manually.
The events contain the new and old states, and the list of baseline nodes after the change.

[cols="2,5,3",opts="header"]
|===
|Event Type | Event Description | Where Event Is Fired
|EVT_CLUSTER_STATE_CHANGED | The cluster state changed.  | All cluster nodes.
|===

== Cache Lifecycle Events

Cache Lifecycle events are instances of the link:{events_url}/CacheEvent.html[CacheEvent, window=_blank] class.
Each cache lifecycle event is associated with a specific cache and has a field that contains the name of the cache.

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_CACHE_STARTED
a| A cache is started on a specific node.
Each server node holds an internal instance of a cache.
This event is fired when the instance is created, which includes the following actions:

* A cluster with existing caches is activated. The event is generated for every cache on all server nodes where the cache is configured.
* A server node joins the cluster with existing caches (the caches are started on that node).
* When you create a new cache dynamically by calling `Ignite.getOrCreateCache(...)` or similar methods. The event is fired on all nodes that host the cache.
* When you obtain an instance of a cache on a client node.
* When you create a cache via the link:sql-reference/ddl#create-table[CREATE TABLE] command.


| All nodes where the cache is started.
| EVT_CACHE_STOPPED a| This event happens when a cache is stopped, which includes the following actions:

* The cluster is deactivated. All caches on all server nodes are stopped.
* `IgniteCache.close()` is called. The event is triggered on the node where the method is called.
* A SQL table is dropped.
* If you call `cache = Ignite.getOrCreateCache(...)` and then call `Ignite.close()`, the `cache` is also closed on that node.

|All nodes where the cache is stopped.

| EVT_CACHE_NODES_LEFT | All nodes that host a specific cache have left the cluster. This can happen when a cache is deployed on a subset of server nodes or when all server nodes leave the cluster and only client nodes remain. | All remaining nodes.
|===


== Cache Events
Cache events are instances of the link:{events_url}/CacheEvent.html[CacheEvent] class and
represent the operations on cache objects, such as 'get', 'put', 'remove', 'lock', etc.

Each event contains the information about the cache, the key that is accessed by the operation, the value before and after the operation (if applicable), etc.

Cache events are also generated when you use DML commands.


[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_CACHE_OBJECT_PUT | An object is put to a cache. This event is fired for every invocation of `IgniteCache.put()`. The bulk operations, such as `putAll(...)`, produce multiple events of this type.

| The primary and backup nodes for the entry.

| EVT_CACHE_OBJECT_READ
| An object is read from a cache.
This event is not emitted when you use link:key-value-api/using-scan-queries[scan queries] (use <<Cache Query Events>> to monitor scan queries).
| The node where read operation is executed.
It can be either the primary or backup node (the latter case is only possible when link:configuring-caches/configuration-overview#readfrombackup[reading from backups is enabled]).
In transactional caches, the event can be generated on both the primary and backup nodes depending on the concurrency and isolation levels.

| EVT_CACHE_OBJECT_REMOVED | An object is removed from a cache. |The primary and backup nodes for the entry.

| EVT_CACHE_OBJECT_LOCKED
a| A lock is acquired on a specific key.
Locks can be acquired only on keys in transactional caches.
User actions that acquire a lock include the following cases:

* The user explicitly acquires a lock by calling `IgniteCache.lock()` or `IgniteCache.lockAll()`.
* A lock is acquired for every atomic (non-transactional) data modifying operation (put, update, remove).
In this case, the event is triggered on both primary and backup nodes for the key.
* Locks are acquired on the keys accessed within a transaction (depending on the link:key-value-api/transactions#concurrency-modes-and-isolation-levels[concurrency and isolation levels]).

| The primary or/and backup nodes for the entry depending on the link:key-value-api/transactions#concurrency-modes-and-isolation-levels[concurrency and isolation levels].

| EVT_CACHE_OBJECT_UNLOCKED | A lock on a key is released. | The primary node for the entry.

| EVT_CACHE_OBJECT_EXPIRED | The event is fired when a cache entry expires. This happens only if an link:configuring-caches/expiry-policies[expiry policy] is configured.  | The primary and backup nodes for the entry.
| EVT_CACHE_ENTRY_CREATED | This event is triggered when Ignite creates an internal entry for working with a specific object from a cache. We don't recommend using this event. If you want to monitor cache put operations, the `EVT_CACHE_OBJECT_PUT` event should be enough for most cases. | The primary and backup nodes for the entry.

| EVT_CACHE_ENTRY_DESTROYED
|  This event is triggered when Ignite destroys an internal entry that was created for working with a specific object from a cache.
We don't recommend using it.
Destroying the internal entry does not remove any data from the cache.
If you want to monitor cache remove operations, use the `EVT_CACHE_OBJECT_REMOVED` event.
| The primary and backup nodes for the entry.
|===

== Cache Query Events

There are two types of events that are related to cache queries:

* Cache query object read events, which are instances of the link:{events_url}/CacheQueryReadEvent.html[CacheQueryReadEvent, window=_blank] class.
* Cache query executed events, which are instances of the link:{events_url}/CacheQueryExecutedEvent.html[CacheQueryExecutedEvent, window=_blank] class.


[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_CACHE_QUERY_OBJECT_READ | An object is read as part of a query execution. This event is generated for every object that matches the link:key-value-api/using-scan-queries#executing-scan-queries[query filter]. | The primary node of the object that is read.
| EVT_CACHE_QUERY_EXECUTED  |  This event is generated when a query is executed. | All server nodes that host the cache.
|===

////
== Checkpointing Events

Related to checkpointingspi in map-reduce

Checkpointing events are instances of the link:{events_url}/CheckpointEvent.html[CheckpointEvent] class.

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_CHECKPOINT_LOADED |  | The node
| EVT_CHECKPOINT_REMOVED | |
| EVT_CHECKPOINT_SAVED | |
|===
////

== Class and Task Deployment Events

Deployment events are instances of the link:{events_url}/DeploymentEvent.html[DeploymentEvent] class.

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_CLASS_DEPLOYED | A class (non-task) is deployed on a specific node. | The node where the class is deployed.
| EVT_CLASS_UNDEPLOYED | A class is undeployed. | The node where the class is undeployed.
| EVT_CLASS_DEPLOY_FAILED | Class deployment failed. |The node where the class is to be deployed.
| EVT_TASK_DEPLOYED | A task class is deployed on a specific node. | The node where the class is deployed.
| EVT_TASK_UNDEPLOYED | A task class is undeployed on a specific node.|The node where the class is undeployed.
| EVT_TASK_DEPLOY_FAILED | Class deployment failed.|The node where the class is to be deployed.
|===

== Discovery Events

Discovery events occur when nodes (both servers and clients) join or leave the cluster, including cases when nodes leave due to a failure.

Discovery events are instances of the link:{events_url}/DiscoveryEvent.html[DiscoveryEvent] class.

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_NODE_JOINED | A node joins the cluster. | All nodes in the cluster (other than the one that joined).
| EVT_NODE_LEFT | A node leaves the cluster. |All remaining nodes in the cluster.
| EVT_NODE_FAILED | The cluster detects that a node left the cluster in a non-graceful way. | All remaining nodes in the cluster.
| EVT_NODE_SEGMENTED | This happens on a node that decides that it was segmented. | The node that is segmented.
| EVT_CLIENT_NODE_DISCONNECTED | A client node loses connection to the cluster.  | The client node that disconnected from the cluster.
| EVT_CLIENT_NODE_RECONNECTED | A client node reconnects to the cluster.| The client node that reconnected to the cluster.
|===

== Task Execution Events

Task execution events are associated with different stages of link:distributed-computing/map-reduce[task execution].
They are also generated when you execute link:distributed-computing/distributed-computing[simple closures] because internally a closure is treated as a task that produces a single job.

////
This is what happens when you execute a task through the compute interface:

. Task is deployed on all nodes (associated with the compute interface)
. Task is started (the map stage)
. Jobs are executed on the remote nodes
. The reduce stage
////

Task Execution events are instances of the link:{events_url}/TaskEvent.html[TaskEvent] class.

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_TASK_STARTED | A task is started. `IgniteCompute.execute()` or other method is called   | The node that initiates the task.
| EVT_TASK_REDUCED | This event represents the 'reduce' stage of the task execution flow.  | The node where the task was started.
| EVT_TASK_FINISHED | The execution of the task finishes. | The node where the task was started.
| EVT_TASK_FAILED | The task failed  | The node where the task was started.
| EVT_TASK_TIMEDOUT |  The execution of the task timed out. This can happen when `Ignite.compute().withTimeout(...)` to execute tasks. When a task times out, it cancels all jobs that are being executed. It also generates the `EVT_TASK_FAILED` event.| The node where the task was started.
| EVT_TASK_SESSION_ATTR_SET | A job sets an attribute in the link:distributed-computing/map-reduce#distributed-task-session[session]. | The node where the job is executed.
|===

{sp}+

Job Execution events are instances of the link:{events_url}/JobEvent.html[JobEvent] class.
The job execution events are generated at different stages of job execution and are associated with particular instances of the job.
The event contains information about the task that produced the job (task name, task class, etc.).

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired

| EVT_JOB_MAPPED | A job is mapped to a specific node. Mapping happens on the node where the task is started. This event is generated for every job produced in the "map" stage. | The node that started the task.

| EVT_JOB_QUEUED | The job is added to the queue on the node to which it was mapped. | The node where the job is scheduled for execution.

| EVT_JOB_STARTED | Execution of the job started.| The node where the job is executed.

| EVT_JOB_FINISHED | Execution of the job finished. This also includes cases when the job is cancelled.| The node where the job is executed.

| EVT_JOB_RESULTED | The job returned a result to the node from which it was sent. | The node where the task was started.

| EVT_JOB_FAILED | Execution of a job fails. If the job failover strategy is configured (default), this event is accompanied by the `EVT_JOB_FAILED_OVER` event. | The node where the job is executed.

| EVT_JOB_FAILED_OVER | The job was failed over to another node. | The node that started the task.

| EVT_JOB_TIMEDOUT | The job timed out. |

| EVT_JOB_REJECTED | The job is rejected. The job can be rejected if a link:distributed-computing/job-scheduling[collision spi] is configured. | The node where the job is rejected.

| EVT_JOB_CANCELLED | The job was cancelled. | The node where the job is being executed.
|===


== Cache Rebalancing Events

Cache Rebalancing events (all except for `EVT_CACHE_REBALANCE_OBJECT_LOADED` and `EVT_CACHE_REBALANCE_OBJECT_UNLOADED`) are instances of the link:{events_url}/CacheRebalancingEvent.html[CacheRebalancingEvent] class.

Rebalancing occurs on a per cache basis; therefore, each rebalancing event corresponds to a specific cache.
The event contains the name of the cache.

The process of moving a single cache partition from Node A to Node B consists of the following steps:

. Node A supplies a partition (REBALANCE_PART_SUPPLIED). The objects from the partition start to move to node B.
. Node B receives the partition data (REBALANCE_PART_LOADED).
. Node A removes the partition from its storage (REBALANCE_PART_UNLOADED).

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_CACHE_REBALANCE_STARTED | The rebalancing of a cache starts. | All nodes that host the cache.
| EVT_CACHE_REBALANCE_STOPPED | The rebalancing of a cache stops. | All nodes that host the cache.
| EVT_CACHE_REBALANCE_PART_LOADED | A cache's partition is loaded on the new node. This event is fired for every partition that participates in the cache rebalancing.| The node where the partition is loaded.
| EVT_CACHE_REBALANCE_PART_UNLOADED |A cache's partition is removed from the node after it has been loaded to its new destination. | The node where the partition was held before the rebalancing process started.
| EVT_CACHE_REBALANCE_OBJECT_LOADED | An object is moved to a new node as part of cache rebalancing. | The node where the object is loaded.
| EVT_CACHE_REBALANCE_OBJECT_UNLOADED | An object is removed from a node after it has been moved to a new node.| The node from which the object is removed.
| EVT_CACHE_REBALANCE_PART_DATA_LOST | A partition that is to be rebalanced is lost, for example, due to a node failure. |
| EVT_CACHE_REBALANCE_PART_SUPPLIED | A node supplies a cache partition as part of the rebalancing process. | The node that owns the partition.
//| EVT_CACHE_REBALANCE_PART_MISSED | *TODO*|
|===

== Transaction Events

Transaction events are instances of the link:{events_url}/TransactionStateChangedEvent.html[TransactionStateChangedEvent] class.
They allow you to get notification about different stages of transaction execution. Each event contains the `Transaction` object this event is associated with.


[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_TX_STARTED | A transaction is started. Note that in transactional caches, each atomic operation executed outside a transaction is considered a transaction with a single operation. | The node where the transaction was started.
| EVT_TX_COMMITTED | A transaction is committed. |  The node where the transaction was started.
| EVT_TX_ROLLED_BACK | A transaction is rolled back. |The node where the transaction was executed.
| EVT_TX_SUSPENDED |  A transaction is suspended.|The node where the transaction was started.
| EVT_TX_RESUMED | A transaction is resumed. |The node where the transaction was started.
|===


////
== Management Task Events

Management task events represent the tasks that are executed by Visor or Web Console.
This event type can be used to monitor a link:security/cluster-monitor-audit[Web Console activity].

[cols="2,5,3",opts="header"]
|===
| Event Type | Event Description | Where Event Is Fired
| EVT_MANAGEMENT_TASK_STARTED | A task from Visor or Web Console starts. | The node where the task is executed.
|===


////