Package 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 Details

    • 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

      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:

    • 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: