Class Destination

Represents logging message destination - an abstract entity that messages are written to by LogService. Destinations must be efficient as they block logger thread. They provide failover mechanism when processing can not be completed. Once failed, the processing can try to be resumed after configurable interval. Destinations also provide optional SLA on the time it takes to perform actual message write - once exceeded destination is considered to have failed. Basic efficient filtering is provided for times, dates and levels. Complex C# expression-based filtering is also supported

Inheritance
System.Object
DisposableObject
ApplicationComponent
Destination
CompositeDestination
ConsoleDestination
FileDestination
LogServiceDestination
MemoryBufferDestination
MongoDBDestination
NullDestination
SMTPDestination
SyslogDestination
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: NFX.Log.Destinations
Assembly: NFX.dll
Syntax
public abstract class Destination : ApplicationComponent, IApplicationComponent, IDisposable, IConfigurable, IExternallyParameterized

Constructors

Destination()

Declaration
public Destination()

Destination(String)

Declaration
public Destination(string name)
Parameters
Type Name Description
System.String name

Fields

After

Allows to insert a destination right after this one

Declaration
public volatile Destination After
Field Value
Type Description
Destination

Before

Allows to insert a destination right before this one

Declaration
public volatile Destination Before
Field Value
Type Description
Destination

CONFIG_DAYS_OF_WEEK_ATTR

Declaration
public const string CONFIG_DAYS_OF_WEEK_ATTR = "days-of-week"
Field Value
Type Description
System.String

CONFIG_END_DATE_ATTR

Declaration
public const string CONFIG_END_DATE_ATTR = "end-date"
Field Value
Type Description
System.String

CONFIG_END_TIME_ATTR

Declaration
public const string CONFIG_END_TIME_ATTR = "end-time"
Field Value
Type Description
System.String

CONFIG_FAILOVER_ATTR

Declaration
public const string CONFIG_FAILOVER_ATTR = "failover"
Field Value
Type Description
System.String

CONFIG_FILTER_ATTR

Declaration
public const string CONFIG_FILTER_ATTR = "filter"
Field Value
Type Description
System.String

CONFIG_GENERATE_FAILOVER_MSG_ATTR

Declaration
public const string CONFIG_GENERATE_FAILOVER_MSG_ATTR = "generate-failover-msg"
Field Value
Type Description
System.String

CONFIG_LEVELS_ATTR

Declaration
public const string CONFIG_LEVELS_ATTR = "levels"
Field Value
Type Description
System.String

CONFIG_MAX_LEVEL_ATTR

Declaration
public const string CONFIG_MAX_LEVEL_ATTR = "max-level"
Field Value
Type Description
System.String

CONFIG_MAX_PROCESSING_TIME_MS_ATTR

Declaration
public const string CONFIG_MAX_PROCESSING_TIME_MS_ATTR = "max-processing-time-ms"
Field Value
Type Description
System.String

CONFIG_MAX_PROCESSING_TIME_MS_MIN_VALUE

Declaration
public const int CONFIG_MAX_PROCESSING_TIME_MS_MIN_VALUE = 25
Field Value
Type Description
System.Int32

CONFIG_MIN_LEVEL_ATTR

Declaration
public const string CONFIG_MIN_LEVEL_ATTR = "min-level"
Field Value
Type Description
System.String

CONFIG_NAME_ATTR

Declaration
public const string CONFIG_NAME_ATTR = "name"
Field Value
Type Description
System.String

CONFIG_NAME_DEFAULT

Declaration
public const string CONFIG_NAME_DEFAULT = "Un-named log destination"
Field Value
Type Description
System.String

CONFIG_ONLY_FAILURES_ATTR

Declaration
public const string CONFIG_ONLY_FAILURES_ATTR = "only-failures"
Field Value
Type Description
System.String

CONFIG_RESTART_PROCESSING_AFTER_MS_ATTR

Declaration
public const string CONFIG_RESTART_PROCESSING_AFTER_MS_ATTR = "restart-processing-after-ms"
Field Value
Type Description
System.String

CONFIG_RESTART_PROCESSING_AFTER_MS_DEFAULT

Declaration
public const int CONFIG_RESTART_PROCESSING_AFTER_MS_DEFAULT = 60000
Field Value
Type Description
System.Int32

CONFIG_START_DATE_ATTR

Declaration
public const string CONFIG_START_DATE_ATTR = "start-date"
Field Value
Type Description
System.String

CONFIG_START_TIME_ATTR

Declaration
public const string CONFIG_START_TIME_ATTR = "start-time"
Field Value
Type Description
System.String

CONFIG_TEST_ON_START_ATTR

Declaration
public const string CONFIG_TEST_ON_START_ATTR = "test-on-start"
Field Value
Type Description
System.String

m_Name

Declaration
protected string m_Name
Field Value
Type Description
System.String

