...

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

...

Scope

This document describes the architecture and design for logging and archiving data generated by ACS applications. This architecture is in accordance with the Logging and Archiving section of the ALMA Common Software Architecture document [RD05].

Introduction

Every properly built system needs to be able to log the

...

Scope

This document describes the architecture and design for logging and archiving data generated by ACS applications. This architecture is in accordance with the Logging and Archiving section of the ALMA Common Software Architecture document [RD05].

...

Every properly built system needs to be able to log the events that occur in it (logging) so that the user of the system can gain an accurate understanding of the system's state, especially in case of a failure. For example, every component should log when it is created and destroyed. For systems with more stringent security requirements it might be required that every access to the system is logged, along with the user that performed it (auditing). Also, the system should log all unusual and error conditions.
Logging is very useful during debugging. Every entering or leaving of an important function could be logged to determine whether a function has been called at all and with what parameters. This information is also useful for profiling because more frequently used functions can be easily identified and more effort can be invested in their optimization.
Logging subsystem can be built very easily in a single computer scenario: a simple fprintf does the job. However, in a distributed system, means must be provided to centralize all logging activity in a single place, and still not overload the network too much. Also, the temporary unavailability of the network connectivity should not cause the logging subsystem to malfunction.
Another very important issue is the consistence of log entries. If all log entries stick to the same formatting rules (for example, the name of the log entry issuer, followed by a colon, followed by an error code, …), then automated log parsers can be built to intelligently filter or transform the log output, assisting the administrator to more efficiently manage the huge amount of data contained in the log.
A control system generates a huge amount of data, such as:

...

• A specialized protocol for transferring archive data.
• An existing mechanism for logging (i.e., archive is nothing else but a huge log file).
• An existing mechanism for monitoring.

...

...

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])
\\
 \\

...

\\

Requirements

...

Logging

The logging subsystem must allow for the following:

1. It must provide an easy-to-use programming interface to the application developer.
2. Every log entry has an associated priority and type (error, fatal error, information, …).
3. Every log entry is equipped with a timestamp accurate to a deci-microsecond (100's of ns).
4. 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.
5. 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.
6. The log entries are consistent, so that they can be interpreted by various automated tools for filtering and transforming.
7. 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.
8. 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)

...

Archiving

The archiving subsystem must allow for the following:

1. Every property in the control system is eligible for archiving.
2. Archiving can be enabled or disabled on per-parameter basis.
3. Archiving can be configured on per-parameter basis.
4. Individual parameter can be archived when it changes or with a certain fixed frequency.
5. There is a central point where the archive of all parameters is kept.
6. Individual parameter's archived data can be stored on a local machine, or immediately forwarded to the central archive.
7. Each parameter can be uniquely identified through the unique distributed object name and the parameter name.
8. The archiving subsystem supplies a mechanism for retrieving the historical value of any parameter at any time, provided that the value was archived prior to that time.

...

...

Logging Architecture

Logging subsystem leverages three systems that have been either already built, or at least well designed and specified. These are:

1. CORBA Telecom Log Service for centralizing all log entries generated throughout the system.
2. CORBA Notification Service for distributing log entries to interested clients (consumers of logs) when the entries are submitted to the centralized logger.
3. The mechanism for generating, formatting, filtering and caching log entries.

...

1. • C++

...

1. • suppliers

...

1. • of

...

1. • logs

...

1. • use

...

1. • the

...

1. • ACE

...

1. • Logging

...

1. • framework

...

1. • with

...

1. • its

...

1. • C++

...

1. • API

...

1. • RD02

...

1. • Java

...

1. • suppliers

...

1. • of

...

1. • logs

...

1. • use

...

1. • the

...

1. • standard

...

1. • Java

...

1. • Logging

...

1. • API

...

1. • RD07

...

1. • Other suppliers of logs, e.g. a Python application, can use the stand-alone ACS Log Server which provides the generic functionality.

The logging subsystem is a very basic one and it should be considered as a part of the infrastructure.
Image Removed Centralized Logging HostHTTP ServerRelational DatabaseEventChannelsClientpush*Centralized Logging*XMLParserDatabaseLogger ClientpushpushFiltering logicWeb ClientXSLTHTTP request/replyClientquerySELECT UPDATESELECTOut of scope of this documentLogs Publisher*write_records*Implements Log interface
Anchor_Ref406581088_Ref406581088a part of the infrastructure.

Image Added

Figure 1: Architecture of the logging system.
The figure shows an overview of the ACS Logging System, based on the CORBA Telecom Log Service and The CORBA Notification Service. The CORBA Telecom Log Service has a Centralized Log object that is responsible for getting the logs from the log suppliers, validating them and submitting them to the Event Channels. The Event Channels push the logs to the subscribed log consumers. The shadowed objects are out of the scope of this document.

...

CORBA Telecom Log Service

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

...

:

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);
};

...

 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
  };

The listings presented here are excerpts from file $TAO_ROOT/orbsvcs/orbsvcs/DsLogAdmin.idl, courtesy of Matthew Brown.:

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".

...

Centralized Log

The Centralized Log that implements the CORBA Telecom Log Service is the facility that receives log entries from the entire system and dispatches them to interested clients. Particularly, it implements the Log interface of the Telecom Log Service. An example of an implementation of such a service is already bundled with TAO's implementation of the Telecom Log Service and can be found under $TAO_ROOT/orbsvcs/Logging_Service.

The Centralized Log uses CORBA for getting the routed logs from the suppliers of logs (publishers) -applications that use the formatting, buffering and pushing capabilities of ACE API, Java Logging API, the ACS Log Service, etc. as they send log records to it.

Thus, the Centralized Logging Service receives an XML string as the "any" parameters in a call to write_records from a supplier. The XML string is formatted according to the specifications described in 3.3 "Syntax of a Log Entry". Since the XML string already contains the timestamp information, that information should take precedence over the actual current timestamp of the receipt of the log entry.

The parsed log entry is then forwarded to appropriate event channel of the CORBA Notification Service which distributes the log entries further. The choice of the event channel depends on the log entry's type and content. For example, log entries related to debugging could be forwarded to a different event channel than those related to archiving. The consumers of logs (clients) can access log entries by subscribing to the event channel of interest.
To store log records, the Centralized Logging Service needs a Database Logger client that has to make the log entries the Centralized Logging Service receives persistent. If such a client exists, other subscribed clients have additional options to access the database:

• Direct access to the SQL database (SELECT).
• Via Database Logging client's query and retrieve methods.
• Via HTTP (the client is a web browser). HTTP server accesses the relational database, transforms the requested entries to XML, transmits them to the browser, which then uses XSLT to transform incoming XML to HTML.

The Centralized Logging Service reconnects to the event channel by default when it detects that the distribution of log entries cannot be performed because of some specific errors. This feature can be disabled by passing the option --no-autoreconnect to the Centralized Logging Service when it's launched.

...

...

Syntax of a Log Entry

Every log entry is represented as an XML document node. The schema of the XML is described in this chapter and the complete schema is provided in appendix A.

...

A Generic Log Entry

A generic log entry representation in XML looks like this:

<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>

...

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_Hlt406572992_Hlt406572992 Anchor_Hlt406572993_Hlt406572993.2

...

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.

...

Source Code Information

The element representing a log entry is equipped with these attributes that convey the location in the source code from which the log entry was generated:

...

These three attributes are optional since they cannot be provided for log entries in each language due to grammar or implementation restrictions. For example, in Java getting the source code line of the log record is very inefficient. Therefore, a log entry would only supply the file name and the method where the log entry originates from.

...

originates from.

...

Runtime Context Information

The log element has six seven attributes that give more information regarding the runtime context in which the log entry is submitted:

...

<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>

...

Log Entry Identification

Every log entry can be supplied with an optional LogId attribute which uniquely identifies the log entry's class (e.g., "file not found", "out of memory", "container starting", etc.).
LogId is particularly useful when used with error messages where it can be used as a key in the help system to look up detailed help/troubleshooting information. Variable sub-elements are also useful in such cases to provide more details about the source of the log entry. For example, if a file could not be found, the following XML could be generated:

<Error TimeStamp="2000-08-23T13:18:27.432"

...

	   File="FileOpener.cpp" Line="131" Routine="FileOpener::Open"

...

       Host="Hurricane" Process="Activator" Thread="EventLoop" SourceObject="GeneralLogger"

...

       LogID="err_File_Not_Found" Priority="8">

...

       <Data Name="FullPath">/home/someuser/file.txt</Data>

...

</Error>

In addition to LogId, an optional Uri attribute is provided, which uniquely identifies the log entry's class. (e.g., log://www.eso.org/acs/errors/OutOfMemory).

...

Priority

The log type implies default priority of a log message. However, if the priority is explicitly specified, then the default is overridden.

<Error TimeStamp="2000-08-23T13:18:27.432"

...

       File="FileOpener.cpp" Line="131" Routine="FileOpener::Open"

...

       Host="Hurricane" Process="Activator" Thread="EventLoop" SourceObject="GeneralLogger"

...

       LogID="err_File_Not_Found" Priority="8">

...

</Error> 

Priority element is optional and is measured as an integer number ranging from 1 to 15, where 1 is lowest and 15 highest priority. The value of 0 indicates the default priority.

...

Data Sub-element

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>

...

 <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>

...

ACS log levels

The ACS log levels are equivalently defined for all ACS programming languages, as defined in §3.4 (for C++), §3.5 (for java) and §3.6 (for python). This section introduces the different log levels defined and its utilization rules. The following is the list of logging levels from lowest to highest level.

...

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. 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

...

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

...

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

...

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):

...