/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.pulsar.structuredeventlog;

import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;

/**
 * Structured Logged Event interface.
 *
 * This interface is used to add context information to the log event and eventually log.
 */
public interface Event {
    /**
     * 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.
     *
     * @return a new child event
     */
    Event newChildEvent();

    /**
     * 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.
     * @param traceId the traceId
     * @return this
     */
    Event traceId(String traceId);

    /**
     * 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.
     * @param parentId the parentId
     * @return this
     */
    Event parentId(String parentId);

    /**
     * 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.
     *
     * <pre>
     * Event e = logger.newRootEvent().timed();
     * // do something that takes time.
     * e.log(Events.SOME_EVENT);
     * </pre>
     *
     * @return this
     */
    Event timed();

    /**
     * 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.
     *
     * @param samplingKey a key by which to scope the rate limiting
     * @param duration the duration for which one event will be logged
     * @param unit the duration unit
     * @return this
     */
    Event sampled(Object samplingKey, int duration, TimeUnit unit);

    /**
     * Add resources for the event from an EventResources object.
     * @see #resource(java.lang.String,java.lang.Object)
     * @return this
     */
    Event resources(EventResources attrs);

    /**
     * Add a resource for the event. Resources are inherited by
     * child events.
     * @param key the key to identify the resource
     * @param value the value which will be logged for the resource.
     *        This is converted to a string before logging.
     * @return this
     */
    Event resource(String key, Object 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.
     * @param key the key to identify the resource
     * @param value a supplier which returns the value to be logged for
     *              this resource
     * @see #resource(java.lang.String,java.lang.Object)
     */
    Event resource(String key, Supplier<String> value);

    /**
     * Add an attribute for the event. Attributes are not inherited
     * by child events.
     * @param key the key to identify the attribute
     * @param value the value which will be logged for the attribute.
     *        This is converted to a string, using Object#toString() before logging.
     * @return this
     */
    Event attr(String key, Object value);

    /**
     * Add an attribute for the event using a supplier.
     * @param key the key to identify the attribute
     * @param value a supplier which returns the value to be logged for
     *              this attribute
     * @return this
     */
    Event attr(String key, Supplier<String> value);

    /**
     * Attach an exception to the event.
     * @param t the exception
     * @return this
     */
    Event exception(Throwable t);

    /**
     * Log this event at the error level.
     * @return this
     */
    Event atError();

    /**
     * Log this event at the info level (the default).
     * @return this
     */
    Event atInfo();

    /**
     * Log this event at the warn level.
     * @return this
     */
    Event atWarn();

    /**
     * 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.
     * @param event the event message, in enum form
     */
    void log(Enum<?> event);

    /**
     * Log the event, using a string.
     * @param event the event message.
     */
    void log(String event);

    /**
     * Stash this log event to bridge across an unmodifiable API call.
     * @see StructuredEventLog#unstash()
     */
    void stash();
}