Bug 962507 - Deprecated operations should be replaced
Deprecated operations should be replaced
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Logging, Documentation (Show other bugs)
6.1.0
Unspecified Unspecified
low Severity high
: ER7
: EAP 6.3.0
Assigned To: sgilda
Russell Dickenson
: Documentation, EasyFix
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-05-13 13:39 EDT by James Perkins
Modified: 2014-09-29 19:21 EDT (History)
6 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Instance Name: Not Defined Build: CSProcessor Builder Version 1.8 Build Name: 11865, Administration and Configuration Guide-6.1-3 Build Date: 13-05-2013 12:52:38
Last Closed: 2014-06-28 11:39:29 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description James Perkins 2013-05-13 13:39:03 EDT
Title: Configure a Async Log Handler in the CLI

Describe the issue:
The documentation uses a few deprecated operations. It looks like a couple of the other topics also use deprecated operations. I can open a bug for each topic if that is preferred.


Suggestions for improvement:
:change-log-level(level="INFO") should be changed to :write-attribute(name="LEVEL", value="INFO")

:assign-handler(name="NFS_HANDLER") should be changed to :add-handler(name="NFS_HANLER")

:unassign-handler(name="NFS_HANDLER") should be changed to :remove-handler(name="NFS_HANLER")

Additional information:
Basically write-attribute should be preferred and the add-handler/remove-handler should be preferred for loggers and the async-handler.
Comment 4 James Perkins 2014-04-17 12:47:38 EDT
Is this still an issue? I don't know the link to the latest documentation, but I'm happy to review it if needed.
Comment 5 Nikoleta Ziakova 2014-04-18 01:53:39 EDT
This is the latest documentation (for EAP 6.3.0):
http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html

It seems that the above mentioned changes have not been done yet.
Comment 6 gsheldon 2014-04-21 18:37:40 EDT
This was incorrectly reassigned to jperkins.

Assigning back to twells.
Comment 7 sgilda 2014-05-20 11:49:57 EDT
Modified the following topics:

1. Replace deprecated 'change-log-level' with 'write-attribute':

Configure a Console Log Handler in the CLI [8857]
Configure a File Log Handler in the CLI [8859]
Configure a Periodic Log Handler in the CLI [8861]
Configure a Size Log Handler in the CLI [8863]
Configure a Async Log Handler in the CLI [8865]
Configuring a Logging Profile using the CLI [14119]


2. Replace deprecated 'assign-handler' with 'add-handler'

Configuring a Logging Profile using the CLI [14119]
Configure a Log Category in the CLI [8856]
Example Logging Profile Configuration [14121]


3. Replace deprecated 'unassign-handler' with 'remove-handler'

Configure a Log Category in the CLI [8856]


It does not appear the relate root-logger commands were changed to match the others, so I did not replace the "root-logger-assign-handler" or ":root-logger-unassign-handler' commands in the following topic:

Configure the Root Logger with the CLI [8854]
Comment 8 sgilda 2014-05-21 14:22:28 EDT
Changes can be verified at the following links: 

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configure_a_Console_Log_Handler_in_the_CLI

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configure_a_File_Log_Handler_in_the_CLI1

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configure_a_Periodic_Log_Handler_in_the_CLI1

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configure_a_Size_Log_Handler_in_the_CLI

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configure_a_Async_Log_Handler_in_the_CLI1

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configuring_a_Logging_Profile_using_the_CLI

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configuring_a_Logging_Profile_using_the_CLI

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Configure_a_Log_Category_in_the_CLI1

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#Example_Logging_Profile_Configuration
Comment 9 Nikoleta Ziakova 2014-06-02 08:40:18 EDT
Some additional modifications are needed here:

(1) Operation root-logger-assign-handler is deprecated, try:
/subsystem=logging/root-logger=ROOT:read-operation-description(name=root-logger-assign-handler)
         "deprecated" => {
            "since" => "1.2.0",
            "reason" => "Use the add-handler operation."
         }

(2) Operation root-logger-unassign-handler is deprecated, try:
/subsystem =logging/root-logger=ROOT:read-operation-description(name=root-logger-unassign-handler)
         "deprecated" => {
            "since" => "1.2.0",
            "reason" => "Use the remove-handler operation."
         }

(3) Operation change-file is deprecated, try:
/subsystem =logging/file-handler=accounts_log:read-operation-description(name=change-file)
        "deprecated" => {
            "since" => "1.2.0",
            "reason" => "Use the write-attribute operation."
        }

(4) Operation assign-subhandler is deprecated, try:
/subsystem =logging/async-handler=NFS_LOGS:read-operation-description(name=assign-subhandler)
        "deprecated" => {
            "since" => "1.2.0",
            "reason" => "Use the add-handler operation."
        }

(5) Operation unassign-subhandler is deprecated, try:
/subsystem =logging/async-handler=NFS_LOGS:read-operation-description(name=unassign-subhandler)
        "deprecated" => {
            "since" => "1.2.0",
            "reason" => "Use the remove-handler operation."
        }

(6) Example 13.10. Removing a log handler uses non-existent operation root-logger-remove-handler. It should use the remove-handler operation.

(7) Name of the Log Level attribute is "level", not "LEVEL". There are more occurrences in the chapter, e.g.:
/subsystem =logging/console-handler=HANDLER:write-attribute(name="LEVEL", value="INFO")
should be replaced by:
/subsystem =logging/console-handler=HANDLER:write-attribute(name="level", value="LEVEL")

(8) The output of read-resource operation has changed, please use the current output for all occurrences of read-resource command example.

(9) Redundant "[standalone@localhost:9999 /]" in some examples in the chapter, please remove them.

I can create a separate BZ for the last 2 items (8) and (9) if you like - they are not blocker issues. I will leave them here if you wish to fix it all in one place.
Comment 11 James Perkins 2014-06-02 14:17:47 EDT
Some of these have been mentioned earlier, but I just wanted to create a comprehensive list of invalid operations or operations that should be changed. This list is only for CLI documentation changes:

Section 13.3.1:
Both in the documentation and code sample:
 * root-logger-assign-handler needs to be changed to assign-handler.
 * root-logger-unassign-handler needs to be changed to remove-handler

Example 13.10:
This section is about generic handlers yet the example shows removing a logger from the root logger. The example should read:
[standalone@localhost:9999 /] /subsystem=logging/logger=CATEGORY:remove-handler(name="AccountsNFSAsync")

Section 13.3.3 to 13.3.7
The examples that write a level use LEVEL (uppercase) as the attribute name. The name should be "level" (lowercase). Corrected example for console-handler (13.3.3):
/subsystem=logging/console-handler=HANDLER:write-attribute(name="level", value="INFO") 

Section 13.3.4 to 13.3.6
The sections that refer to "change-file" should use the "write-attribute" operation. Corrected example for file-handler (13.3.4)
/subsystem=logging/file-handler=HANDLER:write-attribute(name="file", value={"path"="PATH", "relative-to"="DIR"}) 


Section 13.3.7:
The assign-subhandler and unassign-handler should be replaces with add-handler and remove-handler operations.
Comment 12 sgilda 2014-06-02 16:54:33 EDT
Addressed all issues but (8) in comment 9. That will require some effort.
I believe I addressed all issues in comment 11.

Modified the following topics:

Configure the Root Logger with the CLI [8854]
Configure a File Log Handler in the CLI [8859]
Configure a Periodic Log Handler in the CLI [8861]
Configure a Size Log Handler in the CLI [8863]
Configure a Log Category in the CLI [8856]
Configure a Async Log Handler in the CLI [8865]
Configure a Console Log Handler in the CLI [8857]
Configuring a Logging Profile using the CLI [14119]
Example Logging Profile Configuration [14121]
Enabling Role-Based Access Control [23749]
Comment 13 James Perkins 2014-06-02 17:10:03 EDT
Looks good to me.
Comment 14 sgilda 2014-06-02 17:29:04 EDT
Thanks James.

I changed the output for the read-resource for the following:
Configure the Root Logger with the CLI [8854]
Configure a Log Category in the CLI [8856]
Comment 16 Nikoleta Ziakova 2014-06-03 03:15:13 EDT
I checked the preview, issues 1-7 are all OK.

I have found some 8 and 9 and noticed a new one - some CLI examples are without a title. I am going to create a new BZ for these issues because they are not blockers and I can verify this one once it is ON_QA.
Comment 18 Nikoleta Ziakova 2014-06-05 08:18:30 EDT
I haven't noticed this one, apologies for that:

The write-attribute operation requires arguments "name" and "value" instead of "file". 

It means that instead of 
write-attribute(file={"path"=>"accounts-debug.log", "relative-to"=>"jboss.server.log.dir"})
it should be 
write-attribute(name"file", value={"path"=>"accounts-debug.log", "relative-to"=>"jboss.server.log.dir"})

It affects these 3 examples:
Example 13.26. Change the file to which the log handler writes
Example 13.35. Change the file to which the log handler writes
Example 13.45. Specify the file to which the log handler will write

6 (hopefully last) modifications needed:
(1) Change the file to which the log handler writes
/subsystem=logging/file-handler=HANDLER:write-attribute(file={"path"=>"PATH", "relative-to"=>"DIR"}) 
==>
/subsystem=logging/file-handler=HANDLER:write-attribute(name="file",value={"path"=>"PATH", "relative-to"=>"DIR"}) 

(2) Example 13.26. Change the file to which the log handler writes
/subsystem=logging/file-handler=accounts_log:write-attribute(file={"path"=>"accounts-debug.log", "relative-to"=>"jboss.server.log.dir"})
==> 
/subsystem=logging/file-handler=accounts_log:write-attribute(name="file",value={"path"=>"accounts-debug.log", "relative-to"=>"jboss.server.log.dir"})

(3) Change the file to which the log handler writes
/subsystem=logging/periodic-rotating-file-handler=HANDLER:write-attribute(file={"path"=>"PATH", "relative-to"=>"DIR"}) 
==>
/subsystem=logging/periodic-rotating-file-handler=HANDLER:write-attribute(name="file",value={"path"=>"PATH", "relative-to"=>"DIR"}) 

(4) Example 13.35. Change the file to which the log handler writes
/subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(file={"path"=>"daily-debug.log", "relative-to"=>"jboss.server.log.dir"})
==>
/subsystem=logging/periodic-rotating-file-handler=HOURLY_DEBUG:write-attribute(name="file",value={"path"=>"daily-debug.log", "relative-to"=>"jboss.server.log.dir"})

(5) Specify the file to which the log handler will write
/subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(file={"path"=>"PATH", "relative-to"=>"DIR"}) 
==>
/subsystem=logging/size-rotating-file-handler=HANDLER:write-attribute(name="file", value={"path"=>"PATH", "relative-to"=>"DIR"}) 

(6) Example 13.45. Specify the file to which the log handler will write
/subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(file={"path"=>"accounts_trace.log", "relative-to"=>"jboss.server.log.dir"}) 
==> 
/subsystem=logging/size-rotating-file-handler=ACCOUNTS_TRACE:write-attribute(name="file",value={"path"=>"accounts_trace.log", "relative-to"=>"jboss.server.log.dir"})
Comment 20 Nikoleta Ziakova 2014-06-10 06:41:51 EDT
Verified in EAP 6.3.0.ER7, revision 6.3.0-22

Note You need to log in before you can comment on or make changes to this bug.