m_Owner

Declaration
protected CompositeDestination m_Owner
Field Value
Type Description
CompositeDestination

PROCESSING_TIME_EMA_FILTER

Defines how much smoothing the processing time filter does - the lower the number the more smoothing is done. Smoothing makes MaxProcessingTimeMs detection insensitive to some seldom delays that may happen every now and then while destination performs actual write into its sink

Declaration
public const float PROCESSING_TIME_EMA_FILTER = 0.0007F
Field Value
Type Description
System.Single

Properties

AverageProcessingTimeMs

Returns average time it takes destination implementation to write the log message to actual sink. This property is only computed when MaxProcessingTimeMs limit is imposed, otherwise it returns 0f

Declaration
public float AverageProcessingTimeMs { get; }
Property Value
Type Description
System.Single

Channel

Declaration
[Config]
[ExternalParameter(new string[]{"log"})]
public string Channel { get; set; }
Property Value
Type Description
System.String

DaysOfWeek

Imposes a filter on days when this destination handles messages

Declaration
[Config("$days-of-week")]
[ExternalParameter(new string[]{"log"})]
public DaysOfWeek? DaysOfWeek { get; set; }
Property Value
Type Description
System.Nullable<DaysOfWeek>

DirectorLog

Declaration
public LogServiceBase DirectorLog { get; }
Property Value
Type Description
LogServiceBase

EndDate

Imposes a filter that specifies the ending date and time before which this destination will be processing log messages

Declaration
[Config("$end-date")]
[ExternalParameter(new string[]{"log"})]
public DateTime? EndDate { get; set; }
Property Value
Type Description
System.Nullable<System.DateTime>

EndTime

Imposes a filter that specifies the ending time of the day before which this destination will be processing log messages

Declaration
[Config("$end-time")]
[ExternalParameter(new string[]{"log"})]
public TimeSpan? EndTime { get; set; }
Property Value
Type Description
System.Nullable<System.TimeSpan>

ExternalParameters

Returns named parameters that can be used to control this component

Declaration
public virtual IEnumerable<KeyValuePair<string, Type>> ExternalParameters { get; }
Property Value
Type Description
System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<System.String, System.Type>>

Failover

Sets destination name used for failover of this one

Declaration
[Config("$failover")]
[ExternalParameter(new string[]{"log"})]
public string Failover { get; set; }
Property Value
Type Description
System.String

Filter

Gets/sets filter expression for this destination. Filter expressions get dynamically compiled into filter assembly, consequently it is not a good practice to create too many different filters. Filters are heavyweight, and it is advisable to use them ONLY WHEN regular destination filtering (using Min/Max levels, dates and times) can not be used to achieve the desired result

Declaration
public MessageFilterExpression Filter { get; set; }
Property Value
Type Description
MessageFilterExpression

FilterMethod

References message filtering method or null

Declaration
public MessageFilterHandler FilterMethod { get; set; }
Property Value
Type Description
MessageFilterHandler

GenerateFailoverMessages

Determines whether additional co-related error message should be generated when this destination fails or when it is used as failover by some other destination. When this property is true an additional error message gets written into failover destination that describes what message caused failure (error is co-related to original) at what destination. False by default.

Declaration
[Config("$generate-failover-msg")]
[ExternalParameter(new string[]{"log"})]
public bool GenerateFailoverMessages { get; set; }
Property Value
Type Description
System.Boolean

LastError

Returns last error that this destination has encountered

Declaration
public Exception LastError { get; }
Property Value
Type Description
System.Exception

Levels

Declaration
public Destination.LevelsList Levels { get; set; }
Property Value
Type Description
Destination.LevelsList

MaxLevel

Imposes a maximum log level constraint

Declaration
[Config("$max-level")]
[ExternalParameter(new string[]{"log"})]
public MessageType? MaxLevel { get; set; }
Property Value
Type Description
System.Nullable<MessageType>

MaxProcessingTimeMs

Imposes a time limit on internal message processing (writing into actual sink) by this destination. If this limit is exceeded, this destination fails and processing is re-tried to be resumed after RestartProcessingAfterMs interval. The minimum value for this property is 25 ms as lower values compromise timer accuracy

Declaration
[Config("$max-processing-time-ms")]
[ExternalParameter(new string[]{"log"})]
public int ? MaxProcessingTimeMs { get; set; }
Property Value
Type Description
System.Nullable<System.Int32>

MinLevel

Imposes a minimum log level constraint

Declaration
[Config("$min-level")]
[ExternalParameter(new string[]{"log"})]
public MessageType? MinLevel { get; set; }
Property Value
Type Description
System.Nullable<MessageType>

Name

Provides mnemonic destination name

Declaration
[Config("$name", "Un-named log destination")]
public string Name { get; set; }
Property Value
Type Description
System.String

