From 600f0c44cd0cc7f064776d31de50e9006d3476c4 Mon Sep 17 00:00:00 2001 From: Martin D'Souza Date: Sun, 18 Jun 2017 21:59:27 -0600 Subject: [PATCH] doc fixes --- docs/Change Logs.md | 26 ++-- docs/Development Guide.md | 22 +-- docs/Installation.md | 42 +++--- docs/Logger API Template.md | 10 +- docs/Logger API.md | 286 ++++++++++++++++++------------------ docs/Plugins.md | 22 +-- 6 files changed, 204 insertions(+), 204 deletions(-) diff --git a/docs/Change Logs.md b/docs/Change Logs.md index 5cecfa3..30324af 100644 --- a/docs/Change Logs.md +++ b/docs/Change Logs.md @@ -1,7 +1,7 @@ This page contains all of Logger's Change Logs. Starting in version 3.0.0 onwards, only major tickets will be listed here. To see a complete list of all the issues for each version, review the appropriate release page. -##Change Log 3.1.1 +## Change Log 3.1.1 [Download](https://github.com/OraOpenSource/Logger/raw/master/releases/logger_3.1.1.zip)
[Release Page](https://github.com/OraOpenSource/Logger/issues?utf8=%E2%9C%93&q=milestone%3A%22Release+3.1.1%22)
Release Articles @@ -20,7 +20,7 @@ Release Articles -##Change Log 3.1.0 +## Change Log 3.1.0 [Download](https://github.com/OraOpenSource/Logger/raw/master/releases/logger_3.1.0.zip)
[Release Page](https://github.com/OraOpenSource/Logger/issues?utf8=%E2%9C%93&q=milestone%3A%22Release+3.1.0%22+)
Release Articles @@ -91,7 +91,7 @@ Release Articles -##Change Log 3.0.0 +## Change Log 3.0.0 [Download](https://github.com/OraOpenSource/Logger/raw/master/releases/logger_3.0.0.zip)
[Release Page](https://github.com/OraOpenSource/Logger/issues?q=milestone%3A%22Release+3.0.0%22+)
Release Articles @@ -189,7 +189,7 @@ Release Articles -##Change Log 2.1.2 +## Change Log 2.1.2 [Download](https://github.com/oraopensource/logger/tree/master/releases/2.1.2)
[Release Page](https://github.com/oraopensource/logger/issues?milestone=6&state=closed)
@@ -213,7 +213,7 @@ Release Articles -##Change Log 2.1.1 +## Change Log 2.1.1 [Download](https://github.com/oraopensource/logger/tree/master/releases/2.1.1)
[Release Page](https://github.com/oraopensource/logger/issues?milestone=5&state=closed)
@@ -232,7 +232,7 @@ Release Articles -##Change Log 2.1.0 +## Change Log 2.1.0 [Download](https://github.com/oraopensource/logger/tree/master/releases/2.1.0)
[Release Page](https://github.com/oraopensource/logger/issues?milestone=3&state=closed)
Release Articles @@ -289,7 +289,7 @@ Release Articles -##Change Log 2.0.0 +## Change Log 2.0.0 [Download](https://github.com/oraopensource/logger/tree/master/releases/2.0.0)
[Release Page](https://github.com/oraopensource/logger/issues?milestone=1&state=closed)
Release Articles @@ -326,7 +326,7 @@ Release Articles -##Change Log 1.4.0 +## Change Log 1.4.0 [Download](https://github.com/oraopensource/logger/tree/master/releases/1.4.0) @@ -349,7 +349,7 @@ Release Articles -##Change Log 1.3.0 +## Change Log 1.3.0 [Download](https://github.com/oraopensource/logger/tree/master/releases/1.3.0)
@@ -371,7 +371,7 @@ Release Articles
-##Change Log 1.2.2 +## Change Log 1.2.2 @@ -392,7 +392,7 @@ Release Articles
-##Change Log 1.2.0 +## Change Log 1.2.0 [Download](https://github.com/oraopensource/logger/tree/master/releases/1.2.0) @@ -439,10 +439,10 @@ Release Articles
-#Template (ignore) +# Template (ignore) -##Change Log TODOVERSION +## Change Log TODOVERSION [Download](TODO_URL)
[Release Page](TODO_URL)
Release Articles diff --git a/docs/Development Guide.md b/docs/Development Guide.md index cf52f04..f767200 100644 --- a/docs/Development Guide.md +++ b/docs/Development Guide.md @@ -1,27 +1,27 @@ ***This document is best viewed in [flatdoc format](http://oraopensource.github.io/flatdoc?repo=logger&path=docs%2FDevelopment+Guide.md)*** -#Logger Developer Guide -This document describes how to develop and build Logger. +# Logger Developer Guide +This document describes how to develop and build Logger. -#Developing +# Developing When developing with Logger you should work on the main source files, but never in the `releases` folder. The content in there is automatically generated as part of the [build process](#build-process). -##Conditional Compilation +## Conditional Compilation Logger uses [conditional compilation](http://docs.oracle.com/cd/E11882_01/appdev.112/e25519/fundamentals.htm#LNPLS00210) to enable/disable features. It is highly recommended that you understand how conditional compilation works before working on Logger. When installing Logger, the `plsql_ccflags` are automatically defined in the `logger_configure` procedure. It is not reasonable to constantly run `logger_configure` after each change to the source code. -An easy way to control the `plsql_ccflags` is manually set them in your current session. This will allow you to quickly test various situations. The following is an example of how to set your session's conditional compilation flags: +An easy way to control the `plsql_ccflags` is manually set them in your current session. This will allow you to quickly test various situations. The following is an example of how to set your session's conditional compilation flags: ```sql alter session set plsql_ccflags = 'no_op:false, logger_debug:true, APEX:true, logger_plugin_error: true'; ``` -##Tables +## Tables Logger has one installation script that will either update or install Logger. Because of this notion, any changes to tables must assume that the user can re-run the build script at any time and it will not fail. A good example of this, is when adding a new column to a table. The script will check if that column exists. The column will be created only if it does not currently exist. -###$$logger_debug PLSQL_CCFLAG +### $$logger_debug PLSQL_CCFLAG They're some times when you want to debug some code in Logger. There is a catch since you may not want to use Logger to test. Instead, you can add `dbms_output.put_line` statements. If you do add any debug code be sure to wrap in the conditional compilation flag `logger_debug`. Example: ```sql @@ -33,7 +33,7 @@ $end ... ``` -###$$no_op +### $$no_op Logger supports the concept of a `no_op` build. For various reasons, primarily performance releated, you may not want to run Logger on a production system. The `no_op` version allows all the references to Logger however nothing will be executed since each method either returns a minimal result or the procedure is just one `null;` statement. If developing a new method you must support the `no_op` conditional compilation flag. For examples, look at any of the existing methods. @@ -43,15 +43,15 @@ When [building](#build-process) a version of logger the `logger_no_op.pkb` insta The generated version of `logger_no_op.pkb` is stored in `source/packages/` and then the build script copies the file over to the `releases` folder as part of the build. There is no need to commit `logger_no_op.pkb` to Git for version control. By default there is a reference to `source/packages/logger_no_op.pkb` in the `.gitignore` file to ignore this from Git checkins. -##Issues +## Issues Unless an change is very small, please register an [issue](https://github.com/OraOpenSource/Logger/issues) for it in Github. This way it is easy to reference this issue in the code and we can keep track of all the features in a given release. -##Testing +## Testing We plan to implement a test suite in the future which each build must pass in order to be certified. -#Building Logger +# Building Logger Logger has a build script which will take all the source files and merge them into installation files in the `releases` folder. The following demonstrates how to build Logger: ```bash diff --git a/docs/Installation.md b/docs/Installation.md index 4def012..444d9ef 100644 --- a/docs/Installation.md +++ b/docs/Installation.md @@ -4,13 +4,13 @@ - [Maintenance](#maintenance) -#Installation +# Installation If you're new to Logger it's recommended you simply [install into an existing schema](#install-into-existing-schema) on a development environment to get up and running as quickly as possible. You are encouraged to review the rest of the installation sections after you're more familiar with Logger. Once you are comfortable using Logger it is recommended that you read the [Best Practices](Best Practices.md) section -##Important Notes +## Important Notes -###Previous Installations +### Previous Installations Version 2.0.0 build scripts were completely re-written to make it easier for future development. The new build scripts were built off Logger 1.4.0. As such, **if your current version is lower than 1.4.0 you need to run the uninstall script for your specific version**. If you're currently 1.4.0 or above the installation script will automatically update your current version. The following query will identify your current version. ```sql @@ -21,11 +21,11 @@ where pref_name = 'LOGGER_VERSION'; To uninstall an older version of logger, see the [Uninstall](#uninstall) instructions. If necessary, you can download the correct version from the [releases](https://github.com/oraopensource/logger/tree/master/releases) folder. -###Install Through APEX +### Install Through APEX Logger is no longer supported from a web-only installation if the schema was provisioned by APEX. Essentially the APEX team removed the "create any context" privilege when provisioning a new workspace, likely for security reasons. I agree with their choice, it unfortunately impacts logger. -##Install into a new schema +## Install into a new schema 1. Using sql*plus or SQL Developer, connect to the database as system or a user with the DBA role. @@ -41,7 +41,7 @@ Logger is no longer supported from a web-only installation if the schema was pro 1. Follow the steps to install into an existing schema (below). -##Install into an existing schema: +## Install into an existing schema: 1. If possible, connect as a privileged user and issue the following grants to your "existing_user": ```sql grant connect,create view, create job, create table, create sequence, @@ -55,10 +55,10 @@ create trigger, create procedure, create any context to existing_user; 1. Once installed, Logger is automatically set to **DEBUG** level. View the [configurations](#configuration) section to modify its settings. -##NO-OP Option for Production Environments +## NO-OP Option for Production Environments To make sure there is no fear of leaving debug statements in production code, Logger comes with a [NO-OP](http://en.wikipedia.org/wiki/NOP) (No Operation) installation file (logger_no_op.sql). This installs only a shell of the Logger package. All procedures are essentially NO-OPs. It does not even create the tables so there is absolutely no chance it is doing any logging. It is recommended that you leave the full version installed and simply [set the Logger level](Logger API.md#procedure-set_level) to ERROR as the performance hit is exceptionally small. -##Objects +## Objects The following database objects are installed with Logger: ```sql @@ -81,7 +81,7 @@ LOGGER_GLOBAL_CTX CONTEXT -- Global Application Contexts are owned by SYS ``` -##Uninstall +## Uninstall To uninstall Logger simple run the following script in the schema that Logger was installed in: ```sql @@ -89,7 +89,7 @@ To uninstall Logger simple run the following script in the schema that Logger wa ``` -##Restrict Access (Grants & Synonyms) +## Restrict Access (Grants & Synonyms) You may want to [install Logger into it's own schema](#install-into-new-schema) for various reasons. Some of the most common ones are: - DBA does not want to give `CREATE ANY CONTEXT` access to your user. @@ -118,19 +118,19 @@ Run as the user that needs to access Logger: -#Configuration +# Configuration -###Logger Levels +### Logger Levels They're various logger levels. To see the complete list, go to the [Constants](Logger API.md#constants) section in the Logger API. -###Enable +### Enable To enable logging for the entire schema: ```sql exec logger.set_level(logger.g_debug); ``` -###Disable +### Disable To disable logging: ```sql exec logger.set_level(logger.g_off); @@ -145,10 +145,10 @@ If you never want logger to run in an environment you can install the [NO-OP](#i -###Client Specific Configuration +### Client Specific Configuration Logger now supports client specific configuration. For more information and examples view the [Set Logging Level](Logger API.md#set-logging-level) section in the Logger API documentation. -###Status +### Status To view the status/configuration of the Logger: ```sql @@ -170,7 +170,7 @@ For all client info see : logger_prefs_by_client_id PL/SQL procedure successfully completed. ``` -###Preferences +### Preferences Logger stores its configuration settings in LOGGER_PREFS. These are the following preferences: @@ -216,7 +216,7 @@ Logger stores its configuration settings in LOGGER_PREFS. These are the followin
-###Other Options +### Other Options Once you perform the following described steps for the Flashback or APEX option, simply run the *logger_configure* procedure, then run *logger.status* to check validate your changes. @@ -225,19 +225,19 @@ exec logger_configure; exec logger.status; ``` -####Flashback +#### Flashback To enable this option, grant execute on *dbms_flashback* to the user that owns the logger packages. Every insert into *logger_logs* will include the SCN (System Commit Number). This allows you to flashback a session to the time when the error occurred to help debug it or even undo any data corruption. As SYS from sql*plus: ```sql grant execute on dbms_flashback to logger; ``` -####APEX +#### APEX This option allows you to call logger.log_apex_items which grabs the names and values of all APEX items from the current session and stores them in the logger_logs_apex_items table. This is extremely useful in debugging APEX issues. This option is enabled automatically by logger_configure if APEX is installed in the database. -#Maintenance +# Maintenance By default, the DBMS\_SCHEDULER job "LOGGER\_PURGE\_JOB" runs every night at 1:00am and deletes any logs older than 7 days that are of error level *g_debug* or higher which includes *g_debug* and *g_timing*. This means logs with any lower level such as *g_error* or *g_permanent* will never be purged. You can also manually purge all logs using *logger.purge_all*, but this will not delete logs of error level *g_permanent*. diff --git a/docs/Logger API Template.md b/docs/Logger API Template.md index e47064d..194e0ac 100644 --- a/docs/Logger API Template.md +++ b/docs/Logger API Template.md @@ -5,15 +5,15 @@ This is a snippet template to quickly add documentation to the Logger API librar - [TODO_PROC_NAME](#procedure-TODO_ANCHOR_LINK) -####TODO_NAME +#### TODO_NAME TODO_DESC -#####Syntax +##### Syntax ```sql TODO ``` -#####Parameters +##### Parameters @@ -41,7 +41,7 @@ TODO
Attribute
-#####Example +##### Example ```sql TODO -``` \ No newline at end of file +``` diff --git a/docs/Logger API.md b/docs/Logger API.md index 80f6c80..65466d4 100644 --- a/docs/Logger API.md +++ b/docs/Logger API.md @@ -1,9 +1,9 @@ ***This document is best viewed in [flatdoc format](http://oraopensource.github.io/flatdoc?repo=logger&path=docs%2FLogger+API.md)*** -#Constants +# Constants -##General +## General @@ -24,11 +24,11 @@
Name
-##Logger Levels +## Logger Levels For historical purposes, logger levels supports both integers and names which are intergchangble when calling a function that requires a logger level. Note: If setting the Logger level to a deprecated level, it will automatically default to `g_debug`. -###Numeric +### Numeric This is the preferred method @@ -73,7 +73,7 @@ This is the preferred method
-###Name +### Name This will still work, however it is recommended that you use the numeric values. @@ -115,7 +115,7 @@ This will still work, however it is recommended that you use the numeric values.
-##APEX Item Types +## APEX Item Types `log_apex_items` takes in an optional variable `p_item_scope`. This determines which items to log in APEX. Use the following global variables as valid vaules. @@ -141,7 +141,7 @@ This will still work, however it is recommended that you use the numeric values.
-#Types +# Types @@ -170,18 +170,18 @@ This will still work, however it is recommended that you use the numeric values.
Name
-#Subprograms +# Subprograms -##Main Logger Procedures +## Main Logger Procedures Since the main Logger procedures all have the same syntax and behavior (except for the procedure names) the documentation has been combined to avoid replication. -###Best Practices +### Best Practices The [Best Practices](Best%20Practices.md#logger-level-guide) guide covers which Logger procedure to use in different circumstances. -###Syntax +### Syntax The syntax for the main Logger procedures are all the same. ```sql @@ -193,7 +193,7 @@ logger.procedure_name( ``` -###Parameters +### Parameters All of the main Logger procedures have the same parameters @@ -223,7 +223,7 @@ Since most production instances set the logging level to error, it is highly rec
-###Examples +### Examples The following code snippet highlights the main Logger procedures. Since they all have the same parameters, this will serve as the general example for all the main Logger procedures. ```sql begin @@ -271,40 +271,40 @@ end p_demo_procedure; -###LOG +### LOG This procedure will log an entry into the LOGGER\_LOGS table when the logger_level is set to *debug*. See [Main Logger Procedures](#main-logger-procedures) for syntax, parameters, and examples. -###LOG_INFORMATION / LOG_INFO +### LOG_INFORMATION / LOG_INFO This procedure will log an entry into the LOGGER\_LOGS table when the logger_level is set to *information*. See [Main Logger Procedures](#main-logger-procedures) for syntax, parameters, and examples. ```log_info``` is a shortcut wrapper for ```log_information```. -###LOG_WARNING / LOG_WARN +### LOG_WARNING / LOG_WARN This procedure will log an entry into the LOGGER\_LOGS table when the logger_level is set to *warning*. See [Main Logger Procedures](#main-logger-procedures) for syntax, parameters, and examples. ```log_warn``` is a shortcut wrapper for ```log_warning```. -###LOG_ERROR +### LOG_ERROR This procedure will log an entry into the LOGGER\_LOGS table when the logger_level is set to *error*. See [Main Logger Procedures](#main-logger-procedures) for syntax, parameters, and examples. -###LOG_PERMANENT +### LOG_PERMANENT This procedure will log an entry into the LOGGER\_LOGS table when the logger_level is set to *permanent*. See [Main Logger Procedures](#main-logger-procedures) for syntax, parameters, and examples. -##Other Logger Procedures +## Other Logger Procedures -###LOG_USERENV +### LOG_USERENV There are many occasions when the value of one of the USERENV session variables (Documentation: [Overview](http://download.oracle.com/docs/cd/B28359_01/server.111/b28286/functions172.htm), [list of variables](http://download.oracle.com/docs/cd/B28359_01/server.111/b28286/functions172.htm#g1513460)) is a big step in the right direction of finding a problem. A simple call to the *logger.log_userenv* procedure is all it takes to save them in the EXTRA column of logger_logs. *log-userenv* will be logged using the *g\_sys\_context* level. -####Syntax +#### Syntax ```sql log_userenv( @@ -314,7 +314,7 @@ log_userenv( p_level in logger_logs.logger_level%type default null); ``` -####Parameters +#### Parameters @@ -340,7 +340,7 @@ log_userenv(
-####Example +#### Example ```sql exec logger.log_userenv('NLS'); @@ -375,10 +375,10 @@ USERENV values stored in the EXTRA column CURRENT_SCHEMA ``` -###LOG_CGI_ENV +### LOG_CGI_ENV This option only works within a web session, but it's a great way to quickly take a look at an APEX environment. -####Syntax +#### Syntax ```sql logger.log_cgi_env( @@ -387,7 +387,7 @@ logger.log_cgi_env( p_level in logger_logs.logger_level%type default null); ``` -####Parameters +#### Parameters @@ -407,7 +407,7 @@ logger.log_cgi_env(
Parameter
-####Example +#### Example ```sql exec logger.log_cgi_env; @@ -427,10 +427,10 @@ REMOTE_ADDR : 192.168.1.7 ``` -###LOG_CHARACTER_CODES +### LOG_CHARACTER_CODES Have you ever run into an issue with a string that contains control characters such as carriage returns, line feeds and tabs that are difficult to debug? The sql [dump()](http://download.oracle.com/docs/cd/B28359_01/server.111/b28286/functions048.htm#sthref1340) function is great for this, but the output is a bit hard to read as it outputs the character codes for each character, so you end up comparing the character code to an [ascii table](http://www.asciitable.com/) to figure out what it is. The function get_character_codes and the procedure log_character_codes make it much easier as they line up the characters in the original string under the corresponding character codes from dump. Additionally, all tabs are replaced with "^" and all other control characters such as carriage returns and line feeds are replaced with "~". -####Syntax +#### Syntax ```sql logger.log_character_codes( @@ -440,7 +440,7 @@ logger.log_character_codes( p_level in logger_logs.logger_level%type default null); ``` -####Parameters +#### Parameters @@ -464,7 +464,7 @@ logger.log_character_codes(
Parameter
-####Example +#### Example ```sql exec logger.log_character_codes('Hello World'||chr(9)||'Foo'||chr(13)||chr(10)||'Bar'); @@ -478,10 +478,10 @@ Common Codes: 13=Line Feed, 10=Carriage Return, 32=Space, 9=Tab ``` -###LOG_APEX_ITEMS +### LOG_APEX_ITEMS This feature is useful in debugging issues in an APEX application that are related session state. The developers toolbar in APEX provides a place to view session state, but it won't tell you the value of items midway through page rendering or right before and after an AJAX call to an application process. -####Syntax +#### Syntax ```sql logger.log_apex_items( p_text in varchar2 default 'Log APEX Items', @@ -491,7 +491,7 @@ logger.log_apex_items( p_level in logger_logs.logger_level%type default null); ``` -####Parameters +#### Parameters @@ -519,7 +519,7 @@ logger.log_apex_items(
Parameter
-####Example +#### Example ```sql -- Include in your APEX code begin @@ -572,24 +572,24 @@ ID LOG_ID APP_SESSION ITEM_NAME ITEM_VALUE ``` -##Utility Functions +## Utility Functions -###TOCHAR +### TOCHAR TOCHAR will convert the value to a string (varchar2). It is useful when wanting to log items, such as booleans, without having to explicitly convert them. **Note: ```tochar ``` does not use the *no_op* conditional compilation so it will always execute.** This means that you can use outside of Logger (i.e. within your own application business logic). -####Syntax +#### Syntax ```sql logger.tochar( p_val in number | date | timestamp | timestamp with time zone | timestamp with local time zone | boolean return varchar2); ``` -####Parameters +#### Parameters @@ -605,7 +605,7 @@ logger.tochar(
Prameter
-####Example +#### Example ```sql select logger.tochar(sysdate) from dual; @@ -624,7 +624,7 @@ PL/SQL procedure successfully completed. ``` -###SPRINTF +### SPRINTF ```sprintf``` is similar to the common procedure [```printf```](http://en.wikipedia.org/wiki/Printf_format_string) found in many programming languages. It replaces substitution strings for a given string. Substitution strings can be either ```%s``` or ```%s``` where `````` is a number 1~10. @@ -636,7 +636,7 @@ The following rules are used to handle substitution strings (in order): **Note: ```sprintf ``` does not use the *no_op* conditional compilation so it will always execute.** This means that you can use outside of Logger (i.e. within your own application business logic). -####Syntax +#### Syntax ```sql function sprintf( p_str in varchar2, @@ -653,7 +653,7 @@ function sprintf( return varchar2; ``` -####Parameters +#### Parameters @@ -673,7 +673,7 @@ function sprintf(
Prameter
-####Example +#### Example ```sql select logger.sprintf('hello %s, how are you %s', 'martin', 'today') msg from dual; @@ -703,16 +703,16 @@ one, two, one -###GET_CGI_ENV +### GET_CGI_ENV TODO Description -####Syntax +#### Syntax ```sql logger.get_cgi_env( p_show_null in boolean default false) return clob; ``` -####Parameters +#### Parameters @@ -728,17 +728,17 @@ logger.get_cgi_env(
Prameter
-####Example +#### Example ```sql TODO ``` -###GET_PREF +### GET_PREF Returns the preference from LOGGER_PREFS. If `p_pref_type` is not defined then the system level preferences will be returned. -####Syntax +#### Syntax ```sql logger.get_pref( p_pref_name in logger_prefs.pref_name%type, @@ -746,7 +746,7 @@ logger.get_pref( return varchar2 ``` -####Parameters +#### Parameters @@ -766,21 +766,21 @@ logger.get_pref(
Prameter
-####Example +#### Example ```sql dbms_output.put_line('Logger level: ' || logger.get_pref('LEVEL')); ``` -###SET_PREF +### SET_PREF In some cases you may want to store custom preferences in the `LOGGER_PREFS` table. A use case for this would be when creating a plugin that needs to reference some parameters. This procedure allows you to leverage the `LOGGER_PREFS` table to store your custom preferences. To avoid any naming conflicts with Logger, you must use a type (defined in `p_pref_type`). You can not use the type `LOGGER` as it is reserved for Logger system preferences. `SET_PREF` will either create or udpate a value. Values must contain data. If not, use [`DEL_PREF`](#procedure-del_pref) to delete unused preferences. -####Syntax +#### Syntax ```sql logger.set_pref( p_pref_type in logger_prefs.pref_type%type, @@ -788,7 +788,7 @@ logger.set_pref( p_pref_value in logger_prefs.pref_value%type); ``` -####Parameters +#### Parameters @@ -808,7 +808,7 @@ logger.set_pref(
Prameter
-####Example +#### Example ```sql logger.set_pref( p_pref_type => 'CUSTOM' @@ -818,17 +818,17 @@ logger.set_pref( -###DEL_PREF +### DEL_PREF Deletes a preference except for system level preferences. -####Syntax +#### Syntax ```sql logger.del_pref( p_pref_type in logger_prefs.pref_type%type, p_pref_name in logger_prefs.pref_name%type); ``` -####Parameters +#### Parameters @@ -844,7 +844,7 @@ logger.del_pref(
Prameter
-####Example +#### Example ```sql logger.del_pref( p_pref_type => 'CUSTOM' @@ -853,16 +853,16 @@ logger.del_pref( -###PURGE +### PURGE TODO_DESC -####Syntax +#### Syntax ```sql logger.purge( p_purge_after_days in varchar2 default null, p_purge_min_level in varchar2 default null); ``` -####Parameters +#### Parameters @@ -878,26 +878,26 @@ logger.purge(
Prameter
-####Example +#### Example ```sql TODO ``` -###PURGE_ALL +### PURGE_ALL Purges all non-permanent entries in LOGGER_LOGS. -####Syntax +#### Syntax ```sql logger.purge_all; ``` -####Parameters +#### Parameters No Parameters -####Example +#### Example ```sql TODO -- For this one show a count before of logger_logs. Then run, then show what's left in the table. @@ -905,16 +905,16 @@ TODO -###STATUS +### STATUS Prints the Logger's current status and configuration settings. -####Syntax +#### Syntax ```sql logger.status( p_output_format in varchar2 default null); -- SQL-DEVELOPER | HTML | DBMS_OUPUT ``` -####Parameters +#### Parameters @@ -927,7 +927,7 @@ logger.status(
Prameter
-####Example +#### Example ```sql set serveroutput on exec logger.status @@ -949,51 +949,51 @@ PL/SQL procedure successfully completed. -###SQLPLUS_FORMAT +### SQLPLUS_FORMAT TODO_DESC -####Syntax +#### Syntax ```sql logger.sqlplus_format; ``` -####Parameters +#### Parameters No Parameters -####Example +#### Example ```sql TODO ``` -###NULL_GLOBAL_CONTEXTS +### NULL_GLOBAL_CONTEXTS TODO_DESC -####Syntax +#### Syntax ```sql logger.null_global_contexts; ``` -####Parameters +#### Parameters No Parameters. -####Example +#### Example ```sql TODO ``` -###CONVERT_LEVEL_CHAR_TO_NUM +### CONVERT_LEVEL_CHAR_TO_NUM Returns the number representing the given level (string). -####Syntax +#### Syntax ```sql logger.convert_level_char_to_num( p_level in varchar2) return number; ``` -####Parameters +#### Parameters @@ -1009,7 +1009,7 @@ logger.convert_level_char_to_num(
Prameter
-####Example +#### Example ```sql select logger.convert_level_char_to_num(p_level => 'DEBUG') level_number from dual; @@ -1020,16 +1020,16 @@ LEVEL_NUMBER ``` -###DATE_TEXT_FORMAT +### DATE_TEXT_FORMAT Returns the time difference (in nicely formatted string) of *p\_date* compared to now (sysdate). -####Syntax +#### Syntax ```sql logger.date_text_format (p_date in date) return varchar2; ``` -####Parameters +#### Parameters @@ -1045,7 +1045,7 @@ logger.date_text_format (p_date in date)
Prameter
-####Example +#### Example ```sql select logger.date_text_format(sysdate-1) date_diff from dual; @@ -1056,10 +1056,10 @@ DATE_DIFF ``` -###GET_CHARACTER_CODES +### GET_CHARACTER_CODES Similar to [log_character_codes](#procedure-log_character_codes) except will return the character codes instead of logging them. -####Syntax +#### Syntax ```sql logger.get_character_codes( p_string in varchar2, @@ -1067,7 +1067,7 @@ logger.get_character_codes( return varchar2; ``` -####Parameters +#### Parameters @@ -1087,7 +1087,7 @@ logger.get_character_codes(
Prameter
-####Example +#### Example ```sql select logger.get_character_codes('Hello World') char_codes from dual; @@ -1101,10 +1101,10 @@ Common Codes: 13=Line Feed, 10=Carriage Return, 32=Space, 9=Tab -###APPEND_PARAM +### APPEND_PARAM Logger has wrapper functions to quickly and easily log parameters. All primary log procedures take in a fourth parameter to support logging a parameter array. The values are explicitly converted to strings so you don't need to convert them. The parameter values will be stored n the *extra* column. -####Syntax +#### Syntax ```sql logger.append_param( p_params in out nocopy logger.tab_param, @@ -1112,7 +1112,7 @@ logger.append_param( p_val in ); ``` -####Parameters +#### Parameters @@ -1132,7 +1132,7 @@ logger.append_param(
Prameter
-####Example +#### Example ```sql create or replace procedure p_demo_function( p_empno in emp.empno%type, @@ -1153,7 +1153,7 @@ end p_demo_function; ``` -###OK_TO_LOG +### OK_TO_LOG Though Logger internally handles when a statement is stored in the LOGGER_LOGS table there may be situations where you need to know if logger will log a statement before calling logger. This is useful when doing an expensive operation just to log the data. A classic example is looping over an array for the sole purpose of logging the data. In this case, there's no reason why the code should perform the additional computations when logging is disabled for a certain level. @@ -1162,13 +1162,13 @@ A classic example is looping over an array for the sole purpose of logging the d *Note*: *ok\_to\_log* is not something that should be used frequently. All calls to logger run this command internally. -####Syntax +#### Syntax ```sql logger.ok_to_log(p_level in varchar2) return boolean; ``` -####Parameters +#### Parameters @@ -1184,7 +1184,7 @@ logger.ok_to_log(p_level in varchar2)
Prameter
-####Example +#### Example ```sql declare type typ_array is table of number index by pls_integer; @@ -1218,7 +1218,7 @@ end if; -###INS_LOGGER_LOGS +### INS_LOGGER_LOGS Similar to ```ok_to_log```, this procedure should be used very infrequently as the main Logger procedures should handle everything that is required for quickly logging information. As part of the 2.1.0 release, the trigger on ```LOGGER_LOGS``` was removed for both performance and other issues. Though inserting directly to the ```LOGGER_LOGS``` table is not a supported feature of Logger, you may have some code that does a direct insert. The primary reason that a manual insert into ```LOGGER_LOGS``` was done was to obtain the ```ID``` column for the log entry. @@ -1230,7 +1230,7 @@ Important things to now about ```ins_logger_logs```: - It does not check the Logger level. This means it will always insert into the ```LOGGER_LOGS``` table. It is also an Autonomous Transaction procedure so a commit is always performed, however it will not affect the current session. - [Plugins](Plugins.md) will not be executed when calling this procedure. If you have critical processes which leverage plugin support you should use the proper log function instead. -####Syntax +#### Syntax ```sql logger.ins_logger_logs( p_logger_level in logger_logs.logger_level%type, @@ -1243,7 +1243,7 @@ logger.ins_logger_logs( po_id out nocopy logger_logs.id%type); ``` -####Parameters +#### Parameters @@ -1283,7 +1283,7 @@ logger.ins_logger_logs(
Prameter
-####Example +#### Example ```sql set serveroutput on @@ -1311,7 +1311,7 @@ ID: 2930650 -##Set Logging Level +## Set Logging Level Logger allows you to configure both system logging levels and client specific logging levels. If a client specific logging level is defined, it will override the system level configuration. If no client level is defined Logger will defautl to the system level configuration. @@ -1331,10 +1331,10 @@ logger_demo_session ERROR TRUE 24-APR-2013 02:48:13 24-APR-2013 14:48: -###SET_LEVEL +### SET_LEVEL Set both system and client logging levels. -####Syntax +#### Syntax ```sql logger.set_level( p_level in varchar2 default logger.g_debug_name, @@ -1344,7 +1344,7 @@ logger.set_level( ); ``` -####Parameters +#### Parameters @@ -1368,7 +1368,7 @@ logger.set_level(
Prameter
-####Example +#### Example Set system level logging level: ```sql exec logger.set_level(logger.g_debug_name); @@ -1423,15 +1423,15 @@ In APEX the *client\_identifier* is -###UNSET_CLIENT_LEVEL +### UNSET_CLIENT_LEVEL Unset logger level by specific *client_id*. -####Syntax +#### Syntax ```sql logger.unset_client_level(p_client_id in varchar2); ``` -####Parameters +#### Parameters @@ -1443,52 +1443,52 @@ logger.unset_client_level(p_client_id in varchar2);
Prameter
-####Example +#### Example ```sql exec logger.unset_client_level('my_client_id'); ``` -###UNSET_CLIENT_LEVEL +### UNSET_CLIENT_LEVEL Unset all expired *client_id*s. Note this run automatically each hour by the *LOGGER\_UNSET\_PREFS\_BY\_CLIENT* job. -####Syntax +#### Syntax ```sql logger.unset_client_level; ``` -####Parameters +#### Parameters No parameters. -####Example +#### Example ```sql exec logger.unset_client_level; ``` -###UNSET_CLIENT_LEVEL_ALL +### UNSET_CLIENT_LEVEL_ALL Unset all client configurations (regardless of expiry time). -####Syntax +#### Syntax ```sql logger.unset_client_level_all; ``` -####Parameters +#### Parameters No Parameters. -####Example +#### Example ```sql exec logger.unset_client_level_all; ``` -##Timing Procedures +## Timing Procedures TODO description? -###Example +### Example Since all the timing procedures are tightly coupled, the following example will be used to cover all of them: ```sql @@ -1522,34 +1522,34 @@ STOP : foo - 2.015953 seconds ``` -###TIME_RESET +### TIME_RESET Resets all timers. -####Syntax +#### Syntax ```sql logger.time_reset; ``` -####Parameters +#### Parameters No Parameters. -####Example +#### Example ```sql logger.time_reset; ``` -###TIME_START +### TIME_START Starts a timer. -####Syntax +#### Syntax ```sql logger.time_start( p_unit IN VARCHAR2, p_log_in_table IN boolean default true) ``` -####Parameters +#### Parameters @@ -1565,21 +1565,21 @@ logger.time_start(
Prameter
-####Example +#### Example See [Timing Procedures Example](#timing-procedures-example). -###TIME_STOP +### TIME_STOP Stops a timing event and logs in LOGGER_LOGS using level = logger.g_timing. -####Syntax +#### Syntax ```sql logger.time_stop( p_unit in varchar2, p_scope in varchar2 default null); ``` -####Parameters +#### Parameters @@ -1595,14 +1595,14 @@ logger.time_stop(
Prameter
-####Example +#### Example See [Timing Procedures Example](#timing-procedures-example). -###TIME_STOP +### TIME_STOP Similar to [TIME_STOP](#time_stop) procedure, this function will stop a timer. Logging into LOGGER_LOGS is configurable. Returns the stop time string. -####Syntax +#### Syntax ```sql logger.time_stop( p_unit in varchar2, @@ -1611,7 +1611,7 @@ logger.time_stop( return varchar2; ``` -####Parameters +#### Parameters @@ -1635,16 +1635,16 @@ logger.time_stop(
Prameter
-####Example +#### Example ```sql TODO ``` -###TIME_STOP_SECONDS +### TIME_STOP_SECONDS TODO_DESC -####Syntax +#### Syntax ```sql logger.time_stop_seconds( p_unit in varchar2, @@ -1653,7 +1653,7 @@ logger.time_stop_seconds( return number; ``` -####Parameters +#### Parameters @@ -1673,7 +1673,7 @@ logger.time_stop_seconds(
Prameter
-####Example +#### Example ```sql TODO ``` diff --git a/docs/Plugins.md b/docs/Plugins.md index 06bd4db..d4df9c1 100644 --- a/docs/Plugins.md +++ b/docs/Plugins.md @@ -1,13 +1,13 @@ ***This document is best viewed in [flatdoc format](http://oraopensource.github.io/flatdoc?repo=logger&path=docs%2FPlugins.md)*** -#About +# About Plugins are a new feature introduced in Logger 3.0.0. They allow developers to run custom code after a log has been inserted. This can be very useful for things such as custom notifications after an error. To help with performance, the plugin architecture uses conditional compilation which will only execute one a plugin has been properly configured. -##Plugin Methods +## Plugin Methods The following types of plugins are currently supported: @@ -25,7 +25,7 @@ The following types of plugins are currently supported: -#Configuration +# Configuration There are two steps to configure a plugin. The first is to register a custom function ([more on this below](#plugin-interface)) in the logger prefs table. The following examples shows how to register a custom plugin procedure (in this example called ```custom_plugin_method```) to be run after calls to ```logger.log_error```: ```sql update logger_prefs @@ -44,7 +44,7 @@ exec logger_configure; To deregister a plugin, set the appropriate `logger_prefs.pref_value` to `null` and re-run the `logger_configure` procedure. *Note: since `pref_value` is not a nullable column, null values will be automatically converted to "NONE".* -#Plugin Interface +# Plugin Interface Plugins can either be standalone procedures or a procedure in a package. Plugins must implement the following interface: ```sql @@ -55,12 +55,12 @@ procedure ( For more information about the `logger.rec_logger_log` type please see the [Types documentation](Logger%20API.md#types). -#Example +# Example The following example shows how to create a custom plugin, configure, and run it. -##Plugin Procedure +## Plugin Procedure The first thing to do is create a method that will be called when an error is logged: ```sql @@ -84,7 +84,7 @@ end; ``` -##Register Plugin and Configure +## Register Plugin and Configure ```sql -- Register new plugin procedure for errors @@ -99,7 +99,7 @@ exec logger_configure; ``` -##Run +## Run ```sql set serveroutput on @@ -112,10 +112,10 @@ Text: hello ``` -#Other +# Other There are several important things to know about plugins. -##Recursion +## Recursion Plugins do not support recursing for the same type of plugin. I.e. when in an error plugin and the plugin code calls ```logger.log_error```, the error plugin will not execute for the recursive call (but the second error record is still stored in ```logger_logs```. This is to avoid infinite loops in the plugin. The following example highlights this (note that ```logger.log_error``` is called in the plugin). @@ -141,7 +141,7 @@ In Plugin The output shows that the plugin was only run once, despite ```logger.log_error``` being called a second time inside the plugin. -##Errors in Plugin +## Errors in Plugin When an error occurs inside a plugin, it is logged (using ```logger.log_error```) and the error is then raised.