GlassFish Server Open Source Edition 3.2 - Logging One Pager

1. Introduction

1.1. Project/Component Working Name

Logging

1.2. Name(s) and e-mail address of Document Author(s)/Supplier

Naman Mehta : naman_mehta@java.net

1.3. Date of This Document

• 20/04/2011 Initial Draft
• 27/04/2011 Incorporated changes after comment from Siva

2. Project Summary

2.1. Project Description

Enhance logging framework to support GlassFish use as a PaaS environment. Adding new features to the existing logging framework to ease of use.

2.2. Risks and Assumptions

PaaS related feature depends on the PaaS infrastructure availability. Any delay in the delivery of the depended features will affect the delivery of the logging feature.

3. Problem Summary

• Enhance logging framework to support GlassFish use as a PaaS environment
  We need to support this for v3.2 feature parity. Provision PaaS admin logging to respective log files. Provision log records from IaaS Management Service (IMS), Orchestrator (O), Elasticity Manager (EM) and Domains Manager (DM) needs to be logged under DAS. Augment the Service Provider SPI to contain method to list/set/delete log levels and collect log files. (Priority P1)
  TBD: We need to have a discussion around this once the initial arch is completed.

• Enhance logging related commands to support GlassFish use as a PaaS environment
  We need to enhance set of the logging commands for v3.2 feature parity. Enhance existing log commands to set/list/delete log levels for given service(e.g. dbms/mq/lb). Enhance collect-log-files command to collect log files from services used by respective instances. (Priority P2)
  TBD: We need to have a discussion around this once the initial arch is completed.

• Add intelligence for log file refresh during download from remote machine
  Enhancement from 3.1 release. If instance is not part of localhost we used to download file to DAS and uses in Log Viewer. So provide intelligence to avoid downloading of log file every time from remote machine. (Priority P1)

• Date-based log rotation
  Enhancement from 3.1 release. Allow user to set the parameter under logging.properties file and based on that rotate the server.log file when date changes. (Priority P1)

• Add new logging command to delete log levels 'delete-log-levels'
  Enhancement from 3.1 release. Add new command for logging which deletes log levels from logging.properties files. Respective changes are needed in REST and Admin GUI. (Priority P1)

• Add 'Load Defaults' button under Logger Settings page
  Enhancement from 3.1 release. Add new 'Load Default' button to reset the logger setting under Logger Settings page. Respective changes are needed in REST and Admin GUI. (Priority P1)

• Log Analyzer Tool, which is the extension of collect-log-files command
  Enhancement from 3.1 release. Add new button "Log Analyzer" under logger setting page which allow user to view all collected log files under zip in the single screen in different tab. Respective changes are needed in REST and Admin GUI. Major changes needed under logging back end code to provision the same. (Priority P3)
  TBD: We need to have a discussion with Admin team to move further on this.

• Support Elastic BeanStalk related changes in logging
  We need to support this for v3.2 feature parity. Enhance logging to support GF as one of the container in Elastic BeanStalk.
  TBD: We need to have a discussion around this once the initial arch is completed.

4. Technical Description

4.1. Details

4.1.1 Enhancement for logging in a PaaS environment

• Enhance logging framework to support GlassFish use as a PaaS environment.

This document describes the high level design for supporting PaaS infrastructure. We will provide v3.2 feature parity for enhancing logging framework to support GlassFish use as a PaaS environment.

In 3.1, we provided different log levels for cluster, stand alone instance and DAS. Based on the log levels set by user, log records are logged under appropriate log files.

PaaS admin Logging In 3.2, Provision PaaS admin Logging (IaaS Management Service (IMS), Orchestrator (O), Elasticity Manager (EM) and Domains Manager (DM)) to be part of DAS logging only (default location is <AS_HOME>/domains/domain1/logs/server.log). Clustered instances and stand alone instances log records are logged under respective instance log files.

Service level Logging In 3.2, All the log records related to Service level logging would be part of respective service provider(e.g dbms, lb etc.). So provide SPI for service provisioning which contains method to list log levels, set log levels, delete log levels and reading log files. This needs to be implemented by service provider (e.g dbms, lb etc.). On getting request from CLI or Admin GUI, it's redirected to appropriate service provider which returns/sets the data based on the request.

In 3.1, we are setting/listing data from the DAS and replication framework/SCP is used to replicate files/downloading files from the remote instance which is used by logging back end code. So in 3.2, if we have DAS on machine1, cluster instance is running on machine2 which uses any service like dbms/mq running on machine3 then service provider need to implement methods for getting/setting data.

The basic flow is from GUI/Command Line -> Logging Back end Code -> Orchestrator -> Specific Service Provider and vice versa.

• Enhance logging related commands to support GlassFish use as a PaaS environment

We need to enhance logging related commands for v3.2 feature parity.