OnlyFailures

Indicates whether this destination should only process failures - messages that crashed other destinations. When set to true regular messages (dispatched by Send(msg)) are ignored

Declaration
[Config("$only-failures")]
[ExternalParameter(new string[]{"log"})]
public bool OnlyFailures { get; set; }
Property Value
Type Description
System.Boolean

Owner

Returns a composite destination that ownes this destination or null

Declaration
public CompositeDestination Owner { get; }
Property Value
Type Description
CompositeDestination

RestartProcessingAfterMs

Specifies how much time must pass before processing will be tried to resume after failure. The default value is 60000 ms

Declaration
[Config("$restart-processing-after-ms")]
[ExternalParameter(new string[]{"log"})]
public int RestartProcessingAfterMs { get; set; }
Property Value
Type Description
System.Int32

Service

References a log service that this destination services

Declaration
public LogServiceBase Service { get; }
Property Value
Type Description
LogServiceBase

StartDate

Imposes a filter that specifies the starting date and time after which this destination will start processing log messages

Declaration
[Config("$start-date")]
[ExternalParameter(new string[]{"log"})]
public DateTime? StartDate { get; set; }
Property Value
Type Description
System.Nullable<System.DateTime>

StartTime

Imposes a filter that specifies the starting time of the day after which this destination will start processing log messages

Declaration
[Config("$start-time")]
[ExternalParameter(new string[]{"log"})]
public TimeSpan? StartTime { get; set; }
Property Value
Type Description
System.Nullable<System.TimeSpan>

TestOnStart

Indicates whether this destination should try to test the underlying sink on startup. For example DB-based destinations will try to connect to server upon log service launch when this property is true

Declaration
[Config("$test-on-start")]
public bool TestOnStart { get; set; }
Property Value
Type Description
System.Boolean

Methods

Close()

Deactivates destination

Declaration
public virtual void Close()

Configure(IConfigSectionNode)

Configures specified destination

Declaration
public void Configure(IConfigSectionNode fromNode)
Parameters
Type Name Description
IConfigSectionNode fromNode

Destructor()

Declaration
protected override void Destructor()
Overrides

DoConfigure(IConfigSectionNode)

Override to perform derivative-specific configuration

Declaration
protected virtual void DoConfigure(IConfigSectionNode node)
Parameters
Type Name Description
IConfigSectionNode node

DoPulse()

Provides periodic notification of destinations from central Log thread even if there are no messages to write. Override to commit internal batching buffers provided by particular destinations

Declaration
protected virtual void DoPulse()

DoSend(Message)

Performs physical send, i.e. storage in file for FileDestinations

Declaration
protected abstract void DoSend(Message entry)
Parameters
Type Name Description
Message entry

ExternalGetParameter(String, out Object, String[])

Gets external parameter value returning true if parameter was found

Declaration
public virtual bool ExternalGetParameter(string name, out object value, params string[] groups)
Parameters
Type Name Description
System.String name
System.Object value
System.String[] groups
Returns
Type Description
System.Boolean

ExternalParametersForGroups(String[])

Returns named parameters that can be used to control this component

Declaration
public virtual IEnumerable<KeyValuePair<string, Type>> ExternalParametersForGroups(params string[] groups)
Parameters
Type Name Description
System.String[] groups
Returns
Type Description
System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<System.String, System.Type>>

ExternalSetParameter(String, Object, String[])

Sets external parameter value returning true if parameter was found and set

Declaration
public virtual bool ExternalSetParameter(string name, object value, params string[] groups)
Parameters
Type Name Description
System.String name
System.Object value
System.String[] groups
Returns
Type Description
System.Boolean

Open()

Activates destination by preparing it to start operation

Declaration
public virtual void Open()

ParseLevels(String)

Parses levels into a tuple list of level ranges

Declaration
public static Destination.LevelsList ParseLevels(string levels)
Parameters
Type Name Description
System.String levels

String representation of levels using ',' or ';' or '|' as range group delimiters, and '-' as range indicators. If first/second bound of the range is empty, the min/max value of that bound is assumed. Examples: "Debug-DebugZ | Error", "-DebugZ | Info | Warning", "Info-", "DebugB-DebugC, Error"
Returns
Type Description
Destination.LevelsList

Pulse()

Provides periodic notification of destinations from central Log thread even if there are no messages to write. Override DoPulse to commit internal batching buffers provided by particular destinations

Declaration
public void Pulse()

Send(Message)

Sends the message into destination doing filter checks first.

Declaration
public void Send(Message msg)
Parameters
Type Name Description
Message msg

SetError(Exception, Message)

Notifies log service of exception that surfaced during processing of a particular message

Declaration
protected void SetError(Exception error, Message msg)
Parameters
Type Name Description
System.Exception error
Message msg

Implements

System.IDisposable

Extension Methods