--- title: ElasticsearchAuditEventHandler (deprecated) description: This object is deprecated. Use one of the following objects instead: component: pinggateway version: 2024.11 page_id: pinggateway:reference:ElasticsearchAuditEventHandler canonical_url: https://docs.pingidentity.com/pinggateway/2024.11/reference/ElasticsearchAuditEventHandler.html revdate: 2025-06-03T09:07:28Z section_ids: ElasticsearchAuditEventHandler-usage: Usage ElasticsearchAuditEventHandler-properties: Properties ElasticsearchAuditEventHandler-moreinfo: More information --- # ElasticsearchAuditEventHandler (deprecated) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This object is deprecated. Use one of the following objects instead:- [SyslogAuditEventHandler](SyslogAuditEventHandler.html) - [JsonAuditEventHandler](JsonAuditEventHandler.html), with `elasticsearchCompatible` set to `true`Learn more in the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | An audit event handler that responds to events by logging messages in the Elasticsearch search and analytics engine. You can find information about downloading and installing Elasticsearch in the Elasticsearch [Getting started](https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html) document. ## Usage Configure the ElasticsearchAuditEventHandler within an [AuditService](AuditService.html): ```json { "type": "AuditService", "config": { "config": {}, "eventHandlers": [{ "class": "org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler", "config": { "name": configuration expression, "topics": [ configuration expression, ... ], "connection": { "host": configuration expression, "port": configuration expression, "useSSL": configuration expression, "username": configuration expression, "password": configuration expression }, "indexMapping": { "indexName": configuration expression }, "buffering": { "enabled": configuration expression, "writeInterval": configuration expression, "maxSize": configuration expression, "maxBatchedEvents": configuration expression } } } } } ``` The ElasticsearchAuditEventHandler relays audit events to Elasticsearch through the HTTP protocol, using a handler defined in a heap. The handler can be of any kind of handler, from a simple ClientHandler to a complex Chain, composed of multiple filters and a final handler or ScriptableHandler. PingGateway searches first for a handler named `ElasticsearchClientHandler`. If not found, PingGateway searches for a client handler named `AuditClientHandler`. If not found, PingGateway uses the route's default client handler, named `ClientHandler`. The following example configures a ClientHandler named `ElasticsearchClientHandler`: ```json { "name": "ElasticsearchClientHandler", "type": "ClientHandler", "config": {} } ``` The following example configures a ScriptableHandler named `AuditClientHandler`: ```json { "name": "AuditClientHandler", "type": "ScriptableHandler", "config": {} } ``` ## Properties * `"name"`: *configuration expression<[string](preface.html#definition-string)>, required* The name of the event handler. - `"topics"`: *array of configuration expression<[strings](preface.html#definition-string)>, required* One or more topics that this event handler intercepts. PingGateway can record the following audit event topics: * `access`: Log access audit events. Access audit events occur at the system boundary, and include the arrival of the initial request and departure of the final response. To record `access` audit events, configure AuditService inline in a route, or in the heap. * customTopic: Log custom audit events. To create a topic for a custom audit event, include a JSON schema for the topic in your PingGateway configuration. To record custom audit events, configure AuditService in the heap, and refer to it from the route or subroutes. For an example of how to set up custom audit events, refer to [Record custom audit events](../configure/extending.html#audit-custom). - `"connection"`: *[object](preface.html#definition-object), optional* Connection settings for sending messages to Elasticsearch. If this object is not configured, it takes default values for its fields. This object has the following fields: * `"host"`: *configuration expression<[string](preface.html#definition-string)>, optional* Hostname or IP address of Elasticsearch. Default: `localhost` * `"port"`: *configuration expression<[number](preface.html#definition-number)>, optional* The port used by Elasticsearch. The value must be between 0 and 65535. Default: `9200` * `"useSSL"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Setting to use or not use SSL/TLS to connect to Elasticsearch. Default: `false` * `"username"`: *configuration expression<[string](preface.html#definition-string)>, optional* Username when basic authentication is enabled through Elasticsearch Shield. * `"password"`: *configuration expression<[string](preface.html#definition-string)>, optional* Password when basic authentication is enabled through Elasticsearch Shield. - `"indexMapping"`: *[object](preface.html#definition-object), optional* Defines how an audit event and its fields are stored and indexed. * `"indexName"`: *configuration expression<[string](preface.html#definition-string)>, optional* The index name. Set this parameter if the default name `audit` conflicts with an existing Elasticsearch index. Default: `audit`. - `"buffering"`: *[object](preface.html#definition-object), optional* Settings for buffering events and batch writes. * `"enabled"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Setting to use or not use log buffering. Default: false. * `"writeInterval"`: *configuration expression<[duration](preface.html#definition-duration)>* The interval at which to send buffered event messages to Elasticsearch. If buffering is enabled, this interval must be greater than 0. Default: 1 second * `"maxBatchedEvents"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of event messages in a batch write to Elasticsearch for each `writeInterval`. Default: 500 * `"maxSize"`: *configuration expression<[number](preface.html#definition-number)>, optional* The maximum number of event messages in the queue of buffered event messages. Default: 10000 ## More information [org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler](../_attachments/apidocs/org/forgerock/audit/handlers/elasticsearch/ElasticsearchAuditEventHandler.html)