1. RESTful Services Administrator's Guide
  2. Logging and Error Reporting

11 Logging and Error Reporting

Logging and error reporting can help with troubleshooting issues that may arise.

  • Configuring Logging
    You can configure a variety of ways to handle logging, including specifying a range of different logging levels.
  • Error Reporting
    The RESTful Service utility has robust error reporting to debug in order to run RESTful service commands quickly and successfully.

11.1 Configuring Logging

You can configure a variety of ways to handle logging, including specifying a range of different logging levels.

  • About Configuring Logging
    Using RESTful service logging configuration, you generate diagnostic logging information to help with troubleshooting issues that may arise.
  • Log Property File Parameters
    The log property file has parameters to control aspects such as handlers, log levels, output file names, and so on.
  • Example: Logging File
    Oracle Key Vault RESTful services logging files are based on the java.util.logging Java logging utility.

Parent topic: Logging and Error Reporting

11.1.1 About Configuring Logging

Using RESTful service logging configuration, you generate diagnostic logging information to help with troubleshooting issues that may arise.

Oracle Key Vault RESTful service logging is based on the customized Java logging utility, java.util.logging.

The RESTful service logging configuration is specified in a log property file. In the log property file, you can accomplish the following:

  • Specify whether log messages are sent to the console, to a file or to both
  • Specify the file names where log messages are written
  • Specify the level of detail in the log messages.
  • Specify the log formatter to use. You can choose XML or regular text format. Each log entry shows class, object, and method, along with the time when the log entry is generated.

To specify the log property file in the Oracle Key Vault RESTful services configuration file (okvrestcli.ini), you use the log_property parameter.

Parent topic: Configuring Logging

11.1.2 Log Property File Parameters

The log property file has parameters to control aspects such as handlers, log levels, output file names, and so on.

Table 11-1 describes the Oracle Key Vault RESTful logging property file parameters.

Table 11-1 Log Property File Parameters

Logging Property Description

handlers

A comma-delimited list of handler classes to output log messages. Available handlers are java.util.logging.FileHandler and java.util.logging.ConsoleHandler.

The FileHandler can either write to a specified file, or it can write to a rotating set of files.

Handlers can have both ConsoleHandler and FileHandler separated by a comma (,).

.level

Sets the log level for all FileHandler instances. Levels are as follows:

  • ALL indicates that all messages should be logged.
  • FINE is a message level providing tracing information.
  • FINER indicates a fairly detailed tracing message.
  • FINEST indicates a highly detailed tracing message.
  • INFO is a message level for informational messages.
  • OFF is a special level that can be used to turn off logging.
  • SEVERE indicates a serious failure.
  • WARNING indicates a potential problem.

java.util.logging.FileHandler.level

See the description of .level for descriptions of these levels that you can use in java.util.logging.FileHandler.level

java.util.logging.FileHandler.pattern

Specifies a pattern for generating the output file name. A pattern consists of a string that includes the following special components that will be replaced at runtime:

  • / is the local path name separator.
  • %t is the system temporary directory.
  • %h is the value of the user.home system property.
  • %g is the generation number to distinguish rotated logs. If no %g field has been specified and the file count is greater than one, then the generation number will be added to the end of the generated file name, after a dot.
  • %u is a unique number to resolve conflicts between simultaneous Java processes.
  • %% translates to a single percent sign %.

java.util.logging.FileHandler.limit

The maximum size of the file, in bytes. If this is 0, then there is no limit. The default is 200000. Logs larger than the specified limit roll over to the next log file.

java.util.logging.FileHandler.count

The number of log files to use in the log file rotation. The default is 5.

java.util.logging.FileHandler.formatter

Specifies the name of a Formatter class to use.

To generate the log entries in the XML format, use java.util.logging.XMLFormatter.

To generate the log entries in the plain text, use com.oracle.okv.rest.log.OkvFormatter.

java.util.logging.ConsoleHandler.level

Sets the default log level for all ConsoleHandler instances.

See the description of the java.util.logging.FileHandler.level for descriptions of these levels.

java.util.logging.ConsoleHandler.formatter

Specifies the name of a Formatter class to use.

To generate the log entries in the XML format, use java.util.logging.XMLFormatter.

To generate the log entries in the plain text, use com.oracle.okv.rest.log.OkvFormatter.

Parent topic: Configuring Logging

11.1.3 Example: Logging File

Oracle Key Vault RESTful services logging files are based on the java.util.logging Java logging utility.

Example 11-1 shows a logging file that uses the INFO logging level.

Example 11-1 Logging File

handlers= java.util.logging.FileHandler
.level=INFO

# default file output is in log directory.
java.util.logging.FileHandler.pattern = /usr/local/okv/okvrestcli.log
java.util.logging.FileHandler.limit = 200000
java.util.logging.FileHandler.count = 4
java.util.logging.FileHandler.level = INFO
java.util.logging.FileHandler.formatter = com.oracle.okv.rest.log.OkvFormatter

Parent topic: Configuring Logging

11.2 Error Reporting

The RESTful Service utility has robust error reporting to debug in order to run RESTful service commands quickly and successfully.

  • About Error Reporting
    Depending upon the logging configuration, Oracle Key Vault may write additional information about the failure to the log file.
  • Command Line Error Reporting
    Error reporting captures both faulty actions, such as incorrect passwords, and successful command executions.

Parent topic: Logging and Error Reporting

11.2.1 About Error Reporting

Depending upon the logging configuration, Oracle Key Vault may write additional information about the failure to the log file.

The specific error will be reported, with suggestions for corrective actions. Error reporting is common to all REST commands.

The first thing to do when investigating a command failure is to look into the log file. If you have not created a custom log file in a location of your choice, then you can look at the default log file, okvrestcli.log in the conf directory

To see all the messages from the Oracle Key Vault server during command execution, you can set the appropriate logging level, log file name, and the log file location in the configuration file.

The RESTful service utility reports errors such as the failure to locate a file or an environment variable like JAVA_HOME, incorrect command syntax, and incorrect passwords.

Parent topic: Error Reporting

11.2.2 Command Line Error Reporting

Error reporting captures both faulty actions, such as incorrect passwords, and successful command executions.

Example: Error: Incorrect Password

okv admin endpoint update --user psmith --endpoint hr_db_ep --description 'HR DB Endpoint'
Password: password
{
  "result" : "Failure",
  "message" : "Invalid username or password. Try again after 5 seconds."
}

Example: Successful Service Command Execution

okv admin endpoint update --user psmith -endpoint hr_db_ep --description 'HR DB Endpoint'
Password: password
{
  "result" : "Success"
}

Example: Log File Entry

In addition to the helpful error and usage messages, an entry for the action is logged in the log file with the date.

Thu Oct 29 15:50:19 PDT 2020::com.oracle.okv.rest.cli.okv::main::1::[backup, history, list, --max, 5]
Thu Oct 29 15:50:19 PDT 2020::com.oracle.okv.rest.cli.backup.BackupProcessManager::<init>::1::https://10.240.112.193:5695/okv/cloud/api
Thu Oct 29 15:50:19 PDT 2020::com.oracle.okv.rest.cli.backup.BackupProcessManager::<init>::1::/scratch/dopark/demo/EP1/ssl
Thu Oct 29 15:50:19 PDT 2020::com.oracle.okv.rest.cli.backup.BackupOptionsProcessor::takeOption::1::BackupOptionBean 
[name=null, startTime=null, destination=null, type=null, max=5, interval=null, passphrase=null, 
transferMethod=null, hostName=null, port=null, path=null, userName=null, authenticationMethod=null, 
psd=null, cluster=false]

Parent topic: Error Reporting