// 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.
= Working with Events

Ignite can generate events for a variety of operations happening in the cluster and notify your application about those operations. There are many types of events, including cache events, node discovery events, distributed task execution events, and many more.

== Enabling Events

In Ignite 3, events are configured cluster-wide, in link:administrators-guide/config/cluster-config[cluster configuration]. Events are organized in *channels*, each channel tracking one or more event types. You cannot enable or disable individual events, instead you need to disable event channels.

To create an event channel:

[source, shell]
----
cluster config update ignite.eventlog.channels.exampleChannel.events=["USER_AUTHENTICATION_SUCCESS"]
----

This channel will track the `USER_AUTHENTICATION_SUCCESS`, but not trigger yet. For the events to trigger, a *sink* must be configured. It sends the event information to the configured logger category at the configured level. Currently, only the `log` sink type is supported, and it writes output to Ignite log. Here is how you can enable log sink by using the CLI tool:

[source, shell]
----
cluster config update ignite.eventlog.sinks.exampleSink = {type="log", channel="exampleChannel"}
----

Now, the authorization events will be written to the log. Here is how the event may look like:

----
2024-06-04 16:19:29:840 +0300 [INFO][%defaultNode%sql-execution-pool-1][EventLog] {"type":"USER_AUTHORIZATION_SUCCESS","timestamp":1717507169840,"productVersion":"3.0.0","user":{"username":"ignite","authenticationProvider":"basic"},"fields":{"privileges":[{"action":"CREATE_TABLE","on":{"objectType":"TABLE","objectName":"TEST2","schema":"PUBLIC"}}],"roles":["system"]}}
----

Below is the cluster configuration config in JSON.

NOTE: In Ignite 3, you can create and maintain the configuration in either JSON or HOCON format.

[source, json]
----
{
  "ignite" : {
    "eventlog" : {
        "channels" : [ {
          "enabled" : true,
          "events" : [ "USER_AUTHENTICATION_SUCCESS" ],
          "name" : "exampleChannel"
        } ],
        "sinks" : [ {
          "channel" : "exampleChannel",
          "criteria" : "EventLog",
          "format" : "JSON",
          "level" : "INFO",
          "name" : "sampleSink",
          "type" : "log"
        } ]
    }
  }
}
----

== Sink Structure

Data sink configuration in Ignite 3 has the following structure:

[source, json]
----
{
  "channel" : "exampleChannel",
  "criteria" : "EventLog",
  "format" : "JSON",
  "level" : "INFO",
  "name" : "sampleSink",
  "type" : "log"
}
----

[cols="40%,60%",opts="header", stripes=none]
|=======
|Field
|Description

|channel
|The name of the event channel the data sink logs data for.

|criteria
|Logging criteria. By default, only EventLog messages are logged.

|format
|Output format. Currently, only `JSON` messages are supported.

|level
|The level the messages are posted to the log at. Supported values: `ALL`, `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`, `OFF`. Default value: `INFO`.

|name
|Arbitrary sink name.

|type
|Type of event sink. Currently, only `log` sink is supported, and is used to write events to log.
|=======

== Channel Structure

Event channel configuration in Ignite 3 has the following structure:

[source, json]
----
{
  "enabled" : true,
  "events" : [ "USER_AUTHENTICATION_SUCCESS" ],
  "name" : "exampleChannel"
}
----

[cols="40%,60%",opts="header", stripes=none]
|=======
|Field
|Description

|enabled
|Defines if this event channel is enabled.

|events
|The list of events tracked by the event channel. For the full list of event types, see link:developers-guide/events/events-list[Events List].

|name
|Arbitrary channel name.
|=======

== Event Structure

All events in Ignite 3 follow the same basic structure described below. Some events provide additional context in the `data` field.

[source, json]
----
{
  "type": "AUTHENTICATION",
  "user": { "username": "John", "authenticationProvider": "basic" },
  "timestamp": 1715169617,
  "productVersion": "3.0.0",
  "fields": {}
}
----

[cols="40%,60%",opts="header", stripes=none]
|=======
|Field
|Description

|type
|The type of the event. For the full list of event types, see link:developers-guide/events/events-list[Events List].

|user
|The name of the user, and the link:administrators-guide/security/authentication[authentication] provider used to authorize.

|timestamp
|Even time in UNIX epoch time.

|productVersion
|Ignite version used by the client.

|fields
|Event-specific data.
|=======