Logging and Archiving|Released by:|Signature:|

Keywords: KGB-SPE-01/04|Approved by:|Signature:|

H16N161623L (klemen.zagar@ijs.si)
KGB, Jozef Stefan Institute
Radostina Georgieva (rgeorgie@eso.org)
ESO

Change Record

Table Of ContentsScope
1 Introduction
1.1 Reference Documents
2 Requirements
2.1 Logging
2.2 Archiving
3 Logging Architecture
3.1 CORBA Telecom Log Service
3.2 Centralized Log
3.3 Syntax of a Log Entry
3.3.1 A Generic Log Entry
3.3.1.1 Log Entry Type
3.3.1.2 TimeStamp
3.3.1.3 Source Code Information
3.3.1.4 Runtime Context Information
3.3.1.5 Log Entry Identification
3.3.1.6 Priority
3.3.1.7 Data Sub-element
3.3.1.8 Log Entry Message
3.3.2 ACS log levels
3.3.2.1 Trace Log Entry
3.3.2.2 Delouse Log Entry
3.3.2.3 Debug Log Entry
3.3.2.4 Info Log Entry
3.3.2.5 Notice Log Entry
3.3.2.6 Warning Log Entry
3.3.2.7 Error Log Entry
3.3.2.8 Critical Log Entry
3.3.2.9 Alert Log Entry
3.3.2.10 Emergency Log Entry
3.3.3 ACS log audiences
3.4 ACS system logging level
3.5 ACS logging statistics
3.5.1 Design notes
3.6 ACS C++ Logging API
3.6.1 ACE Logging
3.6.2 Logging Proxy's Configuration Data
3.6.3 log Method Semantics
3.6.4 Enabling the Logging Proxy
3.6.5 Submitting Log Entries
3.6.5.1 Submitting the Source Code Information
3.6.5.2 Submitting the Runtime Context
3.6.5.3 Submitting a Variable's Value
3.6.5.4 Overriding the Default Priority
3.6.5.5 Submitting an Arbitrary Message
3.6.6 Specifying an Audience, Array and/or Antenna for a log
3.6.6.1 API
3.6.6.2 Examples
3.6.7 Logging statistics configuration
3.6.7.1 API
3.6.7.2 Code examples
3.6.7.3 Log examples
3.6.7.4 Online (re)configuration
3.7 ACS Java Logging API
3.7.1 JSDK Java Logging API
3.7.2 ACS Java Logging
3.7.3 ALMA Logging Configuration Data
3.7.4 log Method Semantics
3.7.5 Obtaining a Logger
3.7.6 log Method Use
3.7.7 Specifying an Audience, Array and/or Antenna for a log
3.7.7.1 API
3.7.7.2 Example
3.7.8 Java Log Levels
3.7.9 ACS Logging Class Diagram
3.7.10 ACS Formatters
3.7.11 Logging statistics configuration
3.7.11.1 API
3.7.11.2 Code examples
3.7.11.3 Log examples
3.7.11.4 Online (re)configuration
3.8 ACS Python Logging API
3.8.1 ACS Python Logging
3.8.1.1 Short Logging Example
3.8.1.2 Specifying an Audience, Array and/or Antenna for a log
3.8.2 Logging statistics configuration
3.8.2.1 API
3.8.2.2 Code xamples
3.8.2.3 Log examples
3.8.2.4 Online (re)configuration
3.9 Type Safe Logs
4 Archiving Architecture
4.1 The Architecture
4.1.1 Parameter's Archiving Configuration
4.1.2 Extending XML Schema for Archiving
4.1.3 Submitting the Archive Data
4.1.4 Archiving in the Centralized Logger
4.1.5 Archiving architecture inside BACI
Appendix A: Logging XML Schema Definition

...

Anchor
_Toc424830058 _Toc424830058

Reference Documents

