ada-libraries
/
alog
mirror of https://git.codelabs.ch/alog.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Update documentation wrt. policy filtering 

Swap policy example 1 and 2 to explain destination filtering first and
source filtering second.
This commit is contained in:
Adrian-Ken Rueegsegger 2019-09-25 18:47:22 +02:00
parent 24d3cfb920
commit 7ca00921e1
3 changed files with 80 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/index
View File

@ -59,8 +59,9 @@ Casing (toUpper / toLower)::
Policy
~~~~~~
Alog supports source and destination filtering by means of loglevel policies.
Refer to the example section for information on how to setup such policies.
Alog supports destination and if needed source filtering by means of loglevel
policies. Refer to the example section for information on how to setup an use
these policy mechanism.
Examples
--------
@ -94,19 +95,21 @@ include::../examples/facility_example1.adb[]
Policy
~~~~~~
The first policy example uses the policy database of Alog to specify source
specific loglevels. It shows how logging policies can be used to filter
log messages depending on their source.
The first policy example illustrates how destination filtering works. Only log
messages with loglevel `Error` or higher are written to the application error
logfile. It shows how logging policies can be used to filter log messages
depending on the destination (facility name). Furthermore it illustrates how
the default level can be used to filter out messages with lower loglevels.
[source,ada]
---------------------------------------------------------------------
include::../examples/policy_example1.adb[]
---------------------------------------------------------------------
The second policy example demonstrates the usage of destination filtering. Only
log messages with loglevel `Error` or higher are written to the application
error logfile. It shows how logging policies can be used to filter log messages
depending on the destination (facility name).
The second policy example demonstrates how the protected policy database type
of Alog can be used to implement source filtering in an application. It shows
how logging policies can be constructed by specifying source specific loglevels
and how this leads to log messages being filtered depending on their source.
[source,ada]
---------------------------------------------------------------------

68
examples/policy_example1.adb
View File

@ -1,46 +1,42 @@
with Alog.Policy_DB;
with Alog.Dst_Filter;
with Alog.Logger;
with Alog.Facilities.File_Descriptor;
use Alog;
-- Alog source loglevel policy example.
-- Alog destination loglevel policy example.
procedure Policy_Example1 is
Src_Filter : Policy_DB.Protected_Policy_DB;
Log : Logger.Instance (Init => True);
Log : Logger.Instance (Init => True);
Facility_Name : constant String := "Application_Errors";
Errors : constant Facilities.File_Descriptor.Handle
:= new Facilities.File_Descriptor.Instance;
begin
-- Set default loglevel to 'Info'.
Src_Filter.Set_Default_Loglevel (Level => Info);
-- Set source specific loglevel for all 'Example' sources to 'Debug'.
Src_Filter.Set_Loglevel (Identifier => "Example.*",
Level => Debug);
-- Write all error messages to '/tmp/errors.log'.
Errors.Set_Logfile (Path => "/tmp/errors.log");
Errors.Set_Name (Name => Facility_Name);
Errors.Toggle_Write_Loglevel (State => True);
-- This message will be logged because it matches a source specific
-- loglevel (Example.*).
if Src_Filter.Accept_ID (Identifier => "Example.Source1",
Level => Debug)
then
Log.Log_Message (Source => "Example.Source1",
Level => Debug,
Msg => "This is a test message");
end if;
-- Set loglevel policy to 'Error' for destination 'Application_Errors'.
Dst_Filter.Set_Loglevel (Name => Facility_Name,
Level => Error);
-- This message will not be logged because of the configured default 'Info'
-- loglevel. There's no configured source loglevel for 'Source2'.
if Src_Filter.Accept_ID (Identifier => "Source2",
Level => Debug)
then
Log.Log_Message (Source => "Source2",
Level => Debug,
Msg => "This will not be logged");
end if;
Log.Attach_Facility (Facility => Facilities.Handle (Errors));
-- This message will be logged because of the configured default 'Info'
-- loglevel. There's no configured source loglevel for 'Source2'.
if Src_Filter.Accept_ID (Identifier => "Source2",
Level => Info)
then
Log.Log_Message (Source => "Source2",
Level => Info,
Msg => "This is another test message");
end if;
-- This message will appear on stdout, but not in the error logfile.
Log.Log_Message (Level => Info,
Msg => "This is not an error");
-- This message will also be written to the error logfile.
Log.Log_Message (Level => Error,
Msg => "This is an error");
-- Set global loglevel to only log messages with level higher than Warning
-- if no facility-specific level is set.
Dst_Filter.Set_Default_Level (Level => Warning);
-- This message will be filtered out.
Log.Log_Message (Level => Info,
Msg => "This message will be filtered");
-- This message will appear on stdout, but not in the error logfile.
Log.Log_Message (Level => Warning,
Msg => "This is a warning message");
end Policy_Example1;

