Add New Trace Logging Level

level.go

@@ -26,6 +26,10 @@ import (
 )
 
 const (
+	// TraceLevel logs are especially granular log messages that are used in development and debugging
+	// situations in which tracing of function inputs at outputs are necessary. Almost always disabled in production
+	// due to performance hits associated with very voluminous logs.
+	TraceLevel = zapcore.TraceLevel
 	// DebugLevel logs are typically voluminous, and are usually disabled in
 	// production.
 	DebugLevel = zapcore.DebugLevel

level_test.go

@@ -35,6 +35,7 @@ func TestLevelEnablerFunc(t *testing.T) {
 		level   zapcore.Level
 		enabled bool
 	}{
+		{TraceLevel, false},
 		{DebugLevel, false},
 		{InfoLevel, true},
 		{WarnLevel, false},
@@ -81,6 +82,7 @@ func TestAtomicLevelText(t *testing.T) {
 		expect zapcore.Level
 		err    bool
 	}{
+		{"trace", TraceLevel, false},
 		{"debug", DebugLevel, false},
 		{"info", InfoLevel, false},
 		{"", InfoLevel, false},

logger.go

@@ -172,6 +172,14 @@ func (log *Logger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
 	return log.check(lvl, msg)
 }
 
+// Trace logs a message at TraceLevel. The message includes any fields passed
+// at the log site, as well as any fields accumulated on the logger.
+func (log *Logger) Trace(msg string, fields ...Field) {
+	if ce := log.check(TraceLevel, msg); ce != nil {
+		ce.Write(fields...)
+	}
+}
+
 // Debug logs a message at DebugLevel. The message includes any fields passed
 // at the log site, as well as any fields accumulated on the logger.
 func (log *Logger) Debug(msg string, fields ...Field) {

logger_test.go

@@ -57,6 +57,8 @@ func TestLoggerAtomicLevel(t *testing.T) {
 			testLevel zapcore.Level
 			enabled   bool
 		}{
+			{TraceLevel, TraceLevel, true},
+			{DebugLevel, TraceLevel, false},
 			{DebugLevel, DebugLevel, true},
 			{InfoLevel, DebugLevel, false},
 			{WarnLevel, PanicLevel, true},
@@ -169,11 +171,12 @@ func TestLoggerLogFatal(t *testing.T) {
 }
 
 func TestLoggerLeveledMethods(t *testing.T) {
-	withLogger(t, DebugLevel, nil, func(logger *Logger, logs *observer.ObservedLogs) {
+	withLogger(t, TraceLevel, nil, func(logger *Logger, logs *observer.ObservedLogs) {
 		tests := []struct {
 			method        func(string, ...Field)
 			expectedLevel zapcore.Level
 		}{
+			{logger.Trace, TraceLevel},
 			{logger.Debug, DebugLevel},
 			{logger.Info, InfoLevel},
 			{logger.Warn, WarnLevel},

zapcore/level.go

@@ -32,9 +32,13 @@ var errUnmarshalNilLevel = errors.New("can't unmarshal a nil *Level")
 type Level int8
 
 const (
+	// TraceLevel logs are especially granular log messages that are used in development and debugging
+	// situations in which tracing of function inputs at outputs are necessary. Almost always disabled in production
+	// due to performance hits associated with very voluminous logs.
+	TraceLevel Level = iota - 2
 	// DebugLevel logs are typically voluminous, and are usually disabled in
 	// production.
-	DebugLevel Level = iota - 1
+	DebugLevel
 	// InfoLevel is the default logging priority.
 	InfoLevel
 	// WarnLevel logs are more important than Info, but don't need individual
@@ -51,13 +55,15 @@ const (
 	// FatalLevel logs a message, then calls os.Exit(1).
 	FatalLevel
 
-	_minLevel = DebugLevel
+	_minLevel = TraceLevel
 	_maxLevel = FatalLevel
 )
 
 // String returns a lower-case ASCII representation of the log level.
 func (l Level) String() string {
 	switch l {
+	case TraceLevel:
+		return "trace"
 	case DebugLevel:
 		return "debug"
 	case InfoLevel:
@@ -82,6 +88,8 @@ func (l Level) CapitalString() string {
 	// Printing levels in all-caps is common enough that we should export this
 	// functionality.
 	switch l {
+	case TraceLevel:
+		return "TRACE"
 	case DebugLevel:
 		return "DEBUG"
 	case InfoLevel:
@@ -125,6 +133,8 @@ func (l *Level) UnmarshalText(text []byte) error {
 
 func (l *Level) unmarshalText(text []byte) bool {
 	switch string(text) {
+	case "trace", "TRACE":
+		*l = TraceLevel
 	case "debug", "DEBUG":
 		*l = DebugLevel
 	case "info", "INFO", "": // make the zero value useful

zapcore/level_strings.go

@@ -24,6 +24,7 @@ import "go.uber.org/zap/internal/color"
 
 var (
 	_levelToColor = map[Level]color.Color{
+		TraceLevel:  color.Green,
 		DebugLevel:  color.Magenta,
 		InfoLevel:   color.Blue,
 		WarnLevel:   color.Yellow,

zapcore/level_test.go

@@ -31,6 +31,7 @@ import (
 
 func TestLevelString(t *testing.T) {
 	tests := map[Level]string{
+		TraceLevel:  "trace",
 		DebugLevel:  "debug",
 		InfoLevel:   "info",
 		WarnLevel:   "warn",
@@ -52,6 +53,7 @@ func TestLevelText(t *testing.T) {
 		text  string
 		level Level
 	}{
+		{"trace", TraceLevel},
 		{"debug", DebugLevel},
 		{"info", InfoLevel},
 		{"", InfoLevel}, // make the zero value useful
@@ -81,6 +83,7 @@ func TestCapitalLevelsParse(t *testing.T) {
 		text  string
 		level Level
 	}{
+		{"TRACE", TraceLevel},
 		{"DEBUG", DebugLevel},
 		{"INFO", InfoLevel},
 		{"WARN", WarnLevel},
@@ -103,6 +106,7 @@ func TestWeirdLevelsParse(t *testing.T) {
 		level Level
 	}{
 		// I guess...
+		{"Trace", TraceLevel},
 		{"Debug", DebugLevel},
 		{"Info", InfoLevel},
 		{"Warn", WarnLevel},
@@ -112,6 +116,7 @@ func TestWeirdLevelsParse(t *testing.T) {
 		{"Fatal", FatalLevel},
 
 		// What even is...
+		{"TrAcE", TraceLevel},
 		{"DeBuG", DebugLevel},
 		{"InFo", InfoLevel},
 		{"WaRn", WarnLevel},