org.apache.pulsar.structuredeventlog

Interface Event

public interface Event

Structured Logged Event interface. This interface is used to add context information to the log event and eventually log.

Method Summary

Modifier and Type	Method and Description
Event	atError() Log this event at the error level.
Event	atInfo() Log this event at the info level (the default).
Event	attr(String key, Object value) Add an attribute for the event.
Event	attr(String key, Supplier<String> value) Add an attribute for the event using a supplier.
Event	atWarn() Log this event at the warn level.
Event	exception(Throwable t) Attach an exception to the event.
void	log(Enum<?> event) Log the event, using an enum as the message.
void	log(String event) Log the event, using a string.
Event	newChildEvent() Create a new child event.
Event	parentId(String parentId) Set the parent ID of the event.
Event	resource(String key, Object value) Add a resource for the event.
Event	resource(String key, Supplier<String> value) Add a resource for the event using a supplier.
Event	resources(EventResources attrs) Add resources for the event from an EventResources object.
Event	sampled(Object samplingKey, int duration, TimeUnit unit) Mark this event as sampled.
void	stash() Stash this log event to bridge across an unmodifiable API call.
Event	timed() Mark this event as timed.
Event	traceId(String traceId) Set the trace ID of the event.

Method Detail

newChildEvent

Event newChildEvent()

Create a new child event. The child event will inherit the trace ID of the event from which it was created. The child event parentId will be the ID of the event from which it was created. The child will inherit resources from its parent event, but not attributes.

Returns:

a new child event

traceId

Event traceId(String traceId)

Set the trace ID of the event. Normally this will be inherited from the parent event. In the case of a root event, the trace ID will be automatically generated. This method only needs to be used if a traceID has been received from elsewhere, such as from a user request.

Parameters:

traceId - the traceId

Returns:

this

parentId

Event parentId(String parentId)

Set the parent ID of the event. Normally this is set automatically for child events. For root events, it is normally empty unless provided by some other means, such as via a user request.

Parameters:

parentId - the parentId

Returns:

this

timed

Event timed()

Mark this event as timed. Timed events will measure the duration between #timed() being called and logged being called. The duration will be in milliseconds.

 Event e = logger.newRootEvent().timed();
 // do something that takes time.
 e.log(Events.SOME_EVENT);
 

Returns:

this

sampled

Event sampled(Object samplingKey,
              int duration,
              TimeUnit unit)

Mark this event as sampled. Sampled events will only log once per specified duration. The sampling key is used to scope the rate limit. All events using the same sampling key will observe the same rate limit. Sampled events are most useful in the data plane, where, if there is an error for one event, there's likely to be a lot of other events which are almost identical.

Parameters:

samplingKey - a key by which to scope the rate limiting

duration - the duration for which one event will be logged

unit - the duration unit

Returns:

this

resources

Event resources(EventResources attrs)

Add resources for the event from an EventResources object.

Returns:

this

See Also:

resource(java.lang.String,java.lang.Object)

resource

Event resource(String key,
               Object value)

Add a resource for the event. Resources are inherited by child events.

Parameters:

key - the key to identify the resource

value - the value which will be logged for the resource. This is converted to a string before logging.

Returns:

this

resource

Event resource(String key,
               Supplier<String> value)

Add a resource for the event using a supplier. The supplier is used in the case that generating the string from the object is expensive or we want to generate a custom string.

Parameters:

key - the key to identify the resource

value - a supplier which returns the value to be logged for this resource

See Also:

resource(java.lang.String,java.lang.Object)

attr

Event attr(String key,
           Object value)

Add an attribute for the event. Attributes are not inherited by child events.

Parameters:

key - the key to identify the attribute

value - the value which will be logged for the attribute. This is converted to a string, using Object#toString() before logging.

Returns:

this

attr

Event attr(String key,
           Supplier<String> value)

Add an attribute for the event using a supplier.

Parameters:

key - the key to identify the attribute

value - a supplier which returns the value to be logged for this attribute

Returns:

this

exception

Event exception(Throwable t)

Attach an exception to the event.

Parameters:

t - the exception

Returns:

this

atError

Event atError()

Log this event at the error level.

Returns:

this

atInfo

Event atInfo()

Log this event at the info level (the default).

Returns:

this

atWarn

Event atWarn()

Log this event at the warn level.

Returns:

this

log

void log(Enum<?> event)

Log the event, using an enum as the message. Logging with a enum allows documentation and annotations, such as subcomponent to be attached to the message.

Parameters:

event - the event message, in enum form

log

void log(String event)

Log the event, using a string.

Parameters:

event - the event message.

stash

void stash()

Stash this log event to bridge across an unmodifiable API call.

See Also:

StructuredEventLog.unstash()