TjachLog_LogX

Class: TjachLog

Declaration:

    procedure LogXXXX(ATopic: TjachLogTopicIndex; const S: string); overload; inline;
    procedure LogXXXX(ATopic: TjachLogTopicIndex; const S: string; const Args: array of const); overload;
    procedure LogXXXX(ATopic: TjachLogTopicIndex; E: Exception); overload; inline;
    procedure LogXXXX(ATopic: TjachLogTopicIndex; const ExtraMsg: string; E: Exception); overload; inline;
    procedure LogXXXX(ATopic: TjachLogTopicIndex; const S: string; const Args: array of const; E: Exception); overload;
    procedure LogXXXX(const S: string); overload; inline;
    procedure LogXXXX(const S: string; const Args: array of const); overload;
    procedure LogXXXX(E: Exception); overload; inline;
    procedure LogXXXX(const ExtraMsg: string; E: Exception); overload; inline;
    procedure LogXXXX(const S: string; const Args: array of const; E: Exception); overload;

TjachLog.Log Methods

There's no method called LogXXXX, but the methods that start with Log and end with a severity level name share the same functionality and usage.

This topic applies to these different methods:

• Log
• LogAlert
• LogCritical
• LogDebug
• LogDebugVerbose
• LogEmergency
• LogError
• LogInfo
• LogNotice
• LogWarning

Why all different methods?

The different methods are kind of syntactic sugar, provided for a simple and flexible usage of the class and only differs on the severity level of the logged message. Thus, a call to the LogAlert method will register a log entry with lsAlert severity level, while a LogError call will register an entry with lsError severity level.

If you prefer, you can directly call the Log method where you can pass the severity as a parameter.

Method variant calls

The methods are overloaded to further flexibility at the calling point. You will use more or less parameters on different situations.

Topic vs no topic parameter

If you have a simple application where all your log entries belong to a single topic, you can avoid the topic parameter and directly make a call like this:

jachLog.LogInfo('Process is starting');

If you omit the topic parameter, the events will be belong to the DefaultTopic property value.

On the other hand, if you have a complex application where different topics are used to alow a fine tune of the log filtering, you pass the topic index as the first parameter, for example:

jachLog.LogInfo(LTOPIC_AUTOMATION, 'Process is starting');

For more information and examples read about log topics

Simple message vs formatted message

There are some places where you just want to log a simple constant message:

jachLog.LogInfo('Process is starting');

But there are places where you may want to include some runtime information to that message. We usually call the Format() function with a format string an a bunch of arguments to substitute values.

You can simplify your code by just passing the arguments to the Log function, for example:

jachLog.LogDebug('Processing customer No. %5.5d', [qryCustomerID.Value]);

Logging exceptions

At some places, you just want to log the exception information. Be aware that is much better to pass the exception to the routine that just pass the exception message, so you may want to call it like this:

  try
    SomeRoutine;
  except
    on E: Exception do
    begin
      jachLog.LogError(E);
      raise;
    end;
  end;

This allows you, for example, to the the call stack at exception time as part of the log content. For more info read loging the call stack along with exceptions

If you want to include a custom message appended to the exception message, add it as the ExtraMsg parameter that is prepended to the exception message, for example:

      jachLog.LogError('An error occurred while processing the customer data: ', E);

As you may expect now, the library also supports passing a format string with arguments along with the exception:

      jachLog.LogError('An error occurred while processing the customer No. %s data: ', CustomerNo, E);

Logging multiline messages:

The logging routine supports multiline messages, so if you want to log some data, you don't have to call multiple times the routine, just add carriage return characters as part of your string, for example:

  jachLog.LogDebug('Data input line parsed'#13
    + 'ID:    %s'#13
    + 'Name:  %s'#13
    + 'Phone: %s'
    , [lID, lName, lPhone]
  );

Proper line breaks will be introduced at the desired points when written to fixed line length destinations like file, console or GUI (VCL and FMX) and the like.

The carriage return characters will be preserved when written to destinations with an unknown or undefined line lenght, for example databases, syslog, etc.