8 Logging, Error Reporting, and Help Information
Logging, error reporting, and finding help information 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. - Help Information
You can find information about valid options that the RESTful services utility provides.
8.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 thejava.util.logging
Java logging utility.
Parent topic: Logging, Error Reporting, and Help Information
8.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
8.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 8-1 describes the Oracle Key Vault RESTful logging property file parameters.
Table 8-1 Log Property File Parameters
Logging Property | Description |
---|---|
|
A comma-delimited list of handler classes to output log messages. Available handlers are The Handlers can have both |
|
Sets the log level for all
|
|
See the description of |
|
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:
|
|
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. |
|
The number of log files to use in the log file rotation. The default is 5. |
|
Specifies the name of a To generate the log entries in the XML format, use To generate the log entries in the plain text, use |
|
Sets the default log level for all See the description of the |
|
Specifies the name of a To generate the log entries in the XML format, use To generate the log entries in the plain text, use |
Parent topic: Configuring Logging
8.1.3 Example: Logging File
Oracle Key Vault RESTful services logging files are based on the java.util.logging
Java logging utility.
Example 8-1 shows a logging file that uses the INFO
logging level.
Example 8-1 Logging File
handlers= java.util.logging.FileHandler
.level=INFO
# default file output is in log directory.
java.util.logging.FileHandler.pattern = ./conf/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
8.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, Error Reporting, and Help Information
8.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
8.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 pfitch --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 pfitch -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
8.3 Help Information
You can find information about valid options that the RESTful services utility provides.
For a list of valid options, execute the okv --help
command. For example:
okv --help Oracle Key Vault REST CLI Version 21.1.0.0.0 Built 11/25/2020 12:56 usage: okv <category> <resource> <action> [--option] --client_wallet <arg> Client wallet --config <arg> OKV REST CLI configuration file(okvrestcli.ini) location --from-json <arg> Input file in JSON --generate-json-input Generate template file in JSON --help List available options --okv_client_config <arg> OKV Client configuration file(okvclient.ora) location --password <arg> Password --profile <arg> Profile name in configuration file(okvrestcli.ini) --server <arg> OKV server IP address or hostname --user <arg> Username
To learn about supported options for a command, you can execute the command with the --generate-json-input
clause. The output includes the supported command line options for the command. For example, suppose you execute the okv admin endpoint create
command using the --generate-json-input
clause:
okv admin endpoint create --generate-json-input
The output indicates the options that you can use when creating an endpoint. In this case, the options are endpoint
, description
, email
, platform
, type
, subgroup
, and unique
.
{
"service" : {
"category" : "admin",
"resource" : "endpoint",
"action" : "create",
"options" : {
"endpoint" : "#VALUE",
"description" : "#VALUE",
"email" : "#VALUE",
"platform" : "#LINUX64|SOLARIS64|SOLARIS_SPARC|HP-UX|AIX|WINDOWS",
"type" : "#ORACLE_DB|ORACLE_NON_DB|ORACLE_ACFS|MYSQL_DB|OTHER",
"subgroup" : "#VALUE|NO SUBGROUP|USE CREATOR SUBGROUP",
"unique" : "#TRUE|FALSE"
}
}
}
Parent topic: Logging, Error Reporting, and Help Information