log

README

Pydio LOG

Pydio relies on zap logging framework.

We mainly use 2 loggers that are defined in this package and used throughout the backend:

• A syslog logger: it should be used to log technical information.
• An audit logger: it only logs some very precise information at strategic places and is used to monitor the Application from a business point of view. Audit logs are among others used for GRDP compliance.

WARNING: you should not modify nor remove any of the audit log.

Guidelines

• When enriching the log with zap fields, always use constants from common/zapfields.go as keys, otherwise the logs won't be usable for analysis
• Pydio provides some shortcuts to easily generate zap fields for commons pydio objects. Typically when loging info about a tree.Node, one should write: ...Debug("A message", node.Zap())
• Depending on the level of details required, one can either use Zap() that serializes all accessible information or ZapPath(), ZapUuid() or ZapId() (depending on the relevant info) that simply calls zap.String() with relevant pydio zap id (as seen in common/zapfields.go) and corresponding value.

Conventions

• it is idiomatic in Go to write error message that start with a lower case letter and do not end with a punctuation mark.

Documentation

Overview

• Copyright (c) 2019-2021. Abstrium SAS <team (at) pydio.com>
• This file is part of Pydio Cells. *
• Pydio Cells is free software: you can redistribute it and/or modify
• it under the terms of the GNU Affero General Public License as published by
• the Free Software Foundation, either version 3 of the License, or
• (at your option) any later version. *
• Pydio Cells is distributed in the hope that it will be useful,
• but WITHOUT ANY WARRANTY; without even the implied warranty of
• MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
• GNU Affero General Public License for more details. *
• You should have received a copy of the GNU Affero General Public License
• along with Pydio Cells. If not, see <http://www.gnu.org/licenses/>. *
• The latest code can be found at <https://pydio.com>.

Package log define and configure the Pydio loggers based on zap.

We mainly use 2 loggers that are defined in this package and used throughout the backend: - A syslog logger: it should be used to log technical information. - An audit logger: it only logs some very precise information at strategic places and is used to monitor the Application from a business point of view. Audit logs are among others used for GRDP compliance.

WARNING: you should not modify nor remove any of the audit log.

Index

• Constants
• Variables
• func CaptureCaddyStdErr(serviceName string) context.Context
• func DangerouslyZapSmallSlice(key string, value interface{}) zapcore.Field
• func Debug(msg string, fields ...zapcore.Field)
• func Error(msg string, fields ...zapcore.Field)
• func Fatal(msg string, fields ...zapcore.Field)
• func GetAuditId(msgId string) zapcore.Field
• func Info(msg string, fields ...zapcore.Field)
• func Init(logDir string, ww ...LogContextWrapper)
• func RFC3369TimeEncoder(t time.Time, enc zapcore.PrimitiveArrayEncoder)
• func RegisterConsoleNamedColor(serviceName string, color int)
• func RegisterWriteSyncer(syncer WriteSyncer)
• func SetAuditerInit(f func() *zap.Logger, globalConnInit func(ctx context.Context))
• func SetDynamicDebugLevels(reset, level bool, services ...string)
• func SetLoggerInit(f func() *zap.Logger, globalConnInit func(ctx context.Context))
• func SetSkipServerSync()
• func SetTasksLoggerInit(f func() *zap.Logger, globalConnInit func(ctx context.Context))
• func Warn(msg string, fields ...zapcore.Field)
• type LogContextWrapper
• type LogSyncer
  • func NewLogSyncer(ctx context.Context, serviceName string) *LogSyncer
  • func (syncer *LogSyncer) Write(p []byte) (n int, err error)
• type WriteSyncer
• type ZapLogger
  • func Auditer(ctx context.Context) ZapLogger
  • func BasicContextWrapper(ctx context.Context, logger ZapLogger, fields ...zapcore.Field) ZapLogger
  • func Logger(ctx context.Context) ZapLogger
  • func TasksLogger(ctx context.Context) ZapLogger

Constants

const (
	ConsoleColorRest  = 32
	ConsoleColorGrpc  = 35
	ConsoleColorOther = 36
)

Variables

var (
	ConsoleSkipKeys = []string{

		common.KeySpanUuid,
		common.KeySpanRootUuid,
		common.KeySpanParentUuid,
		common.KeySchedulerJobId,
		common.KeySchedulerActionPath,
		common.KeySchedulerTaskId,

		common.KeyUsername,
		common.KeyUserUuid,
		common.KeyGroupPath,
		common.KeyProfile,
		common.KeyRoles,

		servicecontext.HttpMetaRemoteAddress,
		servicecontext.HttpMetaUserAgent,
		servicecontext.HttpMetaContentType,
		servicecontext.HttpMetaProtocol,
	}
)

var (
	EmptyServiceKey = "empty"
)

var (
	StdOut *os.File
)

Functions

func CaptureCaddyStdErr

func CaptureCaddyStdErr(serviceName string) context.Context

func DangerouslyZapSmallSlice

func DangerouslyZapSmallSlice(key string, value interface{}) zapcore.Field

DangerouslyZapSmallSlice is a simple clone for zap.Any, allowing the linter to consider the slice zap as legitimate. It informs the developer to make sure that the slice passed must be small, otherwise it can hang the internal logger

func Debug

func Debug(msg string, fields ...zapcore.Field)

func Error

func Error(msg string, fields ...zapcore.Field)

func Fatal

func Fatal(msg string, fields ...zapcore.Field)

func GetAuditId

func GetAuditId(msgId string) zapcore.Field

GetAuditId simply returns a zap field that contains this message id to ease audit log analysis.

func Info

func Info(msg string, fields ...zapcore.Field)

func Init

func Init(logDir string, ww ...LogContextWrapper)

Init for the log package - called by the main

func RFC3369TimeEncoder

func RFC3369TimeEncoder(t time.Time, enc zapcore.PrimitiveArrayEncoder)

RFC3369TimeEncoder serializes a time.Time to an RFC3339-formatted string

func RegisterConsoleNamedColor

func RegisterConsoleNamedColor(serviceName string, color int)

RegisterConsoleNamedColor allows external registration of colors based on Logger Name.

func RegisterWriteSyncer

func RegisterWriteSyncer(syncer WriteSyncer)

RegisterWriteSyncer optional writers for logs

func SetAuditerInit

func SetAuditerInit(f func() *zap.Logger, globalConnInit func(ctx context.Context))

SetAuditerInit defines what function to use to init the auditer

func SetDynamicDebugLevels

func SetDynamicDebugLevels(reset, level bool, services ...string)

SetDynamicDebugLevels overrides Info level for a specific subset of services

func SetLoggerInit

func SetLoggerInit(f func() *zap.Logger, globalConnInit func(ctx context.Context))

SetLoggerInit defines what function to use to init the logger

func SetSkipServerSync

func SetSkipServerSync()

SetSkipServerSync can disable the core syncing to cells service Must be called before initialization

func SetTasksLoggerInit

func SetTasksLoggerInit(f func() *zap.Logger, globalConnInit func(ctx context.Context))

SetTasksLoggerInit defines what function to use to init the tasks logger

func Warn

func Warn(msg string, fields ...zapcore.Field)

Types

type LogContextWrapper

type LogContextWrapper func(ctx context.Context, logger ZapLogger, fields ...zapcore.Field) ZapLogger

type LogSyncer

type LogSyncer struct {
	// contains filtered or unexported fields
}

func NewLogSyncer

func NewLogSyncer(ctx context.Context, serviceName string) *LogSyncer

func (*LogSyncer) Write

func (syncer *LogSyncer) Write(p []byte) (n int, err error)

Write implements the io.Writer interface to be used as a Syncer by zap logging. We must copy the []byte as a underlying buffer can mess up things if logs are called very quickly.

type WriteSyncer

type WriteSyncer interface {
	io.Writer
	Sync() error
}

WriteSyncer implements zapcore.WriteSyncer

type ZapLogger

type ZapLogger interface {
	Named(s string) ZapLogger
	WithOptions(opts ...zap.Option) ZapLogger
	With(fields ...zap.Field) ZapLogger

	Debug(msg string, fields ...zap.Field)
	Info(msg string, fields ...zap.Field)
	Warn(msg string, fields ...zap.Field)
	Error(msg string, fields ...zap.Field)
	DPanic(msg string, fields ...zap.Field)
	Panic(msg string, fields ...zap.Field)
	Fatal(msg string, fields ...zap.Field)

	Sugar() *zap.SugaredLogger
	Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry
	Sync() error
	Core() zapcore.Core
}

func Auditer

func Auditer(ctx context.Context) ZapLogger

Auditer returns a zap logger with as much context as possible

func BasicContextWrapper

func BasicContextWrapper(ctx context.Context, logger ZapLogger, fields ...zapcore.Field) ZapLogger

BasicContextWrapper creates a Named logger from serviceName found in context

func Logger

func Logger(ctx context.Context) ZapLogger

Logger returns a zap logger with as much context as possible.

func TasksLogger

func TasksLogger(ctx context.Context) ZapLogger

TasksLogger returns a zap logger with as much context as possible.