This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 18 Next »

Status Update

Following on from the high level design, this page will provide a more detailed design approach to implement status update logging in the Java broker.

The logging hierarchy identified is not suitable to be directly used by Log4j as there is multiple routes and loops in the graph.

Abstracting the logging is recommended as this will allow us to simply provide Qpid specific optimisations such as providing the log prefix.

This design will cover the following areas:

Test Plan

Logging Configuration

At this stage configuration will be limited to the addition to the main config.xml file of the following option:

<broker>
 ...
  <status-updates>ON</status-updates>
 ...
</broker>

This status-update on setting will be the default value if the section is not included in the configuration file. The setting will be global for all virtualhosts and will be exposed via the management console as logger 'qpid.status' to allow dynamic setting.

The ability to configure more fine grained logging will be investigated here, but will not be implemented in the initial phase.

Status Updates

In the first phase updates only status updates will be provided. Status updates should take the form of general operational logging level, no logging on message delivery path way and No performance impact. The recommendation will be to have these enabled for production use.
e.g. Creation/Destruction events

The status updates can also be used in a second phase to provide additional logging to assist development.
The additional logging can be performed on the message delivery path way. This may have performance impact and so would not be recommended for long term production use.
e.g. Message Enqueue/Dequeue

Logging Abstraction

The abstraction layer allows us to fully decouple the logging mechanism from any operational logging that the broker may wish to perform. The following code highlights show how we would abstract the logging operations.

The approach to logging is that each Entitiy as highlighted on Logging Format Design would provide an implementation of MessageStatusLogger. This logger would be obtained from the MessagesStatusLoggerFactory during the construction of the entity. When a Status event occurred that should be logged a LogActor is required to request the logging. The initial _LogActor_s would be Connection, Channel and Subscription. Later phases would introduce VirtualHost and ManagementConnection. These Actors will initially only be used to provide their log formatted name as per the format design. However, later their details can be used to identify if logging should proceed for that Actor and Entity combination. At this stage selective configurations is not part of this design.

The addition of the LogActor allows for situations such as Binding to have a Connection associated with the Binding. This will allow a Binding create event to be logged like this:

2009-06-29 13:35:10,1234 +0100 MESSAGE [ con:1(guest@127.0.0.1/)/ch:2/ex(amq.direct)/qu(testQueue)/bd(routingKey) ] BND-1001 : Binding Created

rather having no details about how the creation occurred:

2009-06-29 13:35:10,1234 +0100 MESSAGE [ vh(/)/ex(amq.direct)/qu(testQueue)/bd(routingKey) ] BDN-1001 : Binding Created

Interfaces

LogActor

/**
 * LogActor the entity that is requesting the log to be performed.
 *
 * The actor is responsible for providing the formatted name for the log entry.
 *
 */
public interface LogActor
{
    /**
     * Return the String that this actor wishes to be entered into the logfile.
     *
     * @return String
     */
    public String getLogFormattedName();
}
MessageStatusLogger
/**
 * Message Status messages are logged via this interface.
 *
 * Each Entity that wishes to be logged will implement this to provide their
 * own display representation.
 *
 * The MSLogger will be created by a Factory {@see MessageStatusLoggerFactory}.
 *
 * Currently logging has a global setting however this will later be revised and
 * as such the LogActor will need to be taken in to consideration as well as the
 * status of this Logger.
 *
 * A detailed and published list of messages that will be logged will be
 * provided so that monitoring systems can know what to expect.
 */
public interface MessageStatusLogger
{

    /**
     * This method should be used as a guard against expensive message
     * construction prior to calling message().
     *
     * It should not be called if there is no construction required.
     *
     * This will perform validation that the log message should be performed
     * based on the provided Actor and the Entity this Logger represents.
     * This may be done via delegation to the RootMessageStatusLogger.
     *
     * @param actor The actor that is requesting to perform logging
     *
     * @return if this log message should take place
     */
    public boolean isMessageEnabled(LogActor actor);

    /**
     * Logs the message as provided by String.valueOf(message).
     *
     * The call to message() will first check if #isMessageEnabled() allows
     * the logging to be performed. This means for simple messages it is not
     * necessary to guard this call with isMessageEnabled() as it will be called
     * internally.
     *
     * If any complex construction is required then it MUST BE guarded so that
     * the log message is not needlessly generated.
     *
     * @param actor   The actor that is requesting the logging
     * @param message The message to log
     */
    public void message(LogActor actor, Object message);

