phuslog Documentation

When working with OpenTelemetry code that expects a log.LoggerProvider, you can use the phuslogotel.Logger implementation to satisfy the otellog.Logger interface. This allows you to use standard OpenTelemetry logging calls while benefiting from phuslog's performance and JSON format.

// Implementation of otellog.Logger using phuslog
var logger otellog.Logger = phuslogotel.Logger{
	Log: phuslog.Logger{
		Level: phuslog.InfoLevel,
	},
}

You can customize the global log.DefaultLogger or create local log.Logger instances to control field names, time formats, and log levels.

Key configuration fields:

• Level: The minimum log level (e.g., log.InfoLevel).
• Caller: Depth for capturing the file/line number.
• TimeField: The name of the timestamp field in the output.
• TimeFormat: The format string for the timestamp (supports standard Go layouts or constants like log.TimeFormatUnixMs).
• Writer: The destination for logs.

package main

import (
	"os"
	"github.com/phuslu/log"
)

func main() {
	// Customizing the default global logger
	log.DefaultLogger = log.Logger{
		Level:      log.InfoLevel,
		Caller:     1,
		TimeField:  "date",
		TimeFormat: "2006-01-02",
		Writer:     &log.IOWriter{os.Stdout},
	}

	log.Info().Str("foo", "bar").Msgf("hello %s", "world")
}

The Context type allows you to work with pre-encoded JSON byte slices to avoid re-encoding overhead. This is useful for high-performance scenarios where parts of the log context are reused.

1. Create a context using NewContext(dst []byte).
2. Build fields into that context using Entry methods.
3. Retrieve the bytes via Value().
4. Attach it to a new log entry using Dict(key string, ctx Context) or Context(ctx Context).

Dict wraps the context in a JSON object {...} under the specified key, while Context appends the raw bytes directly to the entry buffer.

// 1. Create a context
ctx := NewContext(nil)
ctx.Str("session_id", "abc-123").Int("retry", 1)

// 2. Use it in a log entry
logger.Info().
    Dict("session_context", ctx.Value()).
    Msg("user action")

The otel package provides an implementation of the OpenTelemetry (OTel) Logger and LoggerProvider interfaces, using phuslog as the underlying structured logging engine. This allows you to use standard OpenTelemetry logging APIs while benefiting from the performance and structured output of phuslog.

To use it, you typically create a LoggerProvider configured with a phuslog.Logger, and then use that provider to create OTel-compliant Logger instances.

// Example conceptual usage
provider := otel.LoggerProvider{
    Log: phuslogLogger, // An existing phuslog.Logger
}

// Create an OTel logger
otelLogger := provider.Logger("my-service")

// Use the OTel logger
ctx := context.Background()
otelLogger.Emit(ctx, otellog.NewRecord(otellog.SeverityInfo, otellog.NewValue(otellog.KindString, "hello world")))

The package provides a DefaultLogger which is pre-configured to log to os.Stderr at DebugLevel. You can use it directly via package-level functions like log.Info() or log.Error().

import "github.com/phuslu/phuslu/log"

func main() {
    log.Info().Msg("hello world")
    log.Error().Str("error_code", "500").Msg("something went wrong")
}

By default, phuslog writes to os.Stderr. You can use structured logging by chaining methods like .Str(), .Int(), and .Err() before calling a terminal method like .Msg() or .Msgf().

package main

import (
	"github.com/phuslu/log"
)

func main() {
	log.Info().Str("foo", "bar").Int("number", 42).Msg("hi, phuslog")
	log.Info().Msgf("foo=%s number=%d error=%+v", "bar", 42, "an error")
}

You can use phuslog as a high-performance replacement for slog.JSONHandler or wrap it to work with the standard slog API.

To use it as a drop-in replacement for slog.JSONHandler:

slog.SetDefault(slog.New(phuslog.SlogNewJSONHandler(os.Stderr, &slog.HandlerOptions{AddSource: true})))

import (
	"log/slog"
	"os"
	phuslog "github.com/phuslu/log"
)

func main() {
	slog.SetDefault(slog.New(phuslog.SlogNewJSONHandler(os.Stderr, &slog.HandlerOptions{AddSource: true})))
	slog.Info("hello from phuslog", "a", 1, "b", 2)
}

Use log.NewContext to create a context containing key-value pairs that will be automatically included in every subsequent log entry from that logger instance.

logger := log.Logger{
	Level:   log.InfoLevel,
	Context: log.NewContext(nil).Str("ctx", "some_ctx").Value(),
}

logger.Info().Msg("this log will have the ctx field")