This article discusses using routines from ELogging unit that can be used to log any data into a single log file. This is useful to get idea of overall flow of your application. To learn about other logging features in EurekaLog - see this article. If you want to use 3rd party framework instead - see this article.

ELogging

ELogging unit writes log into CodeSite-compatible format (.csl file format). CodeSite format is mostly textual. You can view it in advanced text editors (such as Notepad++) or use free CodeSite File Viewer tool. You can obtain it either via installing CodeSite (it is available via GetIt in latest RAD Studio IDEs) or download standalone installer.

Important Note: EurekaLog is not a replacement for CodeSite (or any other logging framework). EurekaLog has no log dispatcher, no live logging, no TCP/HTTP logging, no complex logging methods, etc. EurekaLog simply writes local report file. Only simple/basic logging methods are available, there is no support for complex data types. There is no wizard to wrap your routines in log calls. If you want to use a proper logging framework with EurekaLog - see this article.

First, if you want a permanent log file - you have to create a new log file by calling ELogOpen function:

ExeName         := ParamStr(0);
LogFileName     := ChangeFileExt(ExtractFileName(ExeName), '.csl');
LogFolder       := ExpandEnvVars('%APPDATA%'); // ExpandEnvVars is declared in ESysInfo unit
FullLogFileName := IncludeTrailingPathDelimiter(LogFolder) + LogFileName;
 
ELogOpen(FullLogFileName);

This code will create a new (permanent) log file in the APPDATA folder (with the same name as .exe file). You can create log file in any location. We recommend to use .csl file extension.

Creating log file should be the first action by your code, before you call any other routines in ELogging unit. If you do not call ELogOpen function - logging will be performed into temporal file, which will be deleted when application exists. Always call ELogOpen function to get permanently saved log. Do not call ELogOpen function if you only want log file as attach to bug report (see below).

Important Note: Log file will contain all information that you log using the logging functions listed below. Additionally, you may include EurekaLog's own logging (e.g. hook calls, exception processing, dialogs, sending, etc.) inside same log file too. EurekaLog will not log its own execution flow by default. You can ask EurekaLog to log itself automatically as explained in this article.

You can write to log using various ELog functions:

ELog('Say Hello');
ELog('I', I);
ELogMemoryAsHex('Stream', Stream.Memory, Stream.Size);

The result will be:

Resulting log being viewed in CodeSite File Viewer

See ELogging unit for more information on possible constructs.

You can alter created entries by assigning a category or colors:

ELog.FontColor(clRed).Log('Say Hello');
ELog.Color(clRed).Log('I', I);
ELog.Category('My Category').LogMemoryAsHex('Stream', Stream.Memory, Stream.Size);

As well as chain several modifiers together:

ELog.Category('My Category').Color(clBlack).FontColor(clWhite).Log('Say Hello');

You can also log entering and exiting functions:

procedure Test;
begin
  ELogEnter('Test').D;
 
  // Your code goes here. 

  // Including other logging code, 

  // such as: ELog('Some log inside function');

  // ...

end;

The EDebugInfo unit offers various functions, such as __MODULE__, __UNIT_, __FILE__, __FUNCTION_, and __LINE__. For example:

procedure Test;
begin
  ELogEnter(__FUNCTION__).D;
 
  // Your real code goes here:

  // ...

end;

This code will log entering and exiting from the function, as well as indents log to the right, so any nested calls to ELog inside Test function will be written indented to the right.

You can log function parameters as well:

procedure Test(const AMsg: String; const AValue: Integer);
begin
  ELogEnter('Test').P('AMsg', AMsg).P('AValue', AValue).D;
 
  // Your real code goes here:

  // ...

end;

Please note, that you have to always call either D or C methods as the last action in chain - to indicate that function has no more arguments. Otherwise (if you forgot to close function call) indentation for nested log entries will be wrong. The difference between D and C is that D creates a normal (expanded) log entry, and C creates closed (collapsed) entry.

If you want to log a call to a method - simply specify an object/class as the first argument:

procedure TMyObject.Test(const AMsg: String; const AValue: Integer);
begin
  ELogEnter(Self, 'Test').P('AMsg', AMsg).P('AValue', AValue).D;
 
  // Your real code goes here:

  // ...

end;

If you want to log a returned value too:

function TMyObject.Test(const AMsg: String; const AValue: Integer): Integer;
var
  L: IEurekaLoggerParams; 
begin
  L := ELogEnter(Self, 'Test').P('AMsg', AMsg).P('AValue', AValue).D;
 
  // Your code goes here, for example:

  Unit1.Test(AMsg, AValue);
  if AValue = 0 then
    Result := 0
  else
    Result := 1;
 
  L.Ret(Result);
end;

The existing log file will automatically be added to bug report during sending. When you receive bug report - the log will be shown as file attach:

Log file inside EurekaLog's crash report

Double-click log file to view in CodeSite Viewer tool

If you do not want to use EurekaLog's logging, you can use any other logging framework and attach its own log file to EurekaLog's bug report.

See also: