Package org.apache.hadoop.fs.store.audit

Interface AuditSpan

All Superinterfaces:
AutoCloseable, Closeable
@Private @Unstable public interface AuditSpan extends Closeable
This is a span created by an AuditSpanSource. An implementation of a span may carry context which can be picked up by the filesystem when activated. Each FS can have one active span per thread. Different filesystem instances SHALL have different active spans (if they support them) A span is activated in a thread when activate() is called. The span stays active in that thread until deactivate() is called. When deactivated in one thread, it MAY still be active in others. There's no explicit "end of span"; this is too hard to manage in terms of API lifecycle. Similarly, there's no stack of spans. Once a span is activated, the previous span is forgotten about. Therefore each FS will need a fallback "inactive span" which will be reverted to on deactivation of any other span.

  • Method Summary

    Modifier and Type
    Method
    Description
    AuditSpan
    activate()
    Make this span active in the current thread.
    default void
    close()
    Close calls deactivate(); subclasses may override but the audit manager's wrapping span will always relay to deactivate() rather than call this method on the wrapped span.
    void
    deactivate()
    Deactivate the span in the current thread.
    String
    getOperationName()
    Get the name of the operation.
    String
    getSpanId()
    Return a span ID which must be unique for all spans within everywhere.
    long
    getTimestamp()
    Timestamp in UTC of span creation.
    default boolean
    isValidSpan()
    Is the span valid?
    default void
    set(String key, String value)
    Set an attribute.

  • Method Details

    • getSpanId

      String getSpanId()
      Return a span ID which must be unique for all spans within everywhere. That effectively means part of the span SHOULD be derived from a UUID. Callers MUST NOT make any assumptions about the actual contents or structure of this string other than the uniqueness.
      Returns:
      a non-empty string

    • getOperationName

      String getOperationName()
      Get the name of the operation.
      Returns:
      the operation name.

    • getTimestamp

      long getTimestamp()
      Timestamp in UTC of span creation.
      Returns:
      timestamp.

    • activate

      AuditSpan activate()
      Make this span active in the current thread.
      Returns:
      the activated span. This is makes it easy to use in try with resources

    • deactivate

      void deactivate()
      Deactivate the span in the current thread.

    • close

      default void close()
      Close calls deactivate(); subclasses may override but the audit manager's wrapping span will always relay to deactivate() rather than call this method on the wrapped span.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • isValidSpan

      default boolean isValidSpan()
      Is the span valid? False == this is a span to indicate unbonded.
      Returns:
      true if this span represents a real operation.

    • set

      default void set(String key, String value)
      Set an attribute. This may or may not be propagated to audit logs.
      Parameters:
      key - attribute name
      value - value