Skip to content
Permalink
Browse files

feat: use java.util.logging (#722)

Use java.util.logging to print log messages.
logging can be configured in a regular JUL way, and via
`-DloggerLevel=OFF/DEBUG/TRACE`
`-DloggerFile=logs/pgjdbc_${app}.log`     `${..}` can be used to use property names in the file name, including `System.properties`. `%u`, `%g`, etc patterns from https://docs.oracle.com/javase/7/docs/api/java/util/logging/FileHandler.html can be used as well.
  • Loading branch information
jorsol authored and vlsi committed Feb 12, 2017
1 parent 63ed212 commit 43e6505e3aa16e6acdf08f02f2dd1e3cf131ac3e
Showing with 821 additions and 781 deletions.
  1. +2 −1 README.md
  2. +3 −1 build.properties
  3. +4 −2 docs/index.html
  4. +3 −3 docs/jndi.md
  5. +122 −0 docs/logging.md
  6. +4 −4 docs/reading.md
  7. +78 −72 pgjdbc/src/main/java/org/postgresql/Driver.java
  8. +22 −2 pgjdbc/src/main/java/org/postgresql/PGProperty.java
  9. +1 −1 pgjdbc/src/main/java/org/postgresql/core/BaseConnection.java
  10. +3 −5 pgjdbc/src/main/java/org/postgresql/core/ConnectionFactory.java
  11. +0 −98 pgjdbc/src/main/java/org/postgresql/core/Logger.java
  12. +10 −17 pgjdbc/src/main/java/org/postgresql/core/QueryExecutorBase.java
  13. +61 −99 pgjdbc/src/main/java/org/postgresql/core/v3/ConnectionFactoryImpl.java
  14. +71 −170 pgjdbc/src/main/java/org/postgresql/core/v3/QueryExecutorImpl.java
  15. +14 −24 pgjdbc/src/main/java/org/postgresql/core/v3/replication/V3PGReplicationStream.java
  16. +7 −9 pgjdbc/src/main/java/org/postgresql/core/v3/replication/V3ReplicationProtocol.java
  17. +0 −6 pgjdbc/src/main/java/org/postgresql/ds/PGConnectionPoolDataSource.java
  18. +0 −4 pgjdbc/src/main/java/org/postgresql/ds/PGPooledConnection.java
  19. +0 −5 pgjdbc/src/main/java/org/postgresql/ds/PGPoolingDataSource.java
  20. +0 −5 pgjdbc/src/main/java/org/postgresql/ds/PGSimpleDataSource.java
  21. +59 −43 pgjdbc/src/main/java/org/postgresql/ds/common/BaseDataSource.java
  22. +3 −6 pgjdbc/src/main/java/org/postgresql/fastpath/Fastpath.java
  23. +26 −32 pgjdbc/src/main/java/org/postgresql/gss/GssAction.java
  24. +7 −6 pgjdbc/src/main/java/org/postgresql/gss/MakeGSS.java
  25. +2 −3 pgjdbc/src/main/java/org/postgresql/jdbc/PgArray.java
  26. +38 −53 pgjdbc/src/main/java/org/postgresql/jdbc/PgConnection.java
  27. +35 −18 pgjdbc/src/main/java/org/postgresql/jdbc/PgResultSet.java
  28. +0 −5 pgjdbc/src/main/java/org/postgresql/jdbc/PgStatement.java
  29. +2 −1 pgjdbc/src/main/java/org/postgresql/largeobject/LargeObjectManager.java
  30. +6 −3 pgjdbc/src/main/java/org/postgresql/ssl/MakeSSL.java
  31. +13 −23 pgjdbc/src/main/java/org/postgresql/sspi/SSPIClient.java
  32. +95 −0 pgjdbc/src/main/java/org/postgresql/util/ExpressionProperties.java
  33. +8 −7 pgjdbc/src/main/java/org/postgresql/util/ServerErrorMessage.java
  34. +9 −11 pgjdbc/src/main/java/org/postgresql/util/SharedTimer.java
  35. +14 −18 pgjdbc/src/main/java/org/postgresql/xa/PGXAConnection.java
  36. +1 −6 pgjdbc/src/main/java/org/postgresql/xa/PGXADataSource.java
  37. +22 −11 pgjdbc/src/test/java/org/postgresql/test/TestUtil.java
  38. +4 −0 pgjdbc/src/test/java/org/postgresql/test/jdbc2/Jdbc2TestSuite.java
  39. +5 −5 pgjdbc/src/test/java/org/postgresql/test/jdbc2/PGPropertyTest.java
  40. +2 −1 pgjdbc/src/test/java/org/postgresql/test/jdbc2/optional/BaseDataSourceTest.java
  41. +2 −1 pgjdbc/src/test/java/org/postgresql/test/jdbc2/optional/CaseOptimiserDataSourceTest.java
  42. +63 −0 pgjdbc/src/test/java/org/postgresql/test/util/ExpressionPropertiesTest.java
@@ -153,7 +153,8 @@ In addition to the standard connection parameters the driver supports a number o
| sslpassword | String | null | The password for the client's ssl key (ignored if sslpasswordcallback is set) |
| sendBufferSize | Integer | -1 | Socket write buffer size |
| recvBufferSize | Integer | -1 | Socket read buffer size |
| loglevel | Integer | 0 | The log level to debug the driver, possible values: 0, 1, 2. Call [setLogWriter(PrintWriter)](https://docs.oracle.com/javase/6/docs/api/java/sql/DriverManager.html#setLogWriter%28java.io.PrintWriter%29) to set the log output destination. |
| loggerLevel | String | null | Logger level of the driver using java.util.logging. Allowed values: OFF, DEBUG or TRACE. |
| loggerFile | String | null | File name output of the Logger, if set, the Logger will use a FileHandler to write to a specified file. If the parameter is not set or the file can't be created the ConsoleHandler will be used instead. |
| allowEncodingChanges | Boolean | false | Allow for changes in client_encoding |
| logUnclosedConnections | Boolean | false | When connections that are not explicitly closed are garbage collected, log the stacktrace from the opening of the connection to trace the leak source |
| binaryTransferEnable | String | "" | Comma separated list of types to enable binary transfer. Either OID numbers or names |
@@ -1,5 +1,6 @@
# Default build parameters. These may be overridden by local configuration
# settings in build.local.properties.
# loggerLevel can be OFF, DEBUG, TRACE
#

server=localhost
@@ -11,5 +12,6 @@ privilegedUser=postgres
privilegedPassword=
sspiusername=testsspi
preparethreshold=5
loglevel=0
loggerLevel=OFF
loggerFile=target/pgjdbc-tests.log
protocolVersion=0
@@ -133,8 +133,10 @@ <h3 class="c2">Table of Contents</h3>
<dt><a href="jndi.html">Data Sources and <acronym class="ACRONYM">JNDI</acronym></a></dt>
</dl>
</dd>

<dt>12. <a href="reading.html">Further Reading</a></dt>

<dt>12. <a href="logging.html">Logging with java.util.logging</a></dt>

<dt>13. <a href="reading.html">Further Reading</a></dt>
</dl>
</div>

@@ -5,8 +5,8 @@ header: Chapter 11. Connection Pools and Data Sources
resource: media
previoustitle: Tomcat setup
previous: tomcat.html
nexttitle: Chapter 12. Further Reading
next: reading.html
nexttitle: Chapter 12. Logging with java.util.logging
next: logging.html
---

All the `ConnectionPoolDataSource` and `DataSource` implementations can be stored
@@ -65,4 +65,4 @@ finally
try { conn.close(); } catch (SQLException e) {}
}
}
</code></pre>
</code></pre>
@@ -0,0 +1,122 @@
---
layout: default_docs
title: Chapter 12. Logging using java.util.logging
header: Chapter 12. Logging using java.util.logging
resource: media
previoustitle: Data Sources and JNDI
previous: jndi.html
nexttitle: Further Reading
next: reading.html
---

**Table of Contents**

* [Overview](logging.html#overview)
* [Configuration](logging.html#configuration)
* [Enable logging by using connection properties](logging.html#conprop)
* [Enable logging by using logging.properties file](logging.html#fileprop)

<a name="overview"></a>
# Overview

The PostgreSQL JDBC Driver supports the use of logging (or tracing) to help resolve issues with the
PgJDBC Driver when is used in your application.

The PgJDBC Driver uses the logging APIs of `java.util.logging` that is part of Java since JDK 1.4,
which makes it a good choice for the driver since it don't add any external dependency for a logging
framework. `java.util.logging` is a very rich and powerful tool, it's beyond the scope of this docs
to explain or use it full potential, for that please refer to
[Java Logging Overview](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html).

This logging support was added since version 42.0.0 of the PgJDBC Driver, and previous
versions uses a custom mechanism to enable logging that it is replaced by the use of
`java.util.logging` in current versions, the old mechanism is no longer available.

Please note that while most people asked the use of a Logging Framework for a long time, this
support is mainly to debug the driver itself and not for general sql query debug.

<a name="configuration"></a>
# Configuration

The Logging APIs offer both static and dynamic configuration control. Static control enables field
service staff to set up a particular configuration and then re-launch the application with the new
logging settings. Dynamic control allows for updates to the logging configuration within a currently
running program.

As part of the support of a logging framework in the PgJDBC Driver, there was a need to facilitate
the enabling of the Logger using [connection properties](logging.html#conprop), which uses a static
control to enable the tracing in the driver. Keep in mind that if you use an Application Server
(Tomcat, JBoss, WildFly, etc.) you should use the facilities provided by them to enable the logging,
as most Application Servers use dynamic configuration control which makes easy to enable/disable
logging at runtime.

The root logger used by the PgJDBC driver is `org.postgresql`.

<a name="conprop"></a>
## Enable logging by using connection properties

The driver provides a facility to enable logging using connection properties, it's not as feature rich
as using a `logging.properties` file, so it should be used when you are really debugging the driver.

The properties are `loggerLevel` and `loggerFile`:

**loggerLevel**: Logger level of the driver. Allowed values: `OFF`, `DEBUG` or `TRACE`.

This option enable the `java.util.logging.Logger` of the driver based on the following mapping:

| java.util.logging | loggerLevel |
| ----------------- | ----------- |
| OFF | OFF |
| FINE | DEBUG |
| FINEST | TRACE |

As noted, there are no other levels supported using this method, and internally the driver Logger levels
should not (for the most part) use others levels as the intention is to debug the driver and don't
interfere with higher levels when some applications enable them globally.

**loggerFile**: File name output of the Logger.

If set, the Logger will use a `java.util.logging.FileHandler` to write to a specified file.
If the parameter is not set or the file can't be created the `java.util.logging.ConsoleHandler`
will be used instead.

This parameter should be use together with `loggerLevel`.

The following is an example of how to use connection properties to enable logging:

```
jdbc:postgresql://localhost:5432/mydb?loggerLevel=DEBUG
jdbc:postgresql://localhost:5432/mydb?loggerLevel=TRACE&loggerFile=pgjdbc.log
```

<a name="fileprop"></a>
## Enable logging by using logging.properties file

The default Java logging framework stores its configuration in a file called `logging.properties`.
Settings are stored per line using a dot notation format. Java installs a global configuration file
in the `lib` folder of the Java installation directory, although you can use a separate configuration
file by specifying the `java.util.logging.config.file` property when starting a Java program.
`logging.properties` files can also be created and stored with individual projects.

The following is an example of setting that you can make in the `logging.properties`:
```
# Specify the handler, the handlers will be installed during VM startup.
handlers= java.util.logging.FileHandler
# Default global logging level.
.level= OFF
# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/pgjdbc%u.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 20
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level = FINEST
# Facility specific properties.
org.postgresql.level=FINEST
```

And when you run your application you pass the system property:
`java -jar -Djava.util.logging.config.file=logging.properties run.jar`

@@ -1,10 +1,10 @@
---
layout: default_docs
title: Chapter 12. Further Reading
header: Chapter 12. Further Reading
title: Chapter 13. Further Reading
header: Chapter 13. Further Reading
resource: media
previoustitle: Data Sources and JNDI
previous: jndi.html
previoustitle: Chapter 12. Logging with java.util.logging
previous: logging.html
nexttitle: The PostgreSQL™ JDBC Interface
next: index.html
---

0 comments on commit 43e6505

Please sign in to comment.
You can’t perform that action at this time.