13.3.4. Configure a File Log Handler in the CLI

File log handlers can be added, removed and edited in the CLI.
The main tasks you will perform to configure a file log handler are:
  • Add a new file log handler.
  • Display the configuration of a file log handler
  • Set the handler's log level.
  • Set the handler's appending behavior.
  • Set whether the handler uses autoflush or not.
  • Set the encoding used for the handler's output.
  • Specify the file to which the log handler will write.
  • Set the formatter used for the handler's output.
  • Remove a file log handler.

Important

When configuring a log handler in a logging profile the root of the configuration path is /subsystem=logging/logging-profile=NAME/ instead of /subsystem=logging/.
Add a file log handler
Use the add operation with the following syntax. Replace PATH with the filename for the file that the log is being written to. Replace DIR with the name of the directory where the file is to be located. The value of DIR can be a path variable.
 /subsystem=logging/file-handler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"}) 

Example 13.20. Add a file log handler

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:add(file={"path"=>"accounts.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"}
[standalone@localhost:9999 /]
Display a file log handler configuration
Use the read-resource operation with the following syntax. Replace HANDLER with the name of the file log handler.
 /subsystem=logging/file-handler=HANDLER:read-resource 

Example 13.21. Using the read-resource operation

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:read-resource
{
    "outcome" => "success",
    "result" => {
        "append" => true,
        "autoflush" => true,
        "encoding" => undefined,
        "file" => {
            "path" => "accounts.log",
            "relative-to" => "jboss.server.log.dir"
        },
        "filter" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => undefined
    }
}
[standalone@localhost:9999 /]
Set the Log level
Use the change-log-level operation with the following syntax. Replace HANDLER with the name of the file log handler. Replace LEVEL with the log level that is to be set.
 /subsystem=logging/file-handler=HANDLER:change-log-level(level="LEVEL") 

Example 13.22. Changing the log level

/subsystem=logging/file-handler=accounts_log:change-log-level(level="DEBUG")
{"outcome" => "success"}
[standalone@localhost:9999 /]
Set the append behaviour
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the file log handler. Replace BOOLEAN with false if you required that a new log file be created each time the application server is launched. Replace BOOLEAN with true if the application server should continue to use the same file.
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="append", value="BOOLEAN") 

Example 13.23. Changing the append property

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:write-attribute(name="append", value="true")
{
    "outcome" => "success",
    "response-headers" => {
        "operation-requires-reload" => true,
        "process-state" => "reload-required"
    }
}
[standalone@localhost:9999 /]
JBoss EAP 6 must be restarted for this change to take effect.
Set the Auto Flush
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the file log handler. Replace BOOLEAN with true if this handler is to immediately write its output.
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="autoflush", value="BOOLEAN") 

Example 13.24. Changing the autoflush property

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:write-attribute(name="autoflush", value="false")
{
    "outcome" => "success",
    "response-headers" => {"process-state" => "reload-required"}
}
[standalone@localhost:9999 /]
JBoss EAP 6 must be restarted for this change to take effect.
Set the Encoding
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the file log handler. Replace ENCODING with the name of the required character encoding system.
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="encoding", value="ENCODING") 

Example 13.25. Set the Encoding

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:write-attribute(name="encoding", value="utf-8")     
{"outcome" => "success"}
[standalone@localhost:9999 /]
Change the file to which the log handler writes
Use the change-file operation with the following syntax. Replace PATH with the filename for the file that the log is being written to. Replace DIR with the name of the directory where the file is to be located. The value of DIR can be a path variable.
 /subsystem=logging/file-handler=HANDLER:change-file(file={"path"=>"PATH", "relative-to"=>"DIR"}) 

Example 13.26. Change the file to which the log handler writes

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:change-file(file={"path"=>"accounts-debug.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"}
[standalone@localhost:9999 /]
Set the Formatter
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the file log handler. Replace FORMAT with the required formatter string.
 /subsystem=logging/file-handler=HANDLER:write-attribute(name="formatter", value="FORMAT") 

Example 13.27. Set the Formatter

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts-log:write-attribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
{"outcome" => "success"}
[standalone@localhost:9999 /]
Remove a File Log Handler
Use the remove operation with the following syntax. Replace HANDLER with the name of the file log handler to be removed.
 /subsystem=logging/file-handler=HANDLER:remove 

Example 13.28. Remove a File Log Handler

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:remove
{"outcome" => "success"}
[standalone@localhost:9999 /]
A log handler can only be removed if it is not being referenced by a log category or an async log handler.