Updated log documentation and fixed docs

core/config/doc.go

@@ -33,11 +33,11 @@
 //
 // Provider
 //
-// Provider is the interface for anything that can provide values.
+//  Provider is the interface for anything that can provide values.
 // We provide a few reference implementations (environment and YAML), but you are
 // free to register your own providers via
-// config.RegisterProviders() and
-// config.RegisterDynamicProviders.
+//  config.RegisterProviders() and
+//  config.RegisterDynamicProviders.
 //
 // Static configuration providers
 //
@@ -51,20 +51,20 @@
 // Dynamic configuration providers frequently need some bootstrap configuration to
 // be useful, so UberFx treats them specially. Dynamic configuration providers
 // conform to the
-// Provider interface, but they're instantianted
-// **after** the Static Providers on order to read bootstarp values.
+//  Provider interface, but they're instantianted
+//  **after** the Static Providers on order to read bootstarp values.
 //
 // For example, if you were to implement a ZooKeeper-backed
-// Provider, you'd likely need to specify (via YAML or environment
+//  Provider, you'd likely need to specify (via YAML or environment
 // variables) where your ZooKeeper nodes live.
 //
 //
 // Value
 //
-// Value is the return type of every configuration providers'
-// GetValue(key string) method. Under the hood, we use the empty interface
+//  Value is the return type of every configuration providers'
+//  GetValue(key string) method. Under the hood, we use the empty interface
 // (
-// interface{}) since we don't necessarily know the structure of your
+//  interface{}) since we don't necessarily know the structure of your
 // configuration ahead of time.
 //
 //
@@ -83,24 +83,24 @@
 //   fmt.Println(foo)
 //   // Output: hello
 //
-// • Populate a struct (PopulateStruct(&myStruct))
+// • Populate a struct ( PopulateStruct(&myStruct))
 //
 // The As* method has two variants: TryAs* and As*. The former is a
 // two-value return, similar to a type assertion, where the user checks if the second
-// bool is true before using the value.
+//  bool is true before using the value.
 //
 // The As* methods are similar to the Must* pattern in the standard library.
 // If the underlying value cannot be converted to the requested type,
-// As* will
-// panic.
+//  As* will
+//  panic.
 //
 // PopulateStruct
 //
-// PopulateStruct is akin to json.Unmarshal() in that it takes a pointer to a
+//  PopulateStruct is akin to json.Unmarshal() in that it takes a pointer to a
 // custom struct and fills in the fields. It returns a
-// true if the requested
+//  true if the requested
 // fields were found and populated properly, and
-// false otherwise.
+//  false otherwise.
 //
 // For example, say we have the following YAML file:
 //
@@ -121,7 +121,7 @@
 //   // Output: yes
 //
 // Note that any fields you wish to deserialize into must be exported, just like
-// json.Unmarshal and friends.
+//  json.Unmarshal and friends.
 //
 //
 package config

core/doc.go

@@ -27,7 +27,7 @@
 //
 // If, for example, you just want use the configuration logic from UberFx, you
 // could import
-// go.uber.org/core/config and use it in a stand-alone CLI app.
+//  go.uber.org/core/config and use it in a stand-alone CLI app.
 //
 // It is separate from the service package, which contains logic specifically to
 // a running service.

core/ulog/README.md

@@ -1,8 +1,12 @@
 # Logging package
 
-ulog provides an API wrapper around the logging library (zap Logger)
-The logger is instantiated as logger with default options and can be configured
-via `Configure()` API and provided YAML configuration.
+`package ulog` provides an API wrapper around the logging library [zap](https://github.com/uber-go/zap).
+`ulog` uses the builder pattern to instantiate the logger. With `LogBuilder` you can perform pre-initialization set up
+by injecting configuration, custom logger and log level prior to building the usable `ulog.Log` object. `ulog.Log`
+interface provides a few benifits -
+- Decouple services from the logger used undeaneath the framework.
+- Easy to use API for logging.
+- Easily swappable backend logger without changing the service.
 
 ```go
 package main
@@ -11,21 +15,25 @@ import "go.uber.org/fx/core/ulog"
 
 func main() {
   // Initialize logger object
-  log := ulog.Logger()
+  logBuilder := ulog.Builder()
 
   // Optional, configure logger with configuration preferred by your service
   logConfig := ulog.Configuration{}
-  log.Configure(&logConfig)
+  logBuilder := logBuilder.WithConfiguration(&logConfig)
+
+  // build ulog.Log from logBuilder
+  log := lobBuilder.Build()
 
   // Use logger in your service
   log.Info("Message describing loggging reason", "key", "value")
 }
 ```
 
-Note that the log methods (`Info`,`Warn`, `Debug`) takes parameter as key value pairs (message, (key, value)...)
+Note that the log methods (`Info`,`Warn`, `Debug`) take parameters as key value
+pairs (message, (key, value)...)
 
-ulog configuration can be defined in multiple ways, either by writing the struct yourself, or describing in the YAML
-and populating using config package.
+`ulog.Configuration` can be set up in one of two ways, either by initializing the struct,
+or describing necessary `logging` configuration in the YAML and populating using `config` package.
 
 * Defining config structure:
 
@@ -42,3 +50,25 @@ logging:
   stdout: true
   level: debug
 ```
+
+You can initialize your own `zap.Logger` implementation and inject into `ulog`.
+To configure and inject `zap.Logger`, set up the logger prior to building
+the `ulog.Log` object.
+
+```go
+func setupMyZapLogger(zaplogger zap.Logger) ulog.Log {
+  return ulog.Builder().SetLogger(zaplogger).Build()
+}
+```
+
+* Current benchmarks
+
+Current performance benchmark data with `ulog interface`, `ulog baselogger struct`, and `zap.Logger`
+
+|-------------------------------------------|----------|-----------|-----------|------------|
+|BenchmarkUlogWithoutFields-8               |5000000   |226 ns/op  |48 B/op    |1 allocs/op |
+|BenchmarkUlogWithFieldsLogIFace-8          |2000000   |1026 ns/op |1052 B/op  |19 allocs/op|
+|BenchmarkUlogWithFieldsBaseLoggerStruct-8  |2000000   |912 ns/op  |795 B/op   |18 allocs/op|
+|BenchmarkUlogWithFieldsZapLogger-8         |3000000   |558 ns/op  |513 B/op   |1 allocs/op |
+|BenchmarkUlogLiteWithFields-8              |3000000   |466 ns/op  |297 B/op   |7 allocs/op |
+

core/ulog/doc.go

@@ -20,32 +20,41 @@
 
 // Package ulog is the Logging package.
 //
-// ulog provides an API wrapper around the logging library (zap Logger)
-// The logger is instantiated as logger with default options and can be configured
-// via
-// Configure() API and provided YAML configuration.
+//  package ulog provides an API wrapper around the logging libraryzap (https://github.com/uber-go/zap).
+//  ulog uses the builder pattern to instantiate the logger. With LogBuilder you can perform pre-initialization set up
+// by injecting configuration, custom logger and log level prior to building the usable
+//  ulog.Log object. ulog.Loginterface provides a few benifits -
+// - Decouple services from the logger used undeaneath the framework.
+// - Easy to use API for logging.
+// - Easily swappable backend logger without changing the service.
+//
 //
 //   package main
 //
 //   import "go.uber.org/fx/core/ulog"
 //
 //   func main() {
 //     // Initialize logger object
-//     log := ulog.Logger()
+//     logBuilder := ulog.Builder()
 //
 //     // Optional, configure logger with configuration preferred by your service
 //     logConfig := ulog.Configuration{}
-//     log.Configure(&logConfig)
+//     logBuilder := logBuilder.WithConfiguration(&logConfig)
+//
+//     // build ulog.Log from logBuilder
+//     log := lobBuilder.Build()
 //
 //     // Use logger in your service
 //     log.Info("Message describing loggging reason", "key", "value")
 //   }
 //
-// Note that the log methods (Info,Warn, Debug) takes parameter as key value pairs (message, (key, value)...)
+// Note that the log methods ( Info, Warn, Debug) take parameters as key value
+// pairs (message, (key, value)...)
 //
-// ulog configuration can be defined in multiple ways, either by writing the struct yourself, or describing in the YAML
-// and populating using config package.
 //
+//  ulog.Configuration can be set up in one of two ways, either by initializing the struct,
+// or describing necessary
+//  logging configuration in the YAML and populating using config package.
 //
 // • Defining config structure:
 //
@@ -59,5 +68,27 @@
 //     stdout: true
 //     level: debug
 //
+// You can initialize your own zap.Logger implementation and inject into ulog.
+// To configure and inject
+//  zap.Logger, set up the logger prior to building
+// the
+//  ulog.Log object.
+//
+//   func setupMyZapLogger(zaplogger zap.Logger) ulog.Log {
+//     return ulog.Builder().SetLogger(zaplogger).Build()
+//   }
+//
+// • Current benchmarks
+//
+// Current performance benchmark data with ulog interface, ulog baselogger struct, and zap.Logger
+//
+// |-------------------------------------------|----------|-----------|-----------|------------|
+// |BenchmarkUlogWithoutFields-8               |5000000   |226 ns/op  |48 B/op    |1 allocs/op |
+// |BenchmarkUlogWithFieldsLogIFace-8          |2000000   |1026 ns/op |1052 B/op  |19 allocs/op|
+// |BenchmarkUlogWithFieldsBaseLoggerStruct-8  |2000000   |912 ns/op  |795 B/op   |18 allocs/op|
+// |BenchmarkUlogWithFieldsZapLogger-8         |3000000   |558 ns/op  |513 B/op   |1 allocs/op |
+// |BenchmarkUlogLiteWithFields-8              |3000000   |466 ns/op  |297 B/op   |7 allocs/op |
+//
+//
 //
 package ulog

doc.go

@@ -47,7 +47,7 @@
 //
 // This model results in a simple, consistent way to start a service.  For example,
 // in the case of a simple TChannel Service,
-// main.go might look like this:
+//  main.go might look like this:
 //
 //   package main
 //
@@ -112,13 +112,13 @@
 //
 // Which then allows us to set the roles either via a command line variable:
 //
-// export CONFIG__roles__0=worker
+//  export CONFIG__roles__0=worker
 //
 // Or via the service parameters, we would activate in the following ways:
 //
-// • ./myservice or ./myservice --roles "service,worker": Runs all modules
+// •  ./myservice or ./myservice --roles "service,worker": Runs all modules
 //
-// • ./myservice --roles "worker": Runs only the **Kakfa** module
+// •  ./myservice --roles "worker": Runs only the **Kakfa** module
 //
 // • Etc...
 //
@@ -157,7 +157,7 @@
 //       timeout: 60s
 //
 // In this example, a module named: "rpc" would lookup it's advertise name as
-// modules.rpc.advertiseName.
+//  modules.rpc.advertiseName.
 //
 // Metrics
 //
@@ -167,7 +167,7 @@
 // Internally, this uses a pluggable mechanism for reporting these values, so they
 // can be reported to M3, logging, etc., at the service owner's discretion.
 // By default the metrics are not reported (using a
-// tally.NoopScope)
+//  tally.NoopScope)
 //
 // Configuration
 //

modules/rpc/doc.go

@@ -20,7 +20,7 @@
 
 // Package rpc is the RPC Module.
 //
-// The RPC module wraps YARPC (https://github.com/yarpc/yarpc-go) and exposes
+// The RPC module wrapsYARPC (https://github.com/yarpc/yarpc-go) and exposes
 // creators for both JSON- and Thrift-encoded messages.
 //
 //
@@ -33,9 +33,9 @@
 // • Implement the service interface handlers as method receivers on a struct
 //
 // • Implement a top-level function, conforming to the
-// rpc.CreateThriftServiceFunc signature (uberfx/modules/rpc/thrift.go that
+//  rpc.CreateThriftServiceFunc signature ( uberfx/modules/rpc/thrift.go that
 // returns a
-// []transport.Registrant YARPC implementation from the handler:
+//  []transport.Registrant YARPC implementation from the handler:
 //
 //   func NewMyServiceHandler(svc service.Host) ([]transport.Registrant, error) {
 //     return myservice.New(&MyServiceHandler{}), nil

modules/uhttp/doc.go

@@ -20,9 +20,9 @@
 
 // Package uhttp is the HTTP Module.
 //
-// The HTTP module is built on top of Gorilla Mux (https://github.com/gorilla/mux),
+// The HTTP module is built on top ofGorilla Mux (https://github.com/gorilla/mux),
 // but the details of that are abstracted away through
-// uhttp.RouteHandler.
+//  uhttp.RouteHandler.
 //
 //   package main
 //