All the logging CLI commands need to be set/list/delete log levels for given service. All list/set/delete-log-levels work with a servicename as the "target" argument. Service logging for global shared provisioned services and application scoped provisioned services would be supported. The log levels may be different per Service implementation(MySQL could have a different logging level interpretation – ie may not have a INFO, FINE etc), and the plugin that integrates the Service Implementation into the Orchestrator would handle the translation of log-levels. The Service implementation's log would not use the logging level terminology of GlassFish. It depends on, how the service provider implements the provided SPI.

asadmin list-log-levels --dbmsservice

asadmin set-log-levels --target=dbmsservice dbms.package=INFO

asadmin delete-log-levels --target=dbmsservice dbms.package

We already have command to collect-log-files which needs to be enhanced for collecting log files from services used by instances. Service provider need to implement the method which returns log file from respective host to DAS machine.

4.1.2 Enhancements for logging from previous release

• Add intelligence for log file refresh during download from remote machine

Enhancement from 3.1 release. We are using scp to download files from remote machine when user clicks 'View Log File' button for given instances. If instance is not part of localhost we used to download file to DAS and uses in Log Viewer.

Before downloading files from remote machine check the file size on DAS and compare same with on Remote machine. If size is different then use the SCP code to download the same. To support this requirement provide mechanism to get the file attributes on DAS and Remote machine.

• Date-based log rotation

Enhancement from 3.1 release. Allow user to set the parameter under logging.properties file and based on that rotate the server.log file when date changes.

Add new logging attributes under logging.properties template like 'com.sun.enterprise.server.logging.GFFileHandler.rotationOnDateChange=false'. Default value is false. User can change the value of this attribute by using set-log-attributes command or Admin GUI. If the value is true, then server.log file is rotated when date changes.

If user had selected date based rotation then it will not consider rotation based on time (com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes).

• Add new logging command to delete log levels 'delete-log-levels'

We need to support for this for v3.2 feature parity. Add new command for logging which deletes log levels from logging.properties file.

This command will take logger name as arguments. User can give multiple logger name as ':' separated. The default value for target is server. User can give target value as cluster, stand alone instance or any config name. Based on the target this command would delete log levels from appropriate logging.properties file.

asadmin delete-log-levels dbms.package

asadmin delete-log-levels --target=cluster1 dbms.package

asadmin delete-log-levels --target=cluster1 dbms.package:dbms1.package:dbms2.package

Respective changes are needed in REST and Admin GUI. REST needs to provide API for this command which is used by Admin GUI. Admin GUI needs to provide 'Delete Log Levels' button under Logger Settings page.

• Add 'Load Defaults' button under Logger Settings page

We need to support for this for v3.2 feature parity. Add new 'Load Default' button to reset the logger setting under Logger Settings page.

If user has changed log attributes and log levels for given target. Now to reset them to original value there is no option provided on Logger Settings page. To give the support for load default values two new hidden commands are provided like _load-default-log-attributes and _load-default-log-levels. _load-default-log-attributes is used to set default log attributes and _load-default-log-levels is used to set default log levels.

This command will return values from logging.properties file under template.

Respective changes are needed in REST and Admin GUI. REST needs to provide API for this command which is used by Admin GUI. Admin GUI needs to provide 'Load Default' button under Logger Settings page.

• Log Analyzer Tool, which is the extension of collect-log-files command

Enhancement from 3.1 release. Allow user to view all log files under zip in the single screen in different tab.

As we we had came up with collect-log-files command in v3.1 release. This command would collect log files from clustered instances and created zip under DAS. Now, how to view the content of log files? Solution as on today, unzip this zip files in one folder and open log files one by one in text editor. This can work but not user friendly.

So to make it user friendly and allow user to navigate from one instance to another instance, we need to come up with this tool. It would be useful for end user to view log files for all instances on single screen.

Using this tool user is allowed to select available collected log zip files. On selection of particular zip file it creates different tab based on number of instances. And each tab shows log record under tabular form for particular instance. It supports text search through which user can filter the data. On click of particular log record it opens the detail log record. Here, user can traverse through different instance by just clicking the tab.

Send details to Anissa and Jason about provisioning the same. This tool needs major changes on GUI side and REST API side and logging back end code.

4.1.3 Support Elastic BeanStalk related changes in logging

If we plan to support GF as one of the container for BeanStalk then we need to implement set of the APIs in logging module to get the server/instance log data to BeanStalk.

4.2. Bug/RFE Number(s)

4.2.1 RFE

• Add intelligence for log file refresh during download from remote machine, 15849
• Date-based log rotation, 8894
• Add 'Load Defaults' button under Logger Settings page, 16018
• Add new logging command to delete log levels 'delete-log-levels', 16337
• The Umbrella RFE for Enhancement for logging in a PaaS environment, 16494

4.2.2 Bug