The following documents have been referenced in this document.
*\[RD01\] ALMA ACS Basic* *Control* *Interface* *Specification{*}, M. Plesko, G. Tkacik, G. Chiozzi - ([http://www.eso.org/~gchiozzi/<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="a99e0bb0-90fe-4e53-90b7-2a42cc1f3cd9"><ac:parameter ac:name="">_Hlt408496900</ac:parameter></ac:structured-macro>AlmaAcs/Releases/ACS_2_0_Docs/ACS_Basic_Control_Interface_Specification.pdf|http://www.eso.org/~gchiozzi/AlmaAcs/Releases/ACS_2_0_Docs/ACS_Basic_Control_Interface_Specification.pdf])
*\[RD02\] Adaptive Communications Environment (ACE) -* ([http://www.cs.wustl.<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="b396a73a-7ba6-45d1-960d-fcffefc7e31f"><ac:parameter ac:name="">_Hlt408497061</ac:parameter></ac:structured-macro>edu/~schmidt/ACE-overview.html|http://www.cs.wustl.edu/~schmidt/ACE-overview.html])
*\[RD03\] OMG: CORBA Telecom Log Service Specification -{*}([ftp://ftp.omg.org/pub/docs/form<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="5cd1f43a-ec5d-46fd-81fd-f0dde8920263"><ac:parameter ac:name="">_Hlt408497072</ac:parameter></ac:structured-macro>al/00-01-04.pdf|ftp://ftp.omg.org/pub/docs/formal/00-01-04.pdf])
*\[RD04\] ALMA Common Software Technical Requirements,* ALMA-TRE-ESO-XXXXX-XXXX, G.Raffi, B.Glendenning, Issue 1.0, 2000-06-05
*\[RD05\] ALMA Common Software Architecture,* G.Chiozzi, B.Gustafsson, B.Jeram *-* ([http://almaedm.tuc.nrao.edu<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="3064770b-be38-46ce-8f41-fd8fc29b9d69"><ac:parameter ac:name="">_Hlt408497327</ac:parameter></ac:structured-macro>/forums/alma/dispatch.cgi/Architecture/docProfile/100017/d20021117183329/No/ALMASoftwareArchitecture.pdf|http://almaedm.tuc.nrao.edu/forums/alma/dispatch.cgi/Architecture/docProfile/100017/d20021117183329/No/ALMASoftwareArchitecture.pdf])
\\
*\[RD06\] OMG: Notification Service Specification -{*}([ftp://ftp.omg.org/pub/docs/formal/00-06-20.pdf|ftp://ftp.omg.org/pub/docs/formal/00-06-20.pdf])
*\[RD07\] Java Logging Overview -{*}([http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/overview.html|http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/overview.html])
*\[RD08\] ACS Online Documentation for schema files -{*}([To De Updated.html|http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/overview.html])
\\
 \\
\\

Anchor
_Toc424830059 _Toc424830059

Requirements

...

The logging subsystem must allow for the following: 1.

1. It must provide an easy-to-use programming interface to the application developer.

...

1. Every log entry has an associated priority and type (error, fatal error, information, …).

...

1. Every log entry is equipped with a timestamp accurate to a deci-microsecond (100's of ns).

...

1. The logging subsystem must be centralized, so that all log entries generated in the systems sooner or later find their way to a central log. The order of the log entries is defined by their timestamp.

...

1. The subsystem should allow for filtering, so that log entries with insufficient priority do not get logged, whereas those with high priority get routed to the central log immediately.

...

1. The log entries are consistent, so that they can be interpreted by various automated tools for filtering and transforming.

...

1. Log entries can be buffered locally on the machine where they were generated, and transmitted over the network to the central log on demand or when the local buffer reaches a predetermined size.

...

1. The logging subsystem shall be capable of generating basics statistics of the logs generated (). This capability must be configurable (either to be active or inactive)

Anchor
_Toc424830061 _Toc424830061

Archiving

...

The Telecom log service specification defines a set of IDL interfaces that are suitable for implementation of any kind of a log service [RD03]. The implementation using CORBA is done in the Centralized Log. All interfaces inherit from the Log interface which defines the following operations for submitting and querying log entries The listings presented here are excerpts from file $TAO_ROOT/orbsvcs/orbsvcs/DsLogAdmin.idl, courtesy of Matthew Brown.:

interface Log

...

{ 
  // . .

...

 .   
  // Write records to the log storage

...

  void write_records(in Anys records) raises(LogFull, LogLocked);

...

  // Returns all records in the log that match the given

...

  // constraint <c>.

...

 
  RecordList query(in string grammar,

...

                   in Constraint c,
                   out Iterator i)
    raises(InvalidGrammar, InvalidConstraint);

...

 // Retrieve <how_many> records from time <from_time> using

...

  // iterator <i>. Negative <how_many> indicates backwards

...

  // retrieval

...

  RecordList retrieve(in TimeT from_time,

...

                      in long how_many,

...

                      out Iterator i);

...

};

Telecom log specification represents a log entry by a structure whose IDL is:

 typedef unsigned long long RecordId; // RecordIds are unique within

...

 the
                                       // scope of one log.
  typedef TimeBase::TimeT TimeT; // Timestamp, as defined by the

...

 CORBA
                                 // TimeService.
  struct NVPair     // Name-Value pair
  {
    string name;
    any value;
  };
  typedef sequence<NVPair> NVList; // A set of name-value mappings
  struct LogRecord
  {
    RecordId id;      // Unique number assigned by the log
    TimeT time;       // Time when the event is logged (CORBA Time Service)
    NVList attr_list; // List of user defined name/value pairs. Not part of
                      // the event received by the log. Optional.
    any info;         // Event content
  };

For our purposes, the info element of the LogRecord structure consists of an XML string containing all the information about the record, such as the timestamp (time element is not suitable for our purposes, since it will contain the time when the log entry was logged to the central log, and not when the log entry was submitted; due to caching these two times could be significantly different). The details about the XML schema of the info element are described in 3.3 "Syntax of a Log Entry".

...

A generic log entry representation in XML looks like this:
<LogEntryType

<LogEntryType TimeStamp="yyyy-MM-

...

ddThh:mm:ss.fff"

...

File="filename" Line="lineno"

...

 
Routine="routine"

...

Host="hostname" Process="procname" Thread="threadname" Context="context"

...

SourceObject="source"

...

StackId="stackid" StackLevel="stacklevel"

...

LogId="id" Uri="uri"

...

Priority="p">

...

<Data Name="name"

...

>value</Data>

...

log entry message

...

</

...

LogEntryType>

Anchor
_Toc424830067 _Toc424830067

Log Entry Type

The log entries exist in different types to distinguish between the importance of information it provides. These types are described in the following sections and follow the convention specified by $(ACE_ROOT)/ace/Log_Priority.h. Logging level Delouse has been introduced to ACS.
Note that LogEntryType is not actually an XML tag, but merely a placeholder for the actual XML tag name such as Debug described in the following sections.
More detail on the actual Log Entry Types is provided in §3.3

Anchor
_Toc424830068 _Toc424830068

TimeStamp

The timestamp is a mandatory attribute of every log entry. It specifies the exact time when the log entry was submitted. The time is encoded in ISO 8601 format with a precision to one millisecond. The time is specified in TAI.

Anchor
_Toc424830069 _Toc424830069

Source Code Information

...

• Host: The name of the computer on which the log entry is generated.
• Process: The name of the process from which the log entry is generated.
• Thread: The identification of the thread. For example, in C++ the identification is the name of the thread as supplied to InitThread (see 3.5.1.3. "Enabling the Logging Proxy").
• SourceObject: Identifies the logger that produced the current log entry.
• Context: Any additional context information supplied by the issuer of the log entry. For example, the name of the configuration database that is being used could be put here. This element is optional.
• StackId: Identification of a bundle of related log entries. All log entries in a bundle are caused by the same "root" log entry (e.g., the original cause of an error). This element is only present when logs are stacked.
• StackLevel: Specification of the number of the log entries in the bundle a given entry that have caused the log entry. The root log entry has a StackLevel of 0, the immediate log entries caused by the root log entry have a StackLevel of 1, etc. This element is only present when logs are stacked.

<Error TimeStamp="2000-08-23T13:18:27.432"
       File="FileOpener.cpp" Line="131" Routine="FileOpener::Open"
       Host="Hurricane" Process={_}"{_}Activator" Thread="EventLoop" SourceObject="GeneralLogger"
       \[...\]>
</Error>

Anchor
_Toc424830071 _Toc424830071

Log Entry Identification

...

Every log entry can contain arbitrary number of <Data> sub-elements. These sub-elements are useful for reporting values of individual variables to report the state of the object that submitted the log entry.
The Name attribute is mandatory as well as the content of the element.
<Error TimeStamp="2000-08-23T13:18:27.432"
File="FileOpener.cpp" Line="131" Routine="FileOpener::Open"
Host="Hurricane" Process="Activator" Thread="EventLoop"
LogID="err_File_Not_Found" Priority="8">
<Data Name="FullPath">/home/someuser/file.txt</Data>
</Error>

Anchor
_Toc424830074 _Toc424830074

Log Entry Message

The optional log entry message is a string of characters. The message can be either an XML formatted string, or a CDATA section. The only rule it must obey is not to contain a sub-string \]\]> or characters such as '<', '>' or '&', since it terminates a CDATA section. 
<Error TimeStamp="2000-08-23T13:18:27.432"
       File="FileOpener.cpp" Line="131" Routine="FileOpener::Open"
       Host="Hurricane" Process={_}"{_}Activator" Thread="EventLoop"
       LogID="err_File_Not_Found" Priority="8">
    <Data Name="FullPath">/home/someuser/file.txt</Data>
    *<!\[CDATA\[Message\]\]>*
</Error>
\\
\\

Anchor
_Ref406572988 _Ref406572988

Anchor
_Toc424830075 _Toc424830075

ACS log levels

...

Emergency logs denote an Alarm condition of the highest priority.
They are normally generated by the Alarm System and not explicitly use in applications by calling the logging API.
An emergency log entry (<Emergency>) corresponds to submitting a log entry of type LM_EMERGENCY to the ACE logging system. The default priority of such an entry is 11. Alerts are used for reporting errors that must be solved immediately.

Anchor
_Toc424830086 _Toc424830086

ACS log audiences

...

But ACS provides specific wrappers only for the most popular audiences, which are: OPERATOR, DEVELOPER, and SCILOG.

Anchor
_Ref406581172 _Ref406581172

Anchor
_Toc424830087 _Toc424830087

ACS system logging level

...

The CBD is capable of setting different logging levels per process or per logger

Anchor
_Ref421026857 _Ref421026857

Anchor
_Toc424830088 _Toc424830088

ACS logging statistics

...

Anchor
_Toc424830101 _Toc424830101

Submitting an Arbitrary Message

To submit an arbitrary message, care must be taken not to break XML formatting rules (for example, < and > should be used with care). If the message contents are not known in advance and a possibility exists that they would break XML formatting rules, code like this should be used:
_// This macro is predefined by ACS_
#define LM_CDATA(t) "<!\[CDATA\[" t "\]\]>"
ACE_ERROR((LM_WARNING,
           LM_CDATA("Some < text %s >"),
           szAString)) 
The unpredictable text is placed in an XML CDATA section. 

Anchor
_Toc424830102 _Toc424830102

Specifying an Audience, Array and/or Antenna for a log

...

Anchor
_Toc424830104 _Toc424830104

Examples

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
\\
\\
#include <maciSimpleClient.h>
\\
int main(int argc, char *argv\[\])
\{
        maci::SimpleClient client;
\\
        if (client.init(argc,argv) == 0)\{
                return -1;
        \}
        else\{
                // Log into the manager before doing anything
                client.login();
        \}
\\
        ACS_SHORT_LOG((LM_WARNING,"ACS_SHORT_LOG"));
        LOG_FULL(LM_WARNING,"main","LOG_FULL",log_audience::OPERATOR,"array01","Antenna01");
        LOG_WITH_ANTENNA_CONTEXT(LM_WARNING,"main","LOG_WITH_ANTENNA_CONTEXT","array01","Antenna01");
        LOG_TO_AUDIENCE(LM_WARNING,"main","LOG_TO_AUDIENCE",log_audience::OPERATOR);
        client.logout();
\\
        return 0;
\\
\}
\\

Anchor
_Ref408495274 _Ref408495274

Anchor
_Toc424830105 _Toc424830105

Logging statistics configuration

...

• This method allows the statistic module to be configured
• @param elementName String defining the name of the module the statistics belong to
• @param state Configuaration of disableStatistics attribute (to enable / diable statistics module)
• @param period Configuration of statisticsCalculationPeriod
• @param granularity Configuration of statisticsGranularity
• @return void
  */
  virtual void configureStatistics(const std::string elementName,
  const bool state,
  const uint32_t period,
  const uint32_t granularity);
  

  Anchor
  _Toc424830107 _Toc424830107

  Code examples

\\
#include "loggingACSLogger.h"
#include "loggingHandler.h"
#include "loggingLogTrace.h"
#include "logging.h"
\\
int main(int argc, char *argv\[\])
\{
    ACS_CHECK_LOGGER;
\\
    // Create logger (by default statistics are inactive)
    Logging::Logger::LoggerSmartPtr firstLoggerSmartPtr = getLogger();
    firstLoggerSmartPtr->setName("FirstLogger");
\\
    // Activate statistics for the logger
    firstLoggerSmartPtr->stats.configureStatistics("testLoggerStats",false, 600, 1);
\\
    // Direct log example (will be counted)
    logger->log(Logging::Logger::LM_TRACE, "Testing LM_TRACE message: Messages indicating function-calling sequence");
\\
    // Macro log example (will be counted)
    ACS_LOG( LM_FULL_INFO, __PRETTY_FUNCTION__, (LM_DEBUG, "Test of LM_DEBUG log"));
\\
    return 0;
\}
\\

Anchor
_Toc424830108 _Toc424830108

Log examples

The statistics report is a log with additional data containing the name of the logger and the identificator of the statistics module (if configured) as well as the statistics calculated and described on §3.5
\\
2015-07-15T13:59:04.890 \[GlobalLogger - virtual Logging::Logger::~Logger()\] LOGGING STATISTICS FOR: testLoggerStats.FirstLogger ErrorMessageIncrement="nan" MessageIncrement="-26.6667" LastPeriodNumberOfErrorMessages="0" LastPeriodNumberOfMessages="22" LastPeriodDuration="0.123412" ErrorMessageStatistics="0" MessageStatistics="178.265" StatisticsGranularity="1" LoggerId="FirstLogger" StatisticsIdentification="testLoggerStats"
\\

Anchor
_Ref421028967 _Ref421028967

Anchor
_Toc424830109 _Toc424830109

Online (re)configuration

...

• Help: execution of the binary without parameters provides a brief usage guide like showed below

#./maciContainerLogStatsConfiguration
\\
 usage: ./maciContainerLogStatsConfiguration <container name> \{set,get,list\} <loggerName> \[-c \{Enable / Disable / Default\}\] \[-n <Element name>\] \[-p <Calculation period>\] \[-g <Granularity>\]
         \[OPTIONAL\]\[used only with SET command\] -c allows configure the statistics status for the logger.
                Default sets all logger statistics to default unless explicitly stated
         \[OPTIONAL\]\[used only with SET command\] -n allows configuration of the statistics logger module name
         \[OPTIONAL\]\[used only with SET command\] -p allows configuration of statistics calculation period (in seconds). Should be > 0
         \[OPTIONAL\]\[used only with SET command\] -g allows configuration of statistics granularity (in seconds). Should be > 0
\\

• List: execution of the binary with the name of a container (that is up and running) and "list" as parameter provides the list of all loggers registered to the specified container and their current configuration (see details on §3.5)

#./maciContainerLogStatsConfiguration bilboContainer list
\\
2015-06-02T14:37:15.862 Local file logger: Cache saved to '/alma/ACS-2015.4/acsdata/tmp/alma/ACS_INSTANCE.0/acs_local_log_maciContainerLogStatsConfiguration_26653'.
2015-06-02T14:37:15.876 \[GlobalLogger\] ManagerReference generated using localhost address: 'corbaloc::192.168.153.129:3000/Manager'
2015-06-02T14:37:15.916 \[GlobalLogger\] Container: bilboContainer
2015-06-02T14:37:15.925 \[GlobalLogger\]  Logger information:
2015-06-02T14:37:15.935 \[GlobalLogger\]          \[StatisticsIdentification\].\[LoggerName\] | \[Statistics status\] | \[Calculation period\] | \[Granularity\]
2015-06-02T14:37:15.945 \[GlobalLogger\]          Undefined.bilboContainer | statsDisabled | 600 | 1
2015-06-02T14:37:15.957 \[GlobalLogger\]          Undefined.bilboContainer-GL | statsDisabled | 600 | 1
2015-06-02T14:37:15.966 \[GlobalLogger\]          Undefined.bilboContainer-Static | statsDisabled | 600 | 1
2015-06-02T14:37:15.977 \[GlobalLogger\]          Undefined.maci::LibraryManager | statsDisabled | 600 | 1
2015-06-02T14:37:15.986 \[GlobalLogger\]          Undefined.Container-MethodRequestThreadPool | statsDisabled | 600 | 1
2015-06-02T14:37:15.997 \[GlobalLogger\]          Undefined.AlarmSourceThread | statsDisabled | 600 | 1
2015-06-02T14:37:16.006 \[GlobalLogger\]          Undefined.bilboContainer | statsDisabled | 600 | 1
2015-06-02T14:37:16.016 \[GlobalLogger\]          Undefined.CLOCK1 | statsDisabled | 600 | 1
2015-06-02T14:37:16.026 \[GlobalLogger\]          Undefined.CLOCK1::actionThread | statsDisabled | 600 | 1
2015-06-02T14:37:16.036 \[GlobalLogger\]          Undefined.CLOCK1::monitorThread | statsDisabled | 600 | 1
2015-06-02T14:37:16.049 \[GlobalLogger\]          Undefined.TIMER1 | statsDisabled | 600 | 1
2015-06-02T14:37:16.063 \[GlobalLogger\]          Undefined.MOUNT1 | statsDisabled | 600 | 1
2015-06-02T14:37:16.077 \[GlobalLogger\]          Undefined.MOUNT1::actionThread | statsDisabled | 600 | 1
2015-06-02T14:37:16.087 \[GlobalLogger\]          Undefined.MOUNT1::monitorThread | statsDisabled | 600 | 1
2015-06-02T14:37:16.097 \[GlobalLogger\]  ... done.
2015-06-02T14:37:16.107 \[GlobalLogger\] Done all.
\\
\\

• Get: execution of the binary with the name of a container (that is up and running) and "get" as parameter provides the current configuration for a specific logger (specified as an extra parameter) registered to the container (see details on §3.5)

#./maciContainerLogStatsConfiguration bilboContainer get bilboContainer
\\
2015-06-02T14:50:14.273 Local file logger: Cache saved to '/alma/ACS-2015.4/acsdata/tmp/alma/ACS_INSTANCE.0/acs_local_log_maciContainerLogStatsConfiguration_26921'.
2015-06-02T14:50:14.290 \[GlobalLogger\] ManagerReference generated using localhost address: 'corbaloc::192.168.153.129:3000/Manager'
2015-06-02T14:50:14.360 \[GlobalLogger\] Container: bilboContainer
2015-06-02T14:50:14.381 \[GlobalLogger\]  Logger information 'bilboContainer':
2015-06-02T14:50:14.403 \[GlobalLogger\]          StatisticsIdentification      : Undefined
2015-06-02T14:50:14.420 \[GlobalLogger\]          LoggerName                    : bilboContainer
2015-06-02T14:50:14.443 \[GlobalLogger\]          Statistics status             : statsDisabled
2015-06-02T14:50:14.451 \[GlobalLogger\]          Calculation Period            : 600
2015-06-02T14:50:14.461 \[GlobalLogger\]          Statistics Granularity        : 1
2015-06-02T14:50:14.471 \[GlobalLogger\]  ... done.
2015-06-02T14:50:14.481 \[GlobalLogger\] Done all.
\\

• Set: execution of the binary with the name of a container (that is up and running) and "set" as parameter allows changing the configuration of an specific logger (specified as an extra parameter). The following configuration parameters are allowed Any number of parameters and parameters order is allowed, the only restriction to be noted is that "-c Default" followed by any other valid parameter configuration will set first all configuration parameters to their default values and afterwards modify the rest of parameters as specified.

  	Name	Options	Description
  -c	configuration	Enable	Sets logger statistics to enabled
  		Disable	Sets logger statistics to disabled
  		Default	Sets all logger statistics configuration parameters to its default values (see §3.6.7 for cpp, §3.7.11 for java and §3.8.2 for python)
  -n	Element name	string	Sets the logger statistics element name to the specified string
  -p	Calculation period	int	Sets the logger statistics calculation period to the specified integer
  -g	Granularity	int	Sets the logger statistics calculation granularity to the specified integer

  
  

  Wiki Markup

  \\ #./maciContainerLogStatsConfiguration bilboContainer set bilboContainer -c Enable -n testName -p 700 -g 2 \\ 2015-06-02T15:14:30.379 Local file logger: Cache saved to '/alma/ACS-2015.4/acsdata/tmp/alma/ACS_INSTANCE.0/acs_local_log_maciContainerLogStatsConfiguration_27426'. 2015-06-02T15:14:30.396 \[GlobalLogger\] ManagerReference generated using localhost address: 'corbaloc::192.168.153.129:3000/Manager' 2015-06-02T15:14:30.472 \[GlobalLogger\] Container: bilboContainer 2015-06-02T15:14:30.487 \[GlobalLogger\] Logger statistics configuration 'bilboContainer': 2015-06-02T15:14:30.506 \[GlobalLogger\] StatisticsIdentification : testName 2015-06-02T15:14:30.526 \[GlobalLogger\] LoggerName : bilboContainer 2015-06-02T15:14:30.546 \[GlobalLogger\] Statistics status : statsEnabled 2015-06-02T15:14:30.566 \[GlobalLogger\] Calculation Period : 700 2015-06-02T15:14:30.586 \[GlobalLogger\] Statistics Granularity : 2 2015-06-02T15:14:30.596 \[GlobalLogger\] ... done. 2015-06-02T15:14:30.606 \[GlobalLogger\] Done all. \\ \\ \\

  
  

  Anchor
  _Ref406573696 _Ref406573696

  Anchor
  _Toc424830110 _Toc424830110

  ACS Java Logging API

  Anchor
  _Toc424830111 _Toc424830111

  JSDK Java Logging API

The official Java Logging API (java.util.logging package \[[RD07|http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/overview.html]\]) provides with a framework for generating, formatting and filtering log entries:
1.An object that can hold a log record (LogRecord). Its methods allow getting the level of priority, type and the timestamp as well as the filename, the process, the thread and the context of the source code where the log entry originates from. 
2.An object that is used to log messages for a specific system or application component (Logger). 
3.A mechanism for taking log entries and exporting them modeled by a Handler class (ConsoleHandler, FileHandler). There is one instance of the subclasses of this class per container  For more details, read about the Component-Container model in "Java Component Tutorial.". Both loggers and the handlers are organized in a hierarchical namespace so that children may inherit some properties from their parents.
3.An object that provides support for formatting a LogRecord (Formatter).  The formatter takes a LogRecord and converts it to a string. 
4.An object that defines a set of standard logging levels that can be used to control logging output (Level).  It can be applied to a log record, a logger and a handler. Specifying the lowest acceptable level acts for implementing the filtering functionality.

Anchor
_Toc424830112 _Toc424830112

ACS Java Logging

...

1. Handler specific properties.
2. Describes specific configuration info for Handlers.
   ############################################################
3. default file output is in user's home directory.
   alma.acs.logging.AcsLoggingHandler.level = ALL
   alma.acs.logging.AcsLoggingHandler.localcopy = true
   alma.acs.logging.AcsRemoteHandler.cacheSize = 4
   alma.acs.logging.AcsRemoteHandler.formatter = alma.acs.logging.formatters.AcsXMLFormatter
   java.util.logging.FileHandler.pattern = %h/java%u.log
   java.util.logging.FileHandler.limit = 50000
   java.util.logging.FileHandler.count = 1
   java.util.logging.FileHandler.level = ALL
   java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
4. Limit the message that are printed on the console to INFO and above.
   java.util.logging.ConsoleHandler.level = INFO
   java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
5. java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter
   ############################################################
6. Facility specific properties.
7. Provides extra control for each logger.
   ############################################################
8. For example, set the com.xyz.foo logger to only log SEVERE
9. messages:
   alma.acs.containerstart.level = ALL
   alma.acs.logger.level = ALL
   handlers: is omitted since there is a default console handler which uses its simple log buffer to publish all the log records. It is implemented as part of the AcsLoggingHandler. It is also used for transmitting the log records to the Centralized Log that are initially stored in the log buffer. If there is no connection, the log records end up in the console. The ConsoleHandler uses always the console as a medium for publishing.
   .level: should be set to one of the variables specified in the Java Logging API.
   The handler's specific level, buffer size and formatter should be defined as variables too. Since the log records get published each time the buffer reaches its size and the user gets the log records as soon as the buffer is full, the size variable should not be assigned a big number.
   The other specific properties include setting a specific log level for the container or other components.

   Anchor
   _Toc424830114 _Toc424830114

   log Method Semantics

...

1. 1. 1. 1. Anchor
            _Toc424830119 _Toc424830119

            Example

package alma.acs.logging;
import java.util.logging.Level;
\\
import alma.acs.component.client.ComponentClient;
import alma.acs.logging.domainspecific.AntennaContextLogger;
import alma.log_audience.OPERATOR;
\\
public class TestAudArr extends ComponentClient\{
        public TestAudArr(String managerLoc, String clientName) throws Exception \{
                super(null, managerLoc, clientName);
        \}
\\
        public static void main(String args\[\])\{
                String managerLoc = System.getProperty("ACS.manager");
                if (managerLoc == null) \{
                        System.out.println("Java property 'ACS.manager' must be set to the corbaloc of the ACS manager!");
                        System.exit(-1);
                \}
                String clientName = "TestAudArr";
                TestAudArr client = null;
                try\{
                        client = new TestAudArr(managerLoc, clientName);
                        AcsLogger m_logger = (AcsLogger)client.getContainerServices().getLogger();
                        AntennaContextLogger logger = new AntennaContextLogger(m_logger);
                        m_logger.log(Level.WARNING, "Normal Log");
                        m_logger.logToAudience(Level.WARNING, "Log with audience", OPERATOR.value);
                        m_logger.logToAudience(Level.WARNING, "Log exception with audience", new Exception("My dummy exception"), OPERATOR.value);
                                                        logger.log(Level.WARNING, "Log with audience, array and antenna", OPERATOR.value, "Array01", "Antenna01");
                        logger.log(Level.WARNING, "Log with array and antenna", "Array01", "Antenna01");
                        logger.log(Level.WARNING, "Log exception with audience, array and antenna", new Exception("My dummy exception"), OPERATOR.value, "Array01", "Antenna01");
                        logger.log(Level.WARNING, "Log exception with array and antenna", new Exception("My dummy exception"), "Array01", "Antenna01");
                        \\
                        Thread.sleep(1000);
                \}catch(Exception e)\{
                        System.out.println("Error creating test client");
                \}
                try\{
                        client.tearDown();
                \}catch(Exception e)\{
                        System.out.println("Error destroying test client");
                \}
        \}
\}

Anchor
_Toc424830120 _Toc424830120

Java Log Levels

The Java log levels have been remapped to comply with the ACS log levels from the XML schema. The mapping is done in the alma.acs.logging.AcsLogLevel class where the ACS levels, like the JAVA API levels, are specified by ordered integers. The OFF level which is not mentioned in the XML schema is included for dealing with bad levels as well as for blocking logging:

Anchor
_Toc424830121 _Toc424830121

ACS Logging Class Diagram

...

The formatters involved are named according to the ACS Logging Level. The alma.acs.logging.AcsXMLFormatter is a formatter object that produces a valid XML string out of a log message according to the XML schema for ACS.

Figure 5: Class Diagram of ACS Formatters.
The AcsLogFormatter object defines methods for getting the properties needed for formatting a string into an XML string. The AcsXMLFormatter calls any of the customized formatters.

Anchor
_Ref421027043 _Ref421027043

Anchor
_Toc424830123 _Toc424830123

Logging statistics configuration

...

package alma.acs.logging;
import java.util.logging.Handler;
import java.util.logging.Level;
import java.util.logging.Logger;
import junit.framework.TestCase;
import alma.acs.testsupport.TestLogger;
import alma.log_audience.OPERATOR;
public class AcsLoggerTest extends TestCase {
private AcsLogger acsLogger;
public void testLoggerStatistics() {
// Configure statistics
acsLogger.stats.configureStatistics("AcsLoggerTest", false, 600, 1);
// Write log (will be counted)
acsLogger.log(AcsLogLevel.TRACE, "Message TRACE");
// Close logger module, that will force statistics to be printed
acsLogger.closeLogger();
}
}

Anchor
_Toc424830126 _Toc424830126

Log examples

The statistics report is a log with additional data containing the name of the logger and the identificator of the statistics module (if configured) as well as the statistics calculated and described on §3.5
\\
<Info TimeStamp="2015-07-15T15:31:18.105" File="AcsLoggerTest.java"  Line="136" Routine="testLoggerStatistics" Host="alma" Process="alma.acs.logging.AcsLoggerTest" SourceObject="alma.acs.logging.AcsLoggerTest" Thread="main" LogId="41"><!\[CDATA\[LOGGING STATISTICS FOR: AcsLoggerTest.alma.acs.logging.AcsLoggerTest\]\]><Data Name="LoggerId"><!\[CDATA\[alma.acs.logging.AcsLoggerTest\]\]></Data><Data Name="LastPeriodDuration"><!\[CDATA\[4.012\]\]></Data><Data Name="MessageStatistics"><!\[CDATA\[2.7417746\]\]></Data><Data Name="StatisticsIdentification"><!\[CDATA\[AcsLoggerTest\]\]></Data><Data Name="ErrorMessageIncrement"><!\[CDATA\[NaN\]\]></Data><Data Name="StatisticsGranularity"><!\[CDATA\[1\]\]></Data><Data Name="MessageIncrement"><!\[CDATA\[Infinity\]\]></Data><Data Name="ErrorMessageStatistics"><!\[CDATA\[0.0\]\]></Data><Data Name="LastPeriodNumberOfErrorMessages"><!\[CDATA\[0\]\]></Data><Data Name="LastPeriodNumberOfMessages"><!\[CDATA\[11\]\]></Data></Info>
\\

Anchor
_Toc424830127 _Toc424830127

Online (re)configuration

...

from Acspy.Common.Log import getLogger
import ACSLog
from Acspy.Clients.SimpleClient import PySimpleClient
import logging
from log_audience import OPERATOR
from log_audience import NO_AUDIENCE
simpleClient = PySimpleClient()
logger = getLogger("TestAudience")
logger.log(logging.WARNING, "Normal log")
logger.logNotSoTypeSafe(ACSLog.ACS_LOG_WARNING, "Log with audience, array and antenna", OPERATOR, "Array01", "Antenna01")
logger.logNotSoTypeSafe(ACSLog.ACS_LOG_WARNING, "Log with audience", OPERATOR)
logger.logNotSoTypeSafe(ACSLog.ACS_LOG_WARNING, "Log with array and antenna", NO_AUDIENCE, "Array01", "Antenna01")
simpleClient.disconnect()

Anchor
_Ref421027059 _Ref421027059

Anchor
_Toc424830132 _Toc424830132

Logging statistics configuration

...

from Acspy.Common.Log import getLogger

1. Get a Logger instance
   logger = getLogger()
2. Configure the statistics module
   logger.stats.configureStatistics("AcspyTestLogging", False, 600, 1)
3. Log something (will be counted)
   logger.logNotice('Message included in statistics')
   
   

   Anchor
   _Toc424830135 _Toc424830135

   Log examples

The statistics report is a log with additional data containing the name of the logger and the identificator of the statistics module (if configured) as well as the statistics calculated and described on §3.5
\\
2015-07-16T13:28:02.345 StatisticsTest LOGGING STATISTICS FOR: AcspyTestLogging.StatisticsTest \[ StatisticsIdentification=AcspyTestLogging LoggerId=StatisticsTest LastPeriodDuration=2.00889706612 LastPeriodNumberOfMessages=4 StatisticsGranularity=1 MessageStatistics=1.99114233749 MessageIncrement=0 LastPeriodNumberOfErrorMessages=0 ErrorMessageStatistics=0.0 ErrorMessageIncrement=0 \]
\\

Anchor
_Toc424830136 _Toc424830136

Online (re)configuration

See §3.6.7.3

Anchor
_Toc424830137 _Toc424830137

Type Safe Logs

Type safe logs work on top of the free format logs defined above in the previous sections. These are logs with a formalized structure and contents, mainly thought for the implementation of operational logs of direct interest for the operator of the system, while free format logs are used for post-mortem analysis and debugging. However, this does not exclude that type-safe logs can be used for lower level logs, when deemed convenient.
The module loggingtsTypes contains standard log definitions used over the project. Before you create your own definition, check this module to see if it isn't already there.
Here follows the XML schema file, that type safe log definitions must comply to. It is located in the loggingts module, and is called ACSLogTS.xsd.
<?xml version="1.0" encoding="ISO-8859-1"?>
<xs:schema
xmlns:loggingts="Alma/ACSLogTS"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:common="urn:schemas-cosylab-com:COMMONTYPES:1.0"
targetNamespace="Alma/ACSLogTS"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:import namespace="urn:schemas-cosylab-com:COMMONTYPES:1.0" schemaLocation="commontypes.xsd"/>
<xs:element name="LogDefinitionType">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<xs:element name="LogDefinition" maxOccurs="unbounded">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="Member" type="common:Member_"/>
</xs:choice>
<xs:attribute name="logName" type="common:nameType" use="required"/>
<xs:attribute name="shortDescription" type="common:shortDescriptionString" use="required"/>
<xs:attribute name="description" type="common:nonEmptyString" use="required"/>
<xs:attribute name="URL" type="xs:string" use="optional"/>
<xs:attribute name="priority" type="loggingts:priorityType" use="required"/>
</xs:complexType>
</xs:element>
</xs:choice>
<xs:attribute name="name" type="common:nameType" use="required"/>
<xs:attribute name="type" type="loggingts:logType" use="required"/>
<xs:attribute name="shortDescription" type="common:shortDescriptionString" use="optional"/>
<xs:attribute name="description" type="common:nonEmptyString" use="optional"/>
<xs:attribute name="URL" type="xs:string" use="optional"/>
<xs:attribute name="_prefix" type="common:prefixType" default="alma"/>
</xs:complexType>
</xs:element>
<xs:simpleType name="logType">
<xs:restriction base="xs:nonNegativeInteger"/>
</xs:simpleType>
<xs:simpleType name="priorityType">
<xs:restriction base="common:nonEmptyString">
<xs:enumeration value="TRACE"/>
<xs:enumeration value="DEBUG"/>
<xs:enumeration value="INFO"/>
<xs:enumeration value="NOTICE"/>
<xs:enumeration value="WARNING"/>
<xs:enumeration value="ERROR"/>
<xs:enumeration value="CRITICAL"/>
<xs:enumeration value="ALERT"/>
<xs:enumeration value="EMERGENCY"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
An example log definition file is as follows:
<?xml version="1.0" encoding="ISO-8859-1"?>
<LogDefinitionType
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="Alma/ACSLogTS"
name="SampleLog"
type="10"
shortDescription="Example LogDefinitionType"
description="Longer description of the sample LogDefinitionType"
URL="http://someurl.org"
_prefix="alma">
<LogDefinition
logName="logWithMembers"
shortDescription="Log with members"
description="This is a somewhat more complex log using members"
URL="http://someurl.org"
priority="WARNING">
<Member name="someMember"
type="string"
description="member description"/>
</LogDefinition>
</LogDefinitionType>
After you have defined your logs, you must include them in your module's Makefile, adding the following line(let's assume the file is called SampleLog.xml):
ACSLOGTSDEF=SampleLog
This will produce the code necessary to use the logs from C++, Java and Python.
Example C++ usage(to compile this remember to add -lSampleLog to the LDFLAGS):
#include <SampleLog.h>
...
SampleLog::logWithMembers my_log(_FILE,LINE_,"this_function_name");
my_log.setsomeMember("this is the value of someMember");
my_log.log();
...
Example Java usage:
import alma.SampleLog.*
...
// m_logger is the logger of this class
// i.e. If you are in the main of a class that extends ComponentClient
// you should use this.m_logger
logWithMembers my_log=new logWithMembers(m_logger);
my_log.setsomeMember("this is the value of someMember");
my_log.log();
...
Example Python usage:
from SampleLog import logWithMembers
...
my_log=logWithMembers()
my_log.setsomeMember("this is the value of someMember")
my_log.log()
...

Anchor
_Toc424830138 _Toc424830138

Archiving Architecture

...

Anchor
_Toc424830140 _Toc424830140

Parameter's Archiving Configuration

Along with other parameter characteristics (minimum and maximum value, unit of measurements, ...) these configuration parameters determine the parameter's archiving policy:
*archive_priority* (unsigned 32-bit integer): The priority of the log entry that will carry the information required for archiving the parameter's value. Default is 3 (LM_INFO). If the priority exceeds the value specified in the logging proxy's MaxCachePriority, the archiving data will be transmitted to the centralized logger immediately. If it is below MinCachePriority, the data will be ignored. If it is somewhere in-between, it will be cached locally until a sufficient amount of log entries is collected for transmission to the centralized logger.
*archive_max_int* (double): The maximum amount of time (in seconds and fractions of seconds) allowed to pass between two consecutive submissions to the log. If the time exceeds the value specified here, the log entry should be generated even though the value of the parameter has not changed sufficiently.
*archive_min_int* (double): The minimum amount of time (in seconds and fractions of seconds) allowed to pass between two consecutive submissions to the log. If the time is smaller than the value specified here, the log entry is not submitted, even though the value of the parameter has changed.
*archive_delta* (same type as parameter): Defines what a change in parameter value is. If the value changes for less than the amount specified here, no log entry is generated.
*For more details see the ACS Online documentation for CDB Schema files \[RD08\].*

Anchor
_Toc424830141 _Toc424830141

Extending XML Schema for Archiving

...

Anchor
_Toc424830143 _Toc424830143

Archiving in the Centralized Logger

The Centralized Logger sends all <Archive> elements to a special *_archiving notification channel{_}{*}. The reference to this notification channel can be found in the name resolution service under the name ArchivingChannel.
The log entries sent to the notification channel are structured events with the following properties (\[6\], section 2.2):

Anchor
_Toc424830144 _Toc424830144

Archiving architecture inside BACI

Since BACI already implements monitoring mechanism, only one more monitor per property has to be set up to grab the property's data. The best place to construct this monitor (the archiving monitor) is at the property's construction time. Here, BACI looks up the archive_* entries in the configuration database, and if at least one of archive_min_int, archive_max_int or archive_delta is defined, a monitor callback is constructed and registered with the property using this configuration information.
The monitor callback does nothing else but use the ACS_ARCHIVE macro as shown above to submit archive data to the logging proxy. The logging proxy then takes care of passing this data (either directly or via local cache) to the centralized logger, which is especially adjusted to handle <Archive> elements.
The monitor callback is constructed in-process relative to the property object. If TAO's optimization is used, only one virtual function call will be required from the property's monitor dispatcher to reach the archiving code in the monitor callback, making archiving a very efficient operation.

Anchor
_Toc424830145 _Toc424830145

Appendix A: Logging XML Schema Definition

...