Apama API Reference for .NET  9.9.0.0
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties Events
Apama.Util.Logger Class Reference

The Logger class provides access to the logging functionality used by Apama .NET classes. More...

Public Member Functions

void Crit (string msg, params object[] args)
 Logs the specified message at CRIT level. More...
 
void Crit (string msg, Exception ex, params object[] args)
 Logs the specified message at CRIT level, followed by a stack trace for the exception. More...
 
virtual bool CritEnabled ()
 Determines if the logging is enabled at the CRIT level for this Logger instance. More...
 
void Debug (string msg, params object[] args)
 Logs the specified message at DEBUG level. More...
 
void Debug (string msg, Exception ex, params object[] args)
 Logs the specified message at DEBUG level, followed by a stack trace for the exception. More...
 
virtual bool DebugEnabled ()
 Determines if the logging is enabled at the DEBUG level for this Logger instance. More...
 
void Error (string msg, params object[] args)
 Logs the specified message at ERROR level. More...
 
void Error (string msg, Exception ex, params object[] args)
 Logs the specified message at ERROR level, followed by a stack trace for the exception. More...
 
virtual bool ErrorEnabled ()
 Determines if the logging is enabled at the ERROR level for this Logger instance. More...
 
void ErrorWithDebugStackTrace (string msg, Exception ex, params object[] args)
 Logs the specified message at ERROR level followed by the exception's message string, and then logs the exception's stack trace at DEBUG level. More...
 
void Fatal (string msg, params object[] args)
 Logs the specified message at FATAL level. More...
 
void Fatal (string msg, Exception ex, params object[] args)
 Logs the specified message at FATAL level, followed by a stack trace for the exception. More...
 
virtual bool FatalEnabled ()
 Determines if the logging is enabled at the FATAL level for this Logger instance. More...
 
void Force (string msg, params object[] args)
 Logs the specified message at FORCE level. More...
 
void Force (string msg, Exception ex, params object[] args)
 Logs the specified message at FORCE level, followed by a stack trace for the exception. More...
 
virtual bool ForceEnabled ()
 Determines if the logging is enabled at the FORCE level for this Logger instance. More...
 
void Info (string msg, params object[] args)
 Logs the specified message at INFO level. More...
 
void Info (string msg, Exception ex, params object[] args)
 Logs the specified message at INFO level, followed by a stack trace for the exception. More...
 
virtual bool InfoEnabled ()
 Determines if the logging is enabled at the INFO level for this Logger instance. More...
 
void SetThreshold (LogLevel level)
 Sets the logging threshold for this instance of Logger. More...
 
void Warn (string msg, params object[] args)
 Logs the specified message at WARN level. More...
 
void Warn (string msg, Exception ex, params object[] args)
 Logs the specified message at WARN level, followed by a stack trace for the exception. More...
 
virtual bool WarnEnabled ()
 Determines if the logging is enabled at the WARN level for this Logger instance. More...
 
void WarnWithDebugStackTrace (string msg, Exception ex, params object[] args)
 Logs the specified message at WARN level followed by the exception's message string, and then logs the exception's stack trace at DEBUG level. More...
 

Static Public Member Functions

static Logger GetLogger ()
 Factory method - use to get the default instance of a logger. More...
 
static Logger GetLogger (string name)
 Factory method - use to get an instance of a logger. More...
 
static Logger GetLogger (Type cls)
 Factory method - use to get an instance of a logger. This method is eqivalent to calling More...
 

Public Attributes

const string BaseLogFileConfigName = "baseLogFile"
 Constant that provides the name of the config file property that is used to configure the log file for the client C++ layer. The value is baseLogFile. More...
 
const string BaseLogFilePropertyName = "APAMA_BASE_LOG_FILE"
 Constant that provides the name of the environment variable that is used to configure the log file for the client C++ layer. The value is APAMA_BASE_LOG_FILE. More...
 
const string BaseLogLevelConfigName = "baseLogLevel"
 Constant that provides the name of the config file property that is used to configure the default log level for the client C++ layer. The value is baseLogLevel More...
 
const string BaseLogLevelPropertyName = "APAMA_BASE_LOG_LEVEL"
 Constant that provides the name of the environment variable that is used to configure the default log level for the client C++ layer. The value is APAMA_BASE_LOG_LEVEL. More...
 
const string BaseLogTruncateConfigName = "baseTruncate"
 Constant that provides the name of the config file property that is used to configure whether to truncate logs for the client C++ layer. The value is baseTruncate. More...
 
const string BaseLogTruncatePropertyName = "APAMA_BASE_LOG_TRUNCATE"
 Constant that provides the name of the environment variable that is used to configure whether to truncate logs for the client C++ layer. The value is APAMA_BASE_LOG_TRUNCATE. More...
 
