org.forgerock.audit.handlers.elasticsearch

Class ElasticsearchAuditEventHandler

java.lang.Object

org.forgerock.audit.events.handlers.AuditEventHandlerBase

org.forgerock.audit.handlers.elasticsearch.ElasticsearchAuditEventHandler

All Implemented Interfaces:

AuditEventHandler, BatchConsumer

public class ElasticsearchAuditEventHandler
extends AuditEventHandlerBase
implements BatchConsumer

AuditEventHandler for Elasticsearch.

Field Summary

Fields inherited from class org.forgerock.audit.events.handlers.AuditEventHandlerBase

eventTopicsMetaData

Constructor Summary

Constructors

Constructor and Description
ElasticsearchAuditEventHandler(ElasticsearchAuditEventHandlerConfiguration configuration, EventTopicsMetaData eventTopicsMetaData, Client client) Create a new ElasticsearchAuditEventHandler instance.

Method Summary

Modifier and Type	Method and Description
void	addToBatch(String topic, JsonValue event, StringBuilder payload) Adds an audit event to an Elasticsearch Bulk API payload.
protected String	buildBaseUri() Builds an Elasticsearch API base URI.
protected String	buildBasicAuthHeaderValue() Builds a basic authentication header-value, if username and password are provided in configuration.
protected String	buildBulkUri() Builds an Elasticsearch API URI for Bulk API.
protected String	buildEventUri(String topic, String eventId) Builds an Elasticsearch API URI for operating on a single event (e.g., index, get, etc.).
protected String	buildSearchUri(String topic, int pageSize, int offset) Builds an Elasticsearch API URI for Search API.
Promise<Void,BatchException>	publishBatch(String payload) Publishes a Bulk API payload to Elasticsearch.
Promise<ResourceResponse,ResourceException>	publishEvent(Context context, String topic, JsonValue event) Publishes an event to the provided topic.
protected Promise<ResourceResponse,ResourceException>	publishSingleEvent(String topic, JsonValue event) Publishes a single event to the provided topic.
Promise<QueryResponse,ResourceException>	queryEvents(Context context, String topic, QueryRequest query, QueryResourceHandler handler) Queries the Elasticsearch Search API for audit events.
Promise<ResourceResponse,ResourceException>	readEvent(Context context, String topic, String resourceId) Reads an event with the provided resource id from the provided topic.
protected static ResourceException	resourceException(String indexName, String topic, String resourceId, Response response) Gets an Exception Promise containing an Elasticsearch HTTP response status and payload.
void	shutdown() Instruct this object to flush any buffers and close any open file handles or network connections.
void	startup() Instruct this object that it is safe to initialize file handles and network connections.

Methods inherited from class org.forgerock.audit.events.handlers.AuditEventHandlerBase

getHandledTopics, getName, handleAction, isEnabled

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ElasticsearchAuditEventHandler

public ElasticsearchAuditEventHandler(ElasticsearchAuditEventHandlerConfiguration configuration,
                                      EventTopicsMetaData eventTopicsMetaData,
                                      Client client)

Create a new ElasticsearchAuditEventHandler instance.

Parameters:

configuration - Configuration parameters that can be adjusted by system administrators.

eventTopicsMetaData - Meta-data for all audit event topics.

client - HTTP client or null to use default client.

Method Detail

startup

public void startup()
             throws ResourceException

Description copied from interface: AuditEventHandler

Instruct this object that it is safe to initialize file handles and network connections.

Reconfiguration of the AuditService and its handlers is achieved by replacing rather than modifying the existing objects. Therefore, it's essential that the replacements do not perform any I/O that would interfere with the operation of the objects they are replacing until the old objects are shutdown. For example, when shutting down an old instance of a file-based AuditEventHandler, the old instance may need to flush buffers, apply file rotation or retention policies, or even add line or block signatures as part of tamper evident logging. Any of these operations could be broken if two handler instances are operating on the same set of files simultaneously.

Specified by:

startup in interface AuditEventHandler

Throws:

ResourceException - if starting the AuditEventHandler fails