• Cannot start standalone instance, 16162
• Add ShoalLogger.level=CONFIG to glassfish/lib/templates/logging.properties, 16139
• NPE in UniformLogFormatter when trying to log collections/maps with null values/keys, 16099
• asadmin collect-log-files --target clustername should collect more information, 16088
• Log Levle set for Handler is not working in current GF, 16057
• Replace early logger messages in the code with hk2 service, 15358
• Provide better user experience to customize Eclipselink loggers, 11274
• com.sun.aas.instanceName in log configuration not used initially, 16327
• If user changes GFFileHandler.file attribute and not restart the server, 16451
• Log Viewer: server.log not found on remote system with custom node directory, 15807

4.3. Interfaces

4.3.1 Enhancement for logging in a PaaS environment

• Public Interfaces

  Method	Former Stability (if changing)	Class Name	Comments
  boolean isLoggingSupported()	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to check logging settings are supported for given service or not
  String[] getValidLogLevels()	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to get valid log levels for given service
  boolean updateLoggingProperties(Map<String, String> properties) throws Exception	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to update/set logging properties for given service. Here, key is the logger name and value is the logging level
  boolean deleteLoggingProperties(Lis<String> properties) throws Exception	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to delete logging properties for given service. Here, list contains logger names
  Map<String, String> getLoggingProperties() throws Exception	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to get logging properties for specific service. Here, key is the logger name and value is the logging level
  String[] getAllLoggingFileNames() throws Exception	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to get all logging file names for given service
  boolean downloadAllLoggingFiles(String localPath) throws Exception	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to download all logging files for given service
  boolean downloadLoggingFile(String fileName, String localPath) throws Exception	New	org.glassfish.cloud.service.spi.LoggingProvisionedService	Method to download specific logging file for given service

• Private Interfaces
  N/A.

• Deprecated/Removed Interfaces
  N/A.

• New Classes to Support the functionality
  N/A.

4.3.2 Enhancements for logging from previous release

• Public Interfaces

• Private Interfaces
  N/A.

• Deprecated/Removed Interfaces
  N/A.

• New Classes to Support the functionality

• Need to come up with set of classes if we plan to support Log Analyzer tool. Also, respective changes needed by REST and GUI.

4.4. Doc Impact

Update man pages for the new/modified CLI commands and PaaS related changes.

4.5. Admin/Config Impact

• CLI
  New command is added for Delete log levels. Added hidden command to load default log levels and attributes from logging.properties templates.

• GUI
  Need updates on Logger Settings page with 'Delete Log Levels', 'Delete Log Attributes' and 'Load Default' button. Respective changes needed for REST API.

4.6. HA Impact

No impact.

4.7. I18N/L10N Impact

Minor changes needed for Delete Log Levels command properties.

4.8. Packaging, Delivery & Upgrade

• Packaging
  No impact.

• Delivery
  No impact.

• Upgrade and Migration
  No impact.

4.9. Security Impact

No impact.

4.10. Compatibility Impact

No compatibility impact.

4.11. Dependencies

• Internal Dependencies
• Basic infrastructure: Document

• External Dependencies
  None

4.12. Testing Impact

• PaaS Related Testing
  Changes related to PaaS for logging.

• New CLI commands
  Delete log levels command.

• GUI Testing
  Load Default and Delete Log Levels/Attributes.

• Log Rotation
  Date Based log rotation.

• Log Analyzer Tool
  If we come up with log analyzer then need to be tested.

4.13 Reference Documents

• 3.2 Wiki: Wiki Link

5. Schedule

• Enhance logging framework to support GlassFish use as a PaaS environment - having design dependency
• Enhance logging related commands to support GlassFish use as a PaaS environment - having design dependency
• Add intelligence for log file refresh during download from remote machine - MS3
• Date-based log rotation - MS3
• Add new logging command to delete log levels 'delete-log-levels' - MS3
• Add 'Load Defaults' button under Logger Settings page - MS3
• Log Analyzer Tool, which is the extension of collect-log-files command - having design dependency

6. Open Issues

• Need to discuss with Prasad, Rajiv, Shreedhar & Shiva about the PaaS related changes for logging. I added above details as per my understanding. Need to provide SPI details for service provisioning in this document(under section 4.3.1) after the discussion.

Hi Naman, would it be possible to consider these issue from the Glassfish JIRA for inclusion: GLASSFISH-6666: Ability to log to SLF4J GLASSFISH-11129: Weld encounters SLF4J error: Class path contains multiple SLF4J bindings The issue here is that the Glassfish JARs reference other JARs which in turn include duplicate SLF4J bindings. It would be great if Glassfish could use the common SLF4J interface in order to support different loggers. This would be the self-made logging bridges which sometimes do not integrate with Glassfish very well. What do you think? Cheers, Jörg Posted by joergthoennes at Apr 20, 2011 00:37