[Doc] Roll back logging docs

roji · roji · commit 98ba03a61af4 · 2017-03-21T17:03:15.000+01:00
diff --git a/doc/logging.md b/doc/logging.md
@@ -1,19 +1,97 @@
 # Logging
 
-Npgsql uses Microsoft.Extensions.Logging to emit log events that can be routed to your logging library of choice - see [their docs](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging) for more information. Note that Microsoft.Extensions.Logging support replaced Npgsql's own custom logging wrapper in 3.2.
+*Note:* Npgsql 3.2.0 and 3.2.1 siginifiantly changed logging to use Microsoft.Extensions.Logging. After several complaints and issues (see [#1504](https://github.com/npgsql/npgsql/issues/1504)), this feature was rolled back. Starting with Npgsql 3.2.2, logging support is identical to Npgsql 3.1.
 
-Since Npgsql is an ADO.NET provider and does not support dependency injection, you must manually inject your ILoggingFactory by including the following code *before* starting to use any of Npgsql's other APIs. For example, to log to the console, install `Microsoft.Extensions.Logging.Console` and add the following code:
+Npgsql includes a built-in feature for outputting logging events which can help debug issues.
+
+Npgsql logging is disabled by default and must be turned on. Logging can be turned on by setting `NpgsqlLogManager.Provider` to a class implementing the `INpgsqlLoggingProvider` interface. Npgsql comes with a console implementation which can be set up as follows:
+
+```c#
+NpgsqlLogManager.Provider = new ???
+```
+
+*Note: you must set the logging provider before invoking any other Npgsql method, at the very start of your program.*
+
+It's trivial to create a logging provider that passes log messages to whatever logging framework you use. You can find such an adaptor for NLog [here](http://ni).
+
+*Note:* the logging API is a first implementation and will probably improve/change - don't treat it as a stable part of the Npgsql API. Let us know if you think there are any missing messages or features!
+
+## ConsoleLoggingProvider
+
+Npgsql comes with one built-in logging provider: ConsoleLoggingProvider. It will simply dump all log messages with a given level or above to stdanrd output.
+You can set it up by including the following line at the beginning of your application:
 
 ```c#
-NpgsqlLogManager.LoggerFactory = new LoggerFactory()
-    .AddConsole((text, logLevel) => logLevel >= LogLevel.Debug);
+NpgsqlLogManager.Provider = new ConsoleLoggingProvider(<min level>, <print level?>, <print connector id?>);
 ```
 
-This will make Npgsql log to the console, for messages of at least Debug level. Other providers exist for NLog and other logging packages and services.
+Level defaults to `NpgsqlLogLevel.Info` (which will only print warnings and errors).
+You can also have log levels and connector IDs logged.
 
 ## Statement and Parameter Logging
 
 Npgsql will log all SQL statements at level Debug, this can help you debug exactly what's being sent to PostgreSQL.
 
 By default, Npgsql will not log parameter values as these may contain sensitive information. You can turn on
 parameter logging by setting `NpgsqlLogManager.IsParameterLoggingEnabled` to true.
+
+## NLogLoggingProvider (or implementing your own)
+
+The following provider is used in the Npgsql unit tests to pass log messages to [NLog](http://nlog-project.org/).
+You're welcome to copy-paste it into your project, or to use it as a starting point for implementing your own custom provider.
+
+```c#
+class NLogLoggingProvider : INpgsqlLoggingProvider
+{
+    public NpgsqlLogger CreateLogger(string name)
+    {
+        return new NLogLogger(name);
+    }
+}
+
+class NLogLogger : NpgsqlLogger
+{
+    readonly Logger _log;
+
+    internal NLogLogger(string name)
+    {
+        _log = LogManager.GetLogger(name);
+    }
+
+    public override bool IsEnabled(NpgsqlLogLevel level)
+    {
+        return _log.IsEnabled(ToNLogLogLevel(level));
+    }
+
+    public override void Log(NpgsqlLogLevel level, int connectorId, string msg, Exception exception = null)
+    {
+        var ev = new LogEventInfo(ToNLogLogLevel(level), "", msg);
+        if (exception != null)
+            ev.Exception = exception;
+        if (connectorId != 0)
+            ev.Properties["ConnectorId"] = connectorId;
+        _log.Log(ev);
+    }
+
+    static LogLevel ToNLogLogLevel(NpgsqlLogLevel level)
+    {
+        switch (level)
+        {
+        case NpgsqlLogLevel.Trace:
+            return LogLevel.Trace;
+        case NpgsqlLogLevel.Debug:
+            return LogLevel.Debug;
+        case NpgsqlLogLevel.Info:
+            return LogLevel.Info;
+        case NpgsqlLogLevel.Warn:
+            return LogLevel.Warn;
+        case NpgsqlLogLevel.Error:
+            return LogLevel.Error;
+        case NpgsqlLogLevel.Fatal:
+            return LogLevel.Fatal;
+        default:
+            throw new ArgumentOutOfRangeException("level");
+        }
+    }
+}
+```
diff --git a/doc/migration/3.2.md b/doc/migration/3.2.md
@@ -12,7 +12,7 @@ This release contains a large number of new features, but the main focus is perf
 ## Major Changes
 
 * Prepared statements are now persistent (survive beyond pooled connection close/open), providing significant performance improvements for applications with short-lived connections, such as most webapps ([#483](https://github.com/npgsql/npgsql/issues/483)). Also, statements can optionally be prepared automatically by Npgsql based on use, unlocking prepared statement performance for O/RMs and data layers which don't prepare themselves, such as Dapper or Entity Framework Core ([#1237](https://github.com/npgsql/npgsql/issues/1237)). See [this blog post for more info](http://www.roji.org/prepared-statements-in-npgsql-3-2).
-* Npgsql's custom logging has been replaced with [Microsoft.Extensions.Logging]((https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging), making it easy to log to most providers, and providing structured logging as well for providers such as Serilog ([#1184](https://github.com/npgsql/npgsql/issues/1184)).
+* ~Npgsql's custom logging has been replaced with [Microsoft.Extensions.Logging]((https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging), making it easy to log to most providers, and providing structured logging as well for providers such as Serilog ([#1184](https://github.com/npgsql/npgsql/issues/1184)).~ Microsoft.Extensions.Logging support was rolled back in 3.2.2.
 * The internal I/O system has been overhauled to continue supporting sync and async I/O, but with a vastly better coding model. This should eliminate most protocol sync bugs, and make it much easier to maintain and write new type handlers ([#1326](https://github.com/npgsql/npgsql/issues/1326)).
 * Kerberos login ("integrated security") is now support on Linux/Mac ([#1079](https://github.com/npgsql/npgsql/issues/1079)).
 * Support for System.Transactions and distributed transactions has been rewritten, and should have fewer problems than before ([#122](https://github.com/npgsql/npgsql/issues/122)).
