/**
 * 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
 * <p>
 * http://www.apache.org/licenses/LICENSE-2.0
 * <p>
 * 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.
 */
package org.apache.hadoop.ozone.audit;
/**
 ******************************************************************************
 *                              Important
 * 1. Any changes to classes in this package can render the logging
 * framework broken.
 * 2. The logger framework has been designed keeping in mind future
 * plans to build a log parser.
 * 3. Please exercise great caution when attempting changes in this package.
 ******************************************************************************
 *
 *
 * This package lays the foundation for Audit logging in Ozone.
 * AuditLogging in Ozone has been built using log4j2 which brings in new
 * features that facilitate turning on/off selective audit events by using
 * MarkerFilter, checking for change in logging configuration periodically
 * and reloading the changes, use of disruptor framework for improved
 * Asynchronous logging.
 *
 * The log4j2 configurations can be specified in XML, YAML, JSON and
 * Properties file. For Ozone, we are using the Properties file due to sheer
 * simplicity, readability and ease of modification.
 *
 * log4j2 configuration file can be passed to startup command with option
 * -Dlog4j.configurationFile unlike -Dlog4j.configuration in log4j 1.x
 *
 ******************************************************************************
 *          Understanding the Audit Logging framework in Ozone.
 ******************************************************************************
 * **** Auditable ***
 * This is an interface to mark an entity as auditable.
 * This interface must be implemented by entities requiring audit logging.
 * For example - OMVolumeArgs, OMBucketArgs.
 * The implementing class must override toAuditMap() to return an
 * instance of Map<Key, Value> where both Key and Value are String.
 *
 * Key: must contain printable US ASCII characters
 * May not contain a space, =, ], or "
 * If the key is multi word then use camel case.
 *
 * Value: if it is a collection/array, then it must be converted to a comma
 * delimited string
 *
 * *** AuditAction ***
 * This is an interface to define the various type of actions to be audited.
 * To ensure separation of concern, for each sub-component you must create an
 * Enum to implement AuditAction.
 * Structure of Enum can be referred from the test class DummyAction.
 *
 * For starters, we expect following 3 implementations of AuditAction:
 * OMAction - to define action types for Ozone Manager
 * SCMAction - to define action types for Storage Container manager
 * DNAction - to define action types for Datanode
 *
 * *** AuditEventStatus ***
 * Enum to define Audit event status like success and failure.
 * This is used in AuditLogger.logXXX() methods.
 *
 *  * *** AuditLogger ***
 * This is where the audit logging magic unfolds.
 * The class has 2 Markers defined - READ and WRITE.
 * These markers are used to tag when logging events.
 *
 * *** AuditLoggerType ***
 * Enum to define the various AuditLoggers in Ozone
 *
 * *** AuditMarker ***
 * Enum to define various Audit Markers used in AuditLogging.
 *
 * *** AuditMessage ***
 * Entity to define an audit message to be logged
 * It will generate a message formatted as:
 * user=xxx ip=xxx op=XXXX_XXXX {key=val, key1=val1..} ret=XXXXXX
 *
 * *** Auditor ***
 * Interface to mark an actor class as Auditor
 * Must be implemented by class where we want to log audit events
 * Implementing class must override and implement methods
 * buildAuditMessageForSuccess and buildAuditMessageForFailure.
 *
 * ****************************************************************************
 *                              Usage
 * ****************************************************************************
 * Using the AuditLogger to log events:
 * 1. Get a logger by specifying the appropriate logger type
 * Example: ExtendedLogger AUDIT = new AuditLogger(AuditLoggerType.OMLogger)
 *
 * 2. Construct an instance of AuditMessage
 *
 * 3. Log Read/Write and Success/Failure event as needed.
 * Example
 * AUDIT.logWriteSuccess(buildAuditMessageForSuccess(params))
 *
 * 4. Log Level implicitly defaults to INFO for xxxxSuccess() and ERROR for
 * xxxxFailure()
 * AUDIT.logWriteSuccess(buildAuditMessageForSuccess(params))
 * AUDIT.logWriteFailure(buildAuditMessageForSuccess(params))
 *
 * See sample invocations in src/test in the following class:
 * org.apache.hadoop.ozone.audit.TestOzoneAuditLogger
 *
 * ****************************************************************************
 *                      Defining new Logger types
 * ****************************************************************************
 * New Logger type can be added with following steps:
 * 1. Update AuditLoggerType to add the new type
 * 2. Create new Enum by implementing AuditAction if needed
 * 3. Ensure the required entity implements Auditable
 *
 * ****************************************************************************
 *                      Defining new Marker types
 * ****************************************************************************
 * New Markers can be configured as follows:
 * 1. Define new markers in AuditMarker
 * 2. Get the Marker in AuditLogger for use in the log methods, example:
 * private static final Marker WRITE_MARKER = AuditMarker.WRITE.getMarker();
 * 3. Define log methods in AuditLogger to use the new Marker type
 * 4. Call these new methods from the required classes to audit with these
 * new markers
 * 5. The marker based filtering can be configured in log4j2 configurations
 * Refer log4j2.properties in src/test/resources for a sample.
 */