const LogLevel DefaultBaseLogLevel = LogLevel.ErrorLevel
 Constant that provides the default log level for the base layer. The value is ERROR. More...
 
const string DefaultLogFileName = null
 Constant that provides the default log filename. Currently the value is null. More...
 
const LogLevel DefaultLogLevel = LogLevel.WarnLevel
 Constant that provides the default log level. The value is WARN. More...
 
const string LogFileNameConfigName = "logFile"
 Constant that provides the name of the config file property that is used to configure the default log output destination. The value is logFile. More...
 
const string LogFileNamePropertyName = "APAMA_LOG_FILE"
 Constant that provides the name of the environment variable that is used to configure the default log output destination. The value is APAMA_LOG_FILE. More...
 
const string LogImplementationConfigName = "loggerImpl"
 Constant that provides the name of the config file property that is used to configure the logger implementation used. The value is loggerImpl. More...
 
const string LogImplementationPropertyName = "APAMA_LOG_IMPL"
 Constant that provides the name of the environment variable that is used to configure the logger implementation used. The value is APAMA_LOG_IMPL. More...
 
const string LogLevelConfigName = "logLevel"
 Constant that provides the name of the config file property that is used to configure the default log level. The value is logLevel. More...
 
const string LogLevelPropertyName = "APAMA_LOG_LEVEL"
 Constant that provides the name of the environment variable that is used to configure the default log level. The value is normally APAMA_LOG_LEVEL. More...
 
const string LogTruncateConfigName = "truncate"
 Constant that provides the name of the config file property that is used to configure whether to truncate logs. The value is truncate. More...
 
const string LogTruncatePropertyName = "APAMA_LOG_TRUNCATE"
 Constant that provides the name of the environment variable that is used to configure whether to truncate logs. The value is APAMA_LOG_TRUNCATE. More...
 

Static Public Attributes

static readonly String VersionComment = "Apama Platform Version: " + Versions.BuildNumber
 This is the string that is logged for the Version. More...
 

Properties

static Type LoggerType [get, set]
 The current logger type. More...
 

Detailed Description

The Logger class provides access to the logging functionality used by Apama .NET classes.

An instance of the Logger can be obtained by using one of the GetLogger() static factory methods.

The Logger is configurable: implementation of the Logger can be specified and the log level and filename can be configured.

This is done by either using Environment Variables (with the PropertyName constants, e.g. Logger.LogFileNamePropertyName), or alternatively you can specify configuration settings in a standard .NET Application Configuration File (with the ConfigName constants, e.g. Logger.LogFileNameConfigName, which are used in a config file with a "Apama.Util.Logger" DictionarySectionHandler; see Microsoft documentation for more details on the configuration format). Note that Environment Variables override configuration file settings.

When using Log4Net most of the configuration is specified in a Log4Net configuration file.

Member Function Documentation

void Apama.Util.Logger.Crit ( string  msg,
params object[]  args 
)

Logs the specified message at CRIT level.

void Apama.Util.Logger.Crit ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at CRIT level, followed by a stack trace for the exception.

virtual bool Apama.Util.Logger.CritEnabled ( )
virtual

Determines if the logging is enabled at the CRIT level for this Logger instance.

void Apama.Util.Logger.Debug ( string  msg,
params object[]  args 
)

Logs the specified message at DEBUG level.

void Apama.Util.Logger.Debug ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at DEBUG level, followed by a stack trace for the exception.

virtual bool Apama.Util.Logger.DebugEnabled ( )
virtual

Determines if the logging is enabled at the DEBUG level for this Logger instance.

void Apama.Util.Logger.Error ( string  msg,
params object[]  args 
)

Logs the specified message at ERROR level.

Note that if an error is being logged because an exception was caught, users are strongly discouraged from calling this method and logging the exception object (or its Message) using the msg string argument. Instead, call Logger.Error(string,Exception, object[]) or ErrorWithDebugStackTrace so that all of the valuable diagnostic information from the exception object is available in the log.

void Apama.Util.Logger.Error ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at ERROR level, followed by a stack trace for the exception.

Unlike the more performance-critical ErrorWithDebugStackTrace(string,Exception,object[]), this method always logs the stack trace at ERROR level, which provides useful diagnostic information but can result in the log file becoming more cluttered.

  • Callers are encouraged to use this method if the code that can throw the exception is executed only rarely or once per process (such as startup or connection-establishing code)

    • to ensure that the useful information provided in the stack trace is always available to help track down problems, even if DEBUG logging has not been enabled.

  • However it is best to use ErrorWithDebugStackTrace(string,Exception,object[]) in code paths that are executed very frequently (such as code within a message processing loop)
    • to avoid cluttering the log with lots of long stack traces if many errors occur, which would reduce performance and readability.
