| // 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. |
| |=== |
| |
| |
| //// |