shutdown

public void shutdown()
              throws ResourceException

Description copied from interface: AuditEventHandler

Instruct this object to flush any buffers and close any open file handles or network connections.

Specified by:

shutdown in interface AuditEventHandler

Throws:

ResourceException - if closing the AuditEventHandler fails

queryEvents

public Promise<QueryResponse,ResourceException> queryEvents(Context context,
                                                            String topic,
                                                            QueryRequest query,
                                                            QueryResourceHandler handler)

Queries the Elasticsearch Search API for audit events. Query some events from the provided topic.

Specified by:

queryEvents in interface AuditEventHandler

Parameters:

context - The context chain that initiated the event.

topic - The topic on which query is performed.

query - The request with the query.

handler - The handler to process responses for the query.

Returns:

a promise with either a response or an exception

readEvent

public Promise<ResourceResponse,ResourceException> readEvent(Context context,
                                                             String topic,
                                                             String resourceId)

Description copied from interface: AuditEventHandler

Reads an event with the provided resource id from the provided topic.

Specified by:

readEvent in interface AuditEventHandler

Parameters:

context - The context chain that initiated the event.

topic - The topic where event is read.

resourceId - The identifier of the event.

Returns:

a promise with either a response or an exception

publishEvent

public Promise<ResourceResponse,ResourceException> publishEvent(Context context,
                                                                String topic,
                                                                JsonValue event)

Description copied from interface: AuditEventHandler

Publishes an event to the provided topic.

Specified by:

publishEvent in interface AuditEventHandler

Parameters:

context - The context chain that initiated the event.

topic - The topic where to publish the event.

event - The event to publish.

Returns:

a promise with either a response or an exception

publishSingleEvent

protected Promise<ResourceResponse,ResourceException> publishSingleEvent(String topic,
                                                                         JsonValue event)

Publishes a single event to the provided topic.

Parameters:

topic - The topic where to publish the event.

event - The event to publish.

Returns:

a promise with either a response or an exception

addToBatch

public void addToBatch(String topic,
                       JsonValue event,
                       StringBuilder payload)
                throws BatchException

Adds an audit event to an Elasticsearch Bulk API payload.

Specified by:

addToBatch in interface BatchConsumer

Parameters:

topic - Event topic

event - Event JSON payload

payload - Elasticsearch Bulk API payload

Throws:

BatchException - indicates failure to add-to-batch

publishBatch

public Promise<Void,BatchException> publishBatch(String payload)

Publishes a Bulk API payload to Elasticsearch.

Specified by:

publishBatch in interface BatchConsumer

Parameters:

payload - Elasticsearch Bulk API payload

Returns:

a simple promise encapsulating any potential batch exception

buildBasicAuthHeaderValue

protected String buildBasicAuthHeaderValue()

Builds a basic authentication header-value, if username and password are provided in configuration.

Returns:

Basic authentication header-value or null if not configured

buildEventUri

protected String buildEventUri(String topic,
                               String eventId)

Builds an Elasticsearch API URI for operating on a single event (e.g., index, get, etc.).

Parameters:

topic - Audit topic

eventId - Event ID

Returns:

URI

buildBulkUri

protected String buildBulkUri()

Builds an Elasticsearch API URI for Bulk API.

Returns:

URI

buildSearchUri

protected String buildSearchUri(String topic,
                                int pageSize,
                                int offset)

Builds an Elasticsearch API URI for Search API.

Parameters:

topic - The audit topic to search.

pageSize - The number of results to return.

offset - The number of results to skip.

Returns:

The search uri.

buildBaseUri

protected String buildBaseUri()

Builds an Elasticsearch API base URI. The format is,

http[s]://host:port/indexName

Returns:

Base URI

resourceException

protected static ResourceException resourceException(String indexName,
                                                     String topic,
                                                     String resourceId,
                                                     Response response)

Gets an Exception Promise containing an Elasticsearch HTTP response status and payload.

Parameters:

indexName - Index name

topic - Event topic

resourceId - Event ID

response - HTTP response

Returns:

Exception Promise