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

Interface AuditSpan

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

@Private
@Unstable
public interface AuditSpan
extends java.io.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.
java.lang.String	getOperationName()	Get the name of the operation.
java.lang.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? False == this is a span to indicate unbonded.
default void	set(java.lang.String key, java.lang.String value)	Set an attribute.

Method Detail

getSpanId

java.lang.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

java.lang.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 java.lang.AutoCloseable

Specified by:

close in interface java.io.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(java.lang.String key,
                 java.lang.String value)

Set an attribute. This may or may not be propagated to audit logs.

Parameters:

key - attribute name

value - value