Package org.apache.hadoop.fs.audit

Class CommonAuditContext

java.lang.Object
org.apache.hadoop.fs.audit.CommonAuditContext
@Public @Unstable public final class CommonAuditContext extends Object
The common audit context is a map of common context information which can be used with any audit span. This context is shared across all Filesystems within the thread. Audit spans will be created with a reference to the current context of their thread; That reference is retained even as they are moved across threads, so context information (including thread ID Java runtime). The Global context entries are a set of key-value pairs which span all threads; the HttpReferrerAuditHeader picks these up automatically. It is intended for minimal use of shared constant values (process ID, entry point). An attribute set in setGlobalContextEntry(String, String) will be set across all audit spans in all threads. The noteEntryPoint(Object) method should be used in entry points (ToolRunner.run, etc). It extracts the final element of the classname and attaches that to the global context with the attribute key AuditConstants.PARAM_COMMAND, if not already set. This helps identify the application being executued. All other values set are specific to this context, which is thread local. The attributes which can be added to ths common context include evaluator methods which will be evaluated in whichever thread invokes getEvaluatedEntries() and then evaluates them. That map of evaluated options may evaluated later, in a different thread. For setting and clearing thread-level options, use currentAuditContext() to get the thread-local context for the caller, which can then be manipulated. For further information, especially related to memory consumption, read the document `auditing_architecture` in the `hadoop-aws` module.

  • Field Details

    • PROCESS_ID

      public static final String PROCESS_ID
      Process ID; currently built from UUID and timestamp.

  • Method Details

    • put

      public Supplier<String> put(String key, String value)
      Put a context entry.
      Parameters:
      key - key
      value - new value., If null, triggers removal.
      Returns:
      old value or null

    • put

      public Supplier<String> put(String key, Supplier<String> value)
      Put a context entry dynamically evaluated on demand. Important: as these supplier methods are long-lived, the supplier function MUST NOT be part of/refer to any object instance of significant memory size. Applications SHOULD remove references when they are no longer needed. When logged at TRACE, prints the key and stack trace of the caller, to allow for debugging of any problems.
      Parameters:
      key - key
      value - new value
      Returns:
      old value or null

    • remove

      public void remove(String key)
      Remove a context entry.
      Parameters:
      key - key

    • get

      public String get(String key)
      Get a context entry.
      Parameters:
      key - key
      Returns:
      value or null

    • reset

      public void reset()
      Rest the context; will set the standard options again. Primarily for testing.

    • containsKey

      public boolean containsKey(String key)
      Does the context contain a specific key?
      Parameters:
      key - key
      Returns:
      true if it is in the context.

    • currentAuditContext

      public static CommonAuditContext currentAuditContext()
      Get the current common audit context. Thread local.
      Returns:
      the audit context of this thread.

    • currentThreadID

      public static String currentThreadID()
      A thread ID which is unique for this process and shared across all S3A clients on the same thread, even those using different FS instances.
      Returns:
      a thread ID for reporting.

    • getEvaluatedEntries

      public Map<String,Supplier<String>> getEvaluatedEntries()
      Get the evaluated operations. This is the map unique to this context.
      Returns:
      the operations map.

    • setGlobalContextEntry

      public static void setGlobalContextEntry(String key, String value)
      Set a global entry.
      Parameters:
      key - key
      value - value

    • getGlobalContextEntry

      public static String getGlobalContextEntry(String key)
      Get a global entry.
      Parameters:
      key - key
      Returns:
      value or null

    • removeGlobalContextEntry

      public static void removeGlobalContextEntry(String key)
      Remove a global entry.
      Parameters:
      key - key to clear.

    • noteEntryPoint

      public static void noteEntryPoint(Object tool)
      Add the entry point as a context entry with the key AuditConstants.PARAM_COMMAND if it has not already been recorded. This is called via ToolRunner but may be used at any other entry point.
      Parameters:
      tool - object loaded/being launched.

    • getGlobalContextEntries

      public static Iterable<Map.Entry<String,String>> getGlobalContextEntries()
      Get an iterator over the global entries. Thread safe.
      Returns:
      an iterable to enumerate the values.