68
examples/policy_example2.adb
View File

@ -1,42 +1,46 @@
with Alog.Dst_Filter;
with Alog.Policy_DB;
with Alog.Logger;
with Alog.Facilities.File_Descriptor;
use Alog;
-- Alog destination loglevel policy example.
-- Alog source loglevel policy example.
procedure Policy_Example2 is
Log : Logger.Instance (Init => True);
Facility_Name : constant String := "Application_Errors";
Errors : constant Facilities.File_Descriptor.Handle
:= new Facilities.File_Descriptor.Instance;
Src_Filter : Policy_DB.Protected_Policy_DB;
Log : Logger.Instance (Init => True);
begin
-- Write all error messages to '/tmp/errors.log'.
Errors.Set_Logfile (Path => "/tmp/errors.log");
Errors.Set_Name (Name => Facility_Name);
Errors.Toggle_Write_Loglevel (State => True);
-- Set default loglevel to 'Info'.
Src_Filter.Set_Default_Loglevel (Level => Info);
-- Set source specific loglevel for all 'Example' sources to 'Debug'.
Src_Filter.Set_Loglevel (Identifier => "Example.*",
Level => Debug);
-- Set loglevel policy to 'Error' for destination 'Application_Errors'.
Dst_Filter.Set_Loglevel (Name => Facility_Name,
Level => Error);
-- This message will be logged because it matches a source specific
-- loglevel (Example.*).
if Src_Filter.Accept_ID (Identifier => "Example.Source1",
Level => Debug)
then
Log.Log_Message (Source => "Example.Source1",
Level => Debug,
Msg => "This is a test message");
end if;
Log.Attach_Facility (Facility => Facilities.Handle (Errors));
-- This message will not be logged because of the configured default 'Info'
-- loglevel. There's no configured source loglevel for 'Source2'.
if Src_Filter.Accept_ID (Identifier => "Source2",
Level => Debug)
then
Log.Log_Message (Source => "Source2",
Level => Debug,
Msg => "This will not be logged");
end if;
-- This message will appear on stdout, but not in the error logfile.
Log.Log_Message (Level => Info,
Msg => "This is not an error");
-- This message will also be written to the error logfile.
Log.Log_Message (Level => Error,
Msg => "This is an error");
-- Set global loglevel to only log messages with level higher than Warning
-- if no facility-specific level is set.
Dst_Filter.Set_Default_Level (Level => Warning);
-- This message will be filtered out.
Log.Log_Message (Level => Info,
Msg => "This message will be filtered");
-- This message will appear on stdout, but not in the error logfile.
Log.Log_Message (Level => Warning,
Msg => "This is a warning message");
-- This message will be logged because of the configured default 'Info'
-- loglevel. There's no configured source loglevel for 'Source2'.
if Src_Filter.Accept_ID (Identifier => "Source2",
Level => Info)
then
Log.Log_Message (Source => "Source2",
Level => Info,
Msg => "This is another test message");
end if;
end Policy_Example2;