See also
ErrorWithDebugStackTrace
virtual bool Apama.Util.Logger.ErrorEnabled ( )
virtual

Determines if the logging is enabled at the ERROR level for this Logger instance.

void Apama.Util.Logger.ErrorWithDebugStackTrace ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at ERROR level followed by the exception's message string, and then logs the exception's stack trace at DEBUG level.

This method is more appropriate for performance-critical code than Error(string,Exception,object[]), because it does not log the stack trace unless DEBUG level logging has been enabled.

  • Callers are encouraged to use this method in code paths that are executed very frequently (such as code within a message processing loop)

    • to avoid cluttering the log with lots of long stack traces if many errors occur, which would reduce performance and readability.

  • However it is best to use Error(string,Exception,object[]) when the code that can throw the exception is executed only rarely or once per process (such as startup or connection-establishing code)
    • to ensure that the useful information provided in the stack trace is always available to help track down problems, even if DEBUG logging has not been enabled.
Parameters
msgThe message to be logged. Information from the exception object will be automatically appended to the end of this message, so it is recommended that msg ends with a colon and space, i.e. ": ".
exThe exception object associated with this error.
argsOptional list of arguments used to format msg.
See also
Logger.Error(string,Exception,object[])
void Apama.Util.Logger.Fatal ( string  msg,
params object[]  args 
)

Logs the specified message at FATAL level.

void Apama.Util.Logger.Fatal ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at FATAL level, followed by a stack trace for the exception.

virtual bool Apama.Util.Logger.FatalEnabled ( )
virtual

Determines if the logging is enabled at the FATAL level for this Logger instance.

void Apama.Util.Logger.Force ( string  msg,
params object[]  args 
)

Logs the specified message at FORCE level.

void Apama.Util.Logger.Force ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at FORCE level, followed by a stack trace for the exception.

virtual bool Apama.Util.Logger.ForceEnabled ( )
virtual

Determines if the logging is enabled at the FORCE level for this Logger instance.

static Logger Apama.Util.Logger.GetLogger ( )
static

Factory method - use to get the default instance of a logger.

static Logger Apama.Util.Logger.GetLogger ( string  name)
static

Factory method - use to get an instance of a logger.

static Logger Apama.Util.Logger.GetLogger ( Type  cls)
static

Factory method - use to get an instance of a logger. This method is eqivalent to calling

GetLogger( cls.FullName )

void Apama.Util.Logger.Info ( string  msg,
params object[]  args 
)

Logs the specified message at INFO level.

void Apama.Util.Logger.Info ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at INFO level, followed by a stack trace for the exception.

virtual bool Apama.Util.Logger.InfoEnabled ( )
virtual

Determines if the logging is enabled at the INFO level for this Logger instance.

void Apama.Util.Logger.SetThreshold ( LogLevel  level)

Sets the logging threshold for this instance of Logger.

Parameters
level
void Apama.Util.Logger.Warn ( string  msg,
params object[]  args 
)

Logs the specified message at WARN level.

Note that if a warning is being logged because an exception was caught, users are strongly discouraged from calling this method and logging the exception object (or its Message) using the msg string argument. Instead, call Logger.Warn(string,Exception, object[]) or WarnWithDebugStackTrace so that all of the valuable diagnostic information from the exception object is available in the log.

void Apama.Util.Logger.Warn ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at WARN level, followed by a stack trace for the exception.

Unlike the more performance-critical WarnWithDebugStackTrace(string,Exception,object[]), this method always logs the stack trace at WARN level, which provides useful diagnostic information but can result in the log file becoming more cluttered.

  • Callers are encouraged to use this method if the code that can throw the exception is executed only rarely or once per process (such as startup or connection-establishing code)

    • to ensure that the useful information provided in the stack trace is always available to help track down problems, even if DEBUG logging has not been enabled.

  • However it is best to use WarnWithDebugStackTrace(string,Exception,object[]) in code paths that are executed very frequently (such as code within a message processing loop)
    • to avoid cluttering the log with lots of long stack traces if many warnings occur, which would reduce performance and readability.
See also
WarnWithDebugStackTrace
virtual bool Apama.Util.Logger.WarnEnabled ( )
virtual

Determines if the logging is enabled at the WARN level for this Logger instance.

void Apama.Util.Logger.WarnWithDebugStackTrace ( string  msg,
Exception  ex,
params object[]  args 
)

Logs the specified message at WARN level followed by the exception's message string, and then logs the exception's stack trace at DEBUG level.

This method is more appropriate for performance-critical code than Warn(string,Exception,object[]), because it does not log the stack trace unless DEBUG level logging has been enabled.

  • Callers are encouraged to use this method in code paths that are executed very frequently (such as code within a message processing loop)

    • to avoid cluttering the log with lots of long stack traces if many warnings occur, which would reduce performance and readability.

  • However it is best to use Warn(string,Exception,object[]) when the code that can throw the exception is executed only rarely or once per process (such as startup or connection-establishing code)
    • to ensure that the useful information provided in the stack trace is always available to help track down problems, even if DEBUG logging has not been enabled.
Parameters
msgThe message to be logged. Information from the exception object will be automatically appended to the end of this message, so it is recommended that msg ends with a colon and space, i.e. ": ".
exThe exception object associated with this warning.
argsOptional list of arguments used to format msg.
See also
Logger.Warn(string,Exception,object[])

Member Data Documentation

const string Apama.Util.Logger.BaseLogFileConfigName = "baseLogFile"

Constant that provides the name of the config file property that is used to configure the log file for the client C++ layer. The value is baseLogFile.

const string Apama.Util.Logger.BaseLogFilePropertyName = "APAMA_BASE_LOG_FILE"

Constant that provides the name of the environment variable that is used to configure the log file for the client C++ layer. The value is APAMA_BASE_LOG_FILE.

const string Apama.Util.Logger.BaseLogLevelConfigName = "baseLogLevel"

Constant that provides the name of the config file property that is used to configure the default log level for the client C++ layer. The value is baseLogLevel

const string Apama.Util.Logger.BaseLogLevelPropertyName = "APAMA_BASE_LOG_LEVEL"

Constant that provides the name of the environment variable that is used to configure the default log level for the client C++ layer. The value is APAMA_BASE_LOG_LEVEL.

const string Apama.Util.Logger.BaseLogTruncateConfigName = "baseTruncate"

Constant that provides the name of the config file property that is used to configure whether to truncate logs for the client C++ layer. The value is baseTruncate.

const string Apama.Util.Logger.BaseLogTruncatePropertyName = "APAMA_BASE_LOG_TRUNCATE"

Constant that provides the name of the environment variable that is used to configure whether to truncate logs for the client C++ layer. The value is APAMA_BASE_LOG_TRUNCATE.

const LogLevel Apama.Util.Logger.DefaultBaseLogLevel = LogLevel.ErrorLevel

Constant that provides the default log level for the base layer. The value is ERROR.

const string Apama.Util.Logger.DefaultLogFileName = null

Constant that provides the default log filename. Currently the value is null.

const LogLevel Apama.Util.Logger.DefaultLogLevel = LogLevel.WarnLevel

Constant that provides the default log level. The value is WARN.

const string Apama.Util.Logger.LogFileNameConfigName = "logFile"

Constant that provides the name of the config file property that is used to configure the default log output destination. The value is logFile.

const string Apama.Util.Logger.LogFileNamePropertyName = "APAMA_LOG_FILE"

Constant that provides the name of the environment variable that is used to configure the default log output destination. The value is APAMA_LOG_FILE.

const string Apama.Util.Logger.LogImplementationConfigName = "loggerImpl"

Constant that provides the name of the config file property that is used to configure the logger implementation used. The value is loggerImpl.

const string Apama.Util.Logger.LogImplementationPropertyName = "APAMA_LOG_IMPL"

Constant that provides the name of the environment variable that is used to configure the logger implementation used. The value is APAMA_LOG_IMPL.

const string Apama.Util.Logger.LogLevelConfigName = "logLevel"

Constant that provides the name of the config file property that is used to configure the default log level. The value is logLevel.

const string Apama.Util.Logger.LogLevelPropertyName = "APAMA_LOG_LEVEL"

Constant that provides the name of the environment variable that is used to configure the default log level. The value is normally APAMA_LOG_LEVEL.

const string Apama.Util.Logger.LogTruncateConfigName = "truncate"

Constant that provides the name of the config file property that is used to configure whether to truncate logs. The value is truncate.

const string Apama.Util.Logger.LogTruncatePropertyName = "APAMA_LOG_TRUNCATE"

Constant that provides the name of the environment variable that is used to configure whether to truncate logs. The value is APAMA_LOG_TRUNCATE.

readonly String Apama.Util.Logger.VersionComment = "Apama Platform Version: " + Versions.BuildNumber
static

This is the string that is logged for the Version.

Property Documentation

Type Apama.Util.Logger.LoggerType
staticgetset

The current logger type.

Submit a bug or feature
Copyright (c) 2013-2015 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG.