README
¶
⚡ gcloudzap 
(experimental)
Formerly https://github.com/jonstaryuk/gcloudzap
This package provides a zap logger that forwards entries to the Google Stackdriver Logging service as structured payloads.
Quickstart
Outside of Google Compute Engine, just add the environment variable GOOGLE_APPLICATION_CREDENTIALS with a path to a JSON credential file. For more info on this approach, see the docs.
Option 1: Less configuration
import "github.com/dhduvall/gcloudzap"
log, err := gcloudzap.NewDevelopment("your-project-id", "your-log-id")
if err != nil {
panic(err)
}
log.Sugar().
With("simple", true).
With("foo", "bar").
Info("This will get written to both stderr and Stackdriver Logging.")
Option 2: More flexibility
import (
"go.uber.org/zap"
"cloud.google.com/go/logging"
"github.com/dhduvall/gcloudzap"
)
// Configure the pieces
client, err := logging.NewClient(...)
cfg := zap.Config{...}
// Create a logger
log, err := gcloudzap.New(cfg, client, "your-log-id", zap.Option(), ...)
Option 3: Most flexibility
import (
"go.uber.org/zap/zapcore"
"cloud.google.com/go/logging"
"github.com/dhduvall/gcloudzap"
)
// Configure the pieces
client, err := logging.NewClient(...)
baseCore := zapcore.NewCore(...)
// Create a core
core := gcloudzap.Tee(baseCore, client, "your-log-id")
Documentation
¶
Overview ¶
Package gcloudzap provides a zap logger that forwards entries to the Google Stackdriver Logging service as structured payloads.
All zap.Logger instances created with this package are safe for concurrent use.
Network calls (which are delegated to the Google Cloud Platform package) are asynchronous and payloads are buffered. These benchmarks, on a MacBook Pro 2.4 GHz Core i5, are a loose approximation of latencies on the critical path for the zapcore.Core implementation provided by this package.
$ go test -bench . github.com/dhduvall/gcloudzap goos: darwin goarch: amd64 pkg: github.com/dhduvall/gcloudzap BenchmarkCoreClone-4 2000000 607 ns/op BenchmarkCoreWrite-4 1000000 2811 ns/op
Zap docs: https://godoc.org/go.uber.org/zap
Stackdriver Logging docs: https://cloud.google.com/logging/docs/
Index ¶
- Constants
- Variables
- func New(cfg zap.Config, client *gcl.Client, logID string, opts ...zap.Option) (*zap.Logger, error)
- func NewDevelopment(projectID string, logID string) (*zap.Logger, error)
- func NewProduction(projectID string, logID string) (*zap.Logger, error)
- func Tee(zc zapcore.Core, client *gcl.Client, gclLogID string) zapcore.Core
- type Core
- type GoogleCloudLogger
Constants ¶
const ( // InsertIDKey is the payload field key to use to set the insertId field // in the LogEntry object. InsertIDKey = "logging.googleapis.com/insertId" // CallerKey is the payload field key to use to set the sourceLocation // field in the LogEntry object. CallerKey = "logging.googleapis.com/sourceLocation" // CallerType is the zap field type to use to set the sourceLocation // field in the LogEntry object. CallerType = zapcore.SkipType // SkipKey is the payload field key to use to tell the core not to write // the entry to Stackdriver. SkipKey = "logging.googleapis.com/skipLogging" // SkipType is the zap field type that ought to (though needn't) be used // with a field with key SkipKey. SkipType = zapcore.SkipType )
Variables ¶
var DefaultSeverityMapping = map[zapcore.Level]gcl.Severity{ zapcore.DebugLevel: gcl.Debug, zapcore.InfoLevel: gcl.Info, zapcore.WarnLevel: gcl.Warning, zapcore.ErrorLevel: gcl.Error, zapcore.DPanicLevel: gcl.Critical, zapcore.PanicLevel: gcl.Critical, zapcore.FatalLevel: gcl.Critical, }
DefaultSeverityMapping is the default mapping of zap's Levels to Google's Severities.
var ( // SkipField is a pre-constructed field that will skip being logged SkipField = zapcore.Field{Key: SkipKey, Type: SkipType} )
Functions ¶
func New ¶
New creates a new zap.Logger which will write entries to Stackdriver in addition to the destination specified by the provided zap configuration.
func NewDevelopment ¶
NewDevelopment builds a development Logger that writes DebugLevel and above logs to standard error in a human-friendly format, as well as to Stackdriver using Application Default Credentials.
func NewProduction ¶
NewProduction builds a production Logger that writes InfoLevel and above logs to standard error as JSON, as well as to Stackdriver using Application Default Credentials.
func Tee ¶
Tee returns a zapcore.Core that writes entries to both the provided core and to Stackdriver using the provided client. The provided gclLogID will form the base of each GCP LogEntry's logID, to which will be appended the zap logger name.
For fields to be written to Stackdriver, you must use the With() method on the returned Core rather than just on zc. (This function has no way of knowing about fields that already exist on zc. They will be preserved when writing to zc's existing destination, but not to Stackdriver.)
Types ¶
type Core ¶
type Core struct {
// Logger is a logging.Logger instance from the Google Cloud Platform Go
// library.
Logger GoogleCloudLogger
// Provide your own mapping of zapcore's Levels to Google's Severities, or
// use DefaultSeverityMapping. All of the Core's children will default to
// using this map.
//
// This must not be mutated after the Core's first use.
SeverityMapping map[zapcore.Level]gcl.Severity
// MinLevel is the minimum level for a log entry to be written.
MinLevel zapcore.Level
// contains filtered or unexported fields
}
A Core implements zapcore.Core and writes entries to a Logger from the Google Cloud package.
It's safe for concurrent use by multiple goroutines as long as it's not mutated after first use.
func (*Core) Check ¶
func (c *Core) Check(e zapcore.Entry, ce *zapcore.CheckedEntry) *zapcore.CheckedEntry
Check implements zapcore.Core.
func (*Core) Write ¶
Write implements zapcore.Core. It writes a log entry to Stackdriver.
Certain fields in the zapcore.Entry are used to populate the Stackdriver entry: the Message field maps to "message" in the payload and the Stack field maps to "stack". LoggerName helps populate the logName field in the log entry, as well as mapping to "logger" in the payload.
If there is a field with key CallerKey and type CallerType, and it is a pkg/errors.stackTracer, then the first frame of the stack is put into the Stackdriver entry object's SourceLocation field, and the original field is removed from the payload sent to Stackdriver. If not, then the Caller field from the zap Entry is used instead.
If there is a field with key SkipKey (and any value, but type zapcore.SkipType would be the most useful), the core will skip writing this entry to Stackdriver. This allows the application to prevent writing sensitive data to the cloud, while still allowing cores writing to the terminal to write those entries.
type GoogleCloudLogger ¶
GoogleCloudLogger encapsulates the important methods of gcl.Logger
Source Files