    /**
     * Logs the message as provided by String.valueOf(message).
     *
     * The call to message() will first check if #isMessageEnabled() allows
     * the logging to be performed. This means for simple messages it is not
     * necessary to guard this call with isMessageEnabled() as it will be called
     * internally.
     *
     * If any complex construction is required then it MUST BE guarded so that
     * the log message is not needlessly generated.
     *
     * If the provided Throwable is non-null then the stack trace will also be
     * logged.
     *
     * @param actor   The actor that is requesting the logging
     * @param message The message to log
     * @param throwable The throwable that should be used to generate a trace.
     */
    public void message(LogActor actor, Object message, Throwable throwable);
}

MessageStatusLoggerFactory
/**
 * This interface provides a means of creating the Loggers that will be required
 * by each of the entities that have a desire to provide status updates.
 *
 * For new entities to support status logging this interface must be updated.
 *
 * All Loggers defer to the RootMessageStatusLogger as to wither the log should
 * take place.
 */
public interface MessageStatusLoggerFactory
{
    public ConnectionMessageStatusLogger createConnectionMessageStatusLogger(AMQProtocolSession connection);

    public ChannelMessageStatusLogger createChannelMessageStatusLogger(AMQChannel channel);

    public QueueMessageStatusLogger createQueueMessageStatusLogger(AMQQueue queue);

    public ExchangeMessageStatusLogger createExchangeMessageStatusLogger(Exchange exchange);

    public BindingMessageStatusLogger createBindingMessageStatusLogger(ExchangeBinding binding);

    public SubscriptionMessageStatusLogger createSubscriptionMessageStatusLogger(Subscription subscription);

    public MessageStoreMessageStatusLogger createMessageStoreMessageStatusLogger(MessageStore store);
}

RootMessageStatusLogger
/**
 * The RootMessageStatusLogger is used by the MessageStatusLoggers to query if
 * logging is enabled for the requested message and to provide the actual
 * message that should be logged.
 */
public interface RootMessageStatusLogger
{
    /**
     * Determin if the MessageStatusLogger and the LogActor should be
     * generating log messages.
     *
     * @param messageStatusLogger The logger performing the logging
     * @param actor               The actor requesting the logging
     * @return boolean true if the message should be logged.
     */
    boolean isMessageEnabled(MessageStatusLogger messageStatusLogger,
                             LogActor actor);

    /**
     * Log the raw message to the configured logger.
     *
     * @param message   The message to log
     * @param throwable Optional Throwable that should provide stact trace
     */
    void rawMessage(String message, Throwable throwable);

    /**
     * Accessor to get the MSLFactory that can then be used to perform logging 
     * @return MessageStatusLoggerFactory 
     */
    MessageStatusLoggerFactory getMessageStatusLoggerFactory();
}

RawMessageLogger
/**
 * A RawMessage Logger takes the given String and any Throwable and writes the
 * data to its resource.
 */
public interface RawMessageLogger
{
    /**
     * Log the message and formatted stack trace for any Throwable.
     *
     * @param message   String to log.
     * @param throwable Throwable for which to provide stack trace.
     */
    public void rawMessage(String message, Throwable throwable);
}

Logging Usage

Logging of a Channel Creation
pubic class Channel
...
    if (_statusLogger.isInfoEnabled(cnnectonLogActor))
    {
        _statusLogger.info(connectonLogActor, LogMessages.CHANNEL_CREATE(this));
    }
...

Would result in the following based on the Logging Format Design.

2009-06-29 13:35:10,1234 +0100 MESSAGE [ con:1(guest@127.0.0.1/)/ch:2 ] ChM-1001 : Channel Created
Logging of a new consumer creation
...
    if (_statusLogger.isInfoEnabled(subscriberActor))
    {
        _statusLogger.info(subscriberActor, LogMessages.SUBSCRIPTION_CREATE(this));
    }
...

Would result in the following:

2009-06-29 13:35:10,1234 +0100 MESSAGE [ con:1(guest@127.0.0.1/)/ch:2/sub:1:qu(myqueue) ] Sub-1001 : Subscription Created

Initial Status Messages

Broker

Startup
Configuration details
Ready
Shutdown

ManagementConsole

Startup
Configuration details
Ready
Close

VirtualHost

Create
Configuration details
Close

MessageStore

Startup
Recover Status
Start
Progress
End
Close

Connection

Open
Close

Channel

Create
Flow Status
Destroy

Queue

Create
Destroy

Exchange

Create
Destroy

Binding

Create
Destroy

Subscription

Create
Destroy

  • No labels