feat(otel): add OpenTelemetry support

pkg/gotenberg/internal/log/color.go

@@ -0,0 +1,40 @@
+package log
+
+import (
+	"fmt"
+	"log/slog"
+)
+
+// Foreground colors.
+// Copy pasted from go.uber.org/zap/internal/color/color.go
+const (
+	black color = iota + 30
+	red
+	green
+	yellow
+	blue
+	magenta
+	cyan
+	white
+)
+
+type color uint8
+
+func (c color) Add(s string) string {
+	return fmt.Sprintf("\x1b[%dm%s\x1b[0m", uint8(c), s)
+}
+
+func levelToColor(l slog.Level) color {
+	switch l {
+	case slog.LevelDebug:
+		return cyan
+	case slog.LevelInfo:
+		return blue
+	case slog.LevelWarn:
+		return yellow
+	case slog.LevelError:
+		return red
+	default:
+		return red
+	}
+}

pkg/gotenberg/internal/log/doc.go

@@ -0,0 +1,2 @@
+// Package log gathers internal logging utilities.
+package log

pkg/gotenberg/internal/log/gcp.go

@@ -0,0 +1,18 @@
+package log
+
+import "log/slog"
+
+func gcpSeverity(l slog.Level) string {
+	switch {
+	case l < slog.LevelInfo:
+		return "DEBUG"
+	case l < slog.LevelWarn:
+		return "INFO"
+	case l < slog.LevelError:
+		return "WARNING"
+	case l >= slog.LevelError:
+		return "ERROR"
+	default:
+		return "DEFAULT"
+	}
+}

pkg/gotenberg/internal/log/handler.go

@@ -0,0 +1,171 @@
+package log
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+)
+
+type gotenbergHandler struct {
+	slog.Handler
+	fieldsPrefix string
+	loggerName   string
+}
+
+func NewGotenbergHandler(next slog.Handler, prefix string) slog.Handler {
+	return &gotenbergHandler{Handler: next, fieldsPrefix: prefix}
+}
+
+func (h *gotenbergHandler) Handle(ctx context.Context, r slog.Record) error {
+	var newAttrs []slog.Attr
+
+	if h.loggerName != "" {
+		newAttrs = append(newAttrs, slog.String("logger", h.loggerName))
+	}
+
+	var needsNewRecord bool
+	if len(newAttrs) > 0 {
+		needsNewRecord = true
+	}
+
+	if h.fieldsPrefix != "" {
+		r.Attrs(func(a slog.Attr) bool {
+			if a.Key == "logger" || a.Key == "correlation_id" || a.Key == "trace_id" || a.Key == "span_id" {
+				newAttrs = append(newAttrs, a)
+				needsNewRecord = true
+				return true
+			}
+			a.Key = h.fieldsPrefix + "_" + a.Key
+			newAttrs = append(newAttrs, a)
+			needsNewRecord = true
+			return true
+		})
+	} else if needsNewRecord {
+		r.Attrs(func(a slog.Attr) bool {
+			newAttrs = append(newAttrs, a)
+			return true
+		})
+	}
+
+	if needsNewRecord {
+		newR := slog.NewRecord(r.Time, r.Level, r.Message, r.PC)
+		newR.AddAttrs(newAttrs...)
+		r = newR
+	}
+
+	return h.Handler.Handle(ctx, r)
+}
+
+func (h *gotenbergHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	var prefixed []slog.Attr
+	newLoggerName := h.loggerName
+
+	for _, a := range attrs {
+		if a.Key == "logger" {
+			if newLoggerName == "" {
+				newLoggerName = a.Value.String()
+			} else {
+				newLoggerName = newLoggerName + "." + a.Value.String()
+			}
+			continue
+		}
+
+		if h.fieldsPrefix != "" {
+			if a.Key == "correlation_id" || a.Key == "trace_id" || a.Key == "span_id" {
+				// Don't prefix these keys
+			} else {
+				a.Key = h.fieldsPrefix + "_" + a.Key
+			}
+		}
+		prefixed = append(prefixed, a)
+	}
+
+	newHandler := h.Handler
+	if len(prefixed) > 0 {
+		newHandler = h.Handler.WithAttrs(prefixed)
+	}
+
+	return &gotenbergHandler{
+		Handler:      newHandler,
+		fieldsPrefix: h.fieldsPrefix,
+		loggerName:   newLoggerName,
+	}
+}
+
+func (h *gotenbergHandler) WithGroup(name string) slog.Handler {
+	return &gotenbergHandler{
+		Handler:      h.Handler.WithGroup(name),
+		fieldsPrefix: h.fieldsPrefix,
+		loggerName:   h.loggerName,
+	}
+}
+
+type multiHandler struct {
+	handlers []slog.Handler
+}
+
+func FanOut(handlers ...slog.Handler) slog.Handler {
+	return &multiHandler{handlers: handlers}
+}
+
+func (m *multiHandler) Enabled(ctx context.Context, level slog.Level) bool {
+	for _, h := range m.handlers {
+		if h.Enabled(ctx, level) {
+			return true
+		}
+	}
+	return false
+}
+
+func (m *multiHandler) Handle(ctx context.Context, r slog.Record) error {
+	var errs []error
+	for _, h := range m.handlers {
+		if h.Enabled(ctx, r.Level) {
+			if err := h.Handle(ctx, r.Clone()); err != nil {
+				errs = append(errs, err)
+			}
+		}
+	}
+	return errors.Join(errs...)
+}
+
+func (m *multiHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	cloned := make([]slog.Handler, len(m.handlers))
+	for i, h := range m.handlers {
+		cloned[i] = h.WithAttrs(attrs)
+	}
+	return &multiHandler{handlers: cloned}
+}
+
+func (m *multiHandler) WithGroup(name string) slog.Handler {
+	cloned := make([]slog.Handler, len(m.handlers))
+	for i, h := range m.handlers {
+		cloned[i] = h.WithGroup(name)
+	}
+	return &multiHandler{handlers: cloned}
+}
+
+type levelHandler struct {
+	slog.Handler
+	level slog.Level
+}
+
+func LevelFilter(next slog.Handler, level slog.Level) slog.Handler {
+	return &levelHandler{Handler: next, level: level}
+}
+
+func (h *levelHandler) Enabled(ctx context.Context, level slog.Level) bool {
+	return level >= h.level && h.Handler.Enabled(ctx, level)
+}
+
+func (h *levelHandler) Handle(ctx context.Context, r slog.Record) error {
+	return h.Handler.Handle(ctx, r)
+}
+
+func (h *levelHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return &levelHandler{Handler: h.Handler.WithAttrs(attrs), level: h.level}
+}
+
+func (h *levelHandler) WithGroup(name string) slog.Handler {
+	return &levelHandler{Handler: h.Handler.WithGroup(name), level: h.level}
+}

pkg/gotenberg/internal/log/log.go

@@ -0,0 +1,37 @@
+package log
+
+import (
+	"log/slog"
+	"sync"
+)
+
+// InitLogger initializes the global logger.
+func InitLogger(handler slog.Handler) {
+	if logger != nil {
+		return
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+
+	// Double check: ensure it wasn't initialized while we waited for the lock.
+	if logger != nil {
+		return
+	}
+
+	logger = slog.New(handler)
+}
+
+// Logger returns the global logger.
+func Logger() *slog.Logger {
+	mu.Lock()
+	defer mu.Unlock()
+
+	return logger
+}
+
+// logger is Singleton so that we instantiate our [slog.Logger] only once.
+var (
+	logger *slog.Logger
+	mu     sync.Mutex
+)

pkg/gotenberg/internal/log/stdhandler.go

@@ -0,0 +1,128 @@
+package log
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"strings"
+
+	"go.opentelemetry.io/otel/trace"
+	"golang.org/x/term"
+)
+
+const (
+	autoLoggingFormat = "auto"
+	jsonLoggingFormat = "json"
+	textLoggingFormat = "text"
+)
+
+// traceContextHandler is an internal wrapper that specifically injects
+// trace_id and span_id into the log record before they are written to the standard output.
+type traceContextHandler struct {
+	slog.Handler
+}
+
+func (h traceContextHandler) Handle(ctx context.Context, r slog.Record) error {
+	if spanCtx := trace.SpanContextFromContext(ctx); spanCtx.IsValid() {
+		// Since slog.Record is immutable with regards to adding attributes in-place,
+		// we must clone and add them.
+		newR := slog.NewRecord(r.Time, r.Level, r.Message, r.PC)
+		r.Attrs(func(a slog.Attr) bool {
+			newR.AddAttrs(a)
+			return true
+		})
+		newR.AddAttrs(
+			slog.String("trace_id", spanCtx.TraceID().String()),
+			slog.String("span_id", spanCtx.SpanID().String()),
+		)
+		r = newR
+	}
+
+	return h.Handler.Handle(ctx, r)
+}
+
+func (h traceContextHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return traceContextHandler{Handler: h.Handler.WithAttrs(attrs)}
+}
+
+func (h traceContextHandler) WithGroup(name string) slog.Handler {
+	return traceContextHandler{Handler: h.Handler.WithGroup(name)}
+}
+
+// NewStdHandler returns a [slog.Handler] instance for the standard output.
+func NewStdHandler(level slog.Level, format string, fieldsPrefix string, enableGcpFields bool) (slog.Handler, error) {
+	// #nosec: G115
+	isTerminal := term.IsTerminal(int(os.Stdout.Fd()))
+
+	// Normalize the log format based on the output device.
+	if format == autoLoggingFormat {
+		if isTerminal {
+			format = textLoggingFormat
+		} else {
+			format = jsonLoggingFormat
+		}
+	}
+
+	opts := &slog.HandlerOptions{
+		Level: level,
+	}
+
+	opts.ReplaceAttr = func(groups []string, a slog.Attr) slog.Attr {
+		// Configure level encoding based on format and GCP settings.
+		if a.Key == slog.LevelKey {
+			l := a.Value.Any().(slog.Level)
+			switch {
+			case format == textLoggingFormat && isTerminal:
+				if enableGcpFields {
+					a.Value = slog.StringValue(gcpSeverityColorEncoder(l))
+				} else {
+					a.Value = slog.StringValue(levelToColor(l).Add(l.String()))
+				}
+			case enableGcpFields && format != textLoggingFormat:
+				a.Key = "severity"
+				a.Value = slog.StringValue(gcpSeverity(l))
+			default:
+				a.Value = slog.StringValue(strings.ToLower(l.String()))
+			}
+		}
+
+		if a.Key == slog.TimeKey {
+			if enableGcpFields && format != textLoggingFormat {
+				a.Key = "time"
+			} else {
+				a.Key = "ts"
+			}
+
+			if isTerminal {
+				a.Value = slog.StringValue(a.Value.Time().Local().Format("2006/01/02 15:04:05.000"))
+			} else if !enableGcpFields {
+				a.Value = slog.Float64Value(float64(a.Value.Time().UnixNano()) / 1e9)
+			}
+		}
+
+		if a.Key == slog.MessageKey {
+			if enableGcpFields && format != textLoggingFormat {
+				a.Key = "message"
+			} else {
+				a.Key = "msg"
+			}
+		}
+
+		return a
+	}
+
+	var handler slog.Handler
+	if format == textLoggingFormat {
+		handler = slog.NewTextHandler(os.Stderr, opts)
+	} else {
+		handler = slog.NewJSONHandler(os.Stderr, opts)
+	}
+
+	return traceContextHandler{Handler: handler}, nil
+}
+
+func gcpSeverityColorEncoder(l slog.Level) string {
+	severity := gcpSeverity(l)
+	c := levelToColor(l)
+	return c.Add(severity)
+}

pkg/gotenberg/internal/otel/doc.go

@@ -0,0 +1,8 @@
+// Package otel gathers initialization utilities for OpenTelemetry
+// instrumentation.
+//
+// This package has been significantly inspired by
+// https://github.com/lucavallin/gotel.
+//
+// See: https://opentelemetry.io/.
+package otel

pkg/gotenberg/internal/otel/otel.go

@@ -0,0 +1,166 @@
+package otel
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"sync/atomic"
+
+	"go.opentelemetry.io/contrib/bridges/otelslog"
+	"go.opentelemetry.io/contrib/exporters/autoexport"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/log/global"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/log"
+	"go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/resource"
+	"go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
+)
+
+// InitTracerProvider initializes the OpenTelemetry tracer provider.
+func InitTracerProvider(logger *slog.Logger, serviceName, serviceVersion string) (shutdown func(context.Context) error, err error) {
+	initOtelLogger(logger)
+
+	ctx := context.Background()
+	hostname, err := os.Hostname()
+	if err != nil {
+		return nil, fmt.Errorf("get hostname: %w", err)
+	}
+
+	res, err := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(serviceName),
+			semconv.ServiceVersion(serviceVersion),
+			semconv.HostName(hostname),
+		),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("merge resource: %w", err)
+	}
+
+	traceOpts := []trace.TracerProviderOption{
+		trace.WithResource(res),
+	}
+
+	traceExporter, err := autoexport.NewSpanExporter(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	if !autoexport.IsNoneSpanExporter(traceExporter) {
+		traceOpts = append(traceOpts, trace.WithBatcher(traceExporter))
+	}
+
+	traceProvider := trace.NewTracerProvider(traceOpts...)
+	otel.SetTracerProvider(traceProvider)
+
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		propagation.Baggage{},
+	))
+
+	return traceProvider.Shutdown, nil
+}
+
+// InitMeterProvider initializes the OpenTelemetry meter provider.
+func InitMeterProvider(logger *slog.Logger, serviceName, serviceVersion string) (shutdown func(context.Context) error, err error) {
+	initOtelLogger(logger)
+
+	ctx := context.Background()
+	hostname, err := os.Hostname()
+	if err != nil {
+		return nil, fmt.Errorf("get hostname: %w", err)
+	}
+
+	res, err := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(serviceName),
+			semconv.ServiceVersion(serviceVersion),
+			semconv.HostName(hostname),
+		),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("merge resource: %w", err)
+	}
+
+	metricOpts := []metric.Option{
+		metric.WithResource(res),
+	}
+
+	metricReader, err := autoexport.NewMetricReader(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	if !autoexport.IsNoneMetricReader(metricReader) {
+		metricOpts = append(metricOpts, metric.WithReader(metricReader))
+	}
+
+	meterProvider := metric.NewMeterProvider(metricOpts...)
+	otel.SetMeterProvider(meterProvider)
+
+	return meterProvider.Shutdown, nil
+}
+
+// InitLoggerProvider initializes the OpenTelemetry logger provider.
+func InitLoggerProvider(logger *slog.Logger, serviceName, serviceVersion string) (shutdown func(context.Context) error, handler slog.Handler, err error) {
+	initOtelLogger(logger)
+
+	ctx := context.Background()
+	hostname, err := os.Hostname()
+	if err != nil {
+		return nil, nil, fmt.Errorf("get hostname: %w", err)
+	}
+
+	res, err := resource.Merge(
+		resource.Default(),
+		resource.NewWithAttributes(
+			semconv.SchemaURL,
+			semconv.ServiceName(serviceName),
+			semconv.ServiceVersion(serviceVersion),
+			semconv.HostName(hostname),
+		),
+	)
+	if err != nil {
+		return nil, nil, fmt.Errorf("merge resource: %w", err)
+	}
+
+	logOpts := []log.LoggerProviderOption{
+		log.WithResource(res),
+	}
+
+	logExporter, err := autoexport.NewLogExporter(ctx)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if !autoexport.IsNoneLogExporter(logExporter) {
+		logOpts = append(logOpts, log.WithProcessor(log.NewBatchProcessor(logExporter)))
+	}
+
+	loggerProvider := log.NewLoggerProvider(logOpts...)
+	otelHandler := otelslog.NewHandler(serviceName, otelslog.WithLoggerProvider(loggerProvider))
+	global.SetLoggerProvider(loggerProvider)
+
+	return loggerProvider.Shutdown, otelHandler, nil
+}
+
+func initOtelLogger(logger *slog.Logger) {
+	if otlpLoggerInitialized.Load() {
+		return
+	}
+
+	otel.SetErrorHandler(otel.ErrorHandlerFunc(func(err error) {
+		logger.Error(err.Error())
+	}))
+
+	otlpLoggerInitialized.Store(true)
+}
+
+var otlpLoggerInitialized atomic.Bool