refactor(pdfengines): embeds => attachments

2026-08-12 02:12:15 +01:00 · 2026-03-08 15:49:09 +01:00
parent 7af3cd1ff5
commit cf9fd7eedc
92 changed files with 5763 additions and 3082 deletions
--- a/pkg/modules/api/api.go
+++ b/pkg/modules/api/api.go
@@ -4,8 +4,10 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log/slog"
 	"net"
 	"net/http"
+	"os"
 	"sort"
 	"strings"
 	"time"
@@ -15,7 +17,6 @@ import (
 	"github.com/labstack/echo/v4"
 	flag "github.com/spf13/pflag"
 	"go.uber.org/multierr"
-	"go.uber.org/zap"
 	"golang.org/x/net/http2"
 	"golang.org/x/sync/errgroup"

@@ -27,22 +28,25 @@ func init() {
 }

 // Api is a module that provides an HTTP server. Other modules may add routes,
-// middlewares or health checks.
+// middlewares, or health checks.
 type Api struct {
-	port                      int
-	bindIp                    string
-	tlsCertFile               string
-	tlsKeyFile                string
-	startTimeout              time.Duration
-	bodyLimit                 int64
-	timeout                   time.Duration
-	rootPath                  string
-	traceHeader               string
-	basicAuthUsername         string
-	basicAuthPassword         string
-	downloadFromCfg           downloadFromConfig
-	disableHealthCheckLogging bool
-	enableDebugRoute          bool
+	port                             int
+	bindIp                           string
+	tlsCertFile                      string
+	tlsKeyFile                       string
+	startTimeout                     time.Duration
+	bodyLimit                        int64
+	timeout                          time.Duration
+	rootPath                         string
+	basicAuthUsername                string
+	basicAuthPassword                string
+	correlationIdHeader              string
+	downloadFromCfg                  downloadFromConfig
+	disableHealthCheckRouteTelemetry bool
+	disableRootRouteTelemetry        bool
+	disableVersionRouteTelemetry     bool
+	disableDebugRouteTelemetry       bool
+	enableDebugRoute                 bool

 	routes              []Route
 	externalMiddlewares []Middleware
@@ -50,7 +54,7 @@ type Api struct {
 	readyFn             []func() error
 	asyncCounters       []AsynchronousCounter
 	fs                  *gotenberg.FileSystem
-	logger              *zap.Logger
+	logger              *slog.Logger
 	srv                 *echo.Echo
 }

@@ -80,9 +84,9 @@ type Route struct {
 	// Optional.
 	IsMultipart bool

-	// DisableLogging disables the logging for this route.
+	// DisableTelemetry disables the telemetry and logging for this route.
 	// Optional.
-	DisableLogging bool
+	DisableTelemetry bool

 	// Handler is the function that handles the request.
 	// Required.
@@ -118,29 +122,6 @@ const (

 // Middleware is a middleware that can be added to the [Api]'s middlewares
 // chain.
-//
-//	middleware := Middleware{
-//	  Handler: func() echo.MiddlewareFunc {
-//	    return func(next echo.HandlerFunc) echo.HandlerFunc {
-//	      return func(c echo.Context) error {
-//	        rootPath := c.Get("rootPath").(string)
-//	        healthURI := fmt.Sprintf("%shealth", rootPath)
-//
-//	        // Skip the middleware if health check URI.
-//	        if c.Request().RequestURI == healthURI {
-//	          // Call the next middleware in the chain.
-//	          return next(c)
-//	        }
-//
-//	        // Your middleware process.
-//	        // ...
-//
-//	        // Call the next middleware in the chain.
-//	        return next(c)
-//	      }
-//	    }
-//	  }(),
-//	}
 type Middleware struct {
 	// Stack tells in which stack the middleware should be located.
 	// Default to [DefaultStack].
@@ -190,14 +171,18 @@ func (a *Api) Descriptor() gotenberg.ModuleDescriptor {
 			fs.Duration("api-timeout", time.Duration(30)*time.Second, "Set the time limit for requests")
 			fs.String("api-body-limit", "", "Set the body limit for multipart/form-data requests - it accepts values like 5MB, 1GB, etc")
 			fs.String("api-root-path", "/", "Set the root path of the API - for service discovery via URL paths")
-			fs.String("api-trace-header", "Gotenberg-Trace", "Set the header name to use for identifying requests")
 			fs.Bool("api-enable-basic-auth", false, "Enable basic authentication - will look for the GOTENBERG_API_BASIC_AUTH_USERNAME and GOTENBERG_API_BASIC_AUTH_PASSWORD environment variables")
+			fs.String("api-correlation-id-header", "X-Correlation-ID", "Set the header name to use to set the correlation id in the logs")
 			fs.String("api-download-from-allow-list", "", "Set the allowed URLs for the download from feature using a regular expression")
 			fs.String("api-download-from-deny-list", "", "Set the denied URLs for the download from feature using a regular expression")
 			fs.Int("api-download-from-max-retry", 4, "Set the maximum number of retries for the download from feature")
 			fs.Bool("api-disable-download-from", false, "Disable the download from feature")
-			fs.Bool("api-disable-health-check-logging", false, "Disable health check logging")
+			fs.Bool("api-disable-health-check-route-telemetry", false, "Disable the health check route telemetry")
+			fs.Bool("api-disable-root-route-telemetry", false, "Disable the root route telemetry")
+			fs.Bool("api-disable-version-route-telemetry", false, "Disable the version route telemetry")
+			fs.Bool("api-disable-debug-route-telemetry", false, "Disable the debug route telemetry")
 			fs.Bool("api-enable-debug-route", false, "Enable the debug route")
+
 			return fs
 		}(),
 		New: func() gotenberg.Module { return new(Api) },
@@ -215,14 +200,17 @@ func (a *Api) Provision(ctx *gotenberg.Context) error {
 	a.timeout = flags.MustDuration("api-timeout")
 	a.bodyLimit = flags.MustHumanReadableBytes("api-body-limit")
 	a.rootPath = flags.MustString("api-root-path")
-	a.traceHeader = flags.MustString("api-trace-header")
+	a.correlationIdHeader = flags.MustString("api-correlation-id-header")
 	a.downloadFromCfg = downloadFromConfig{
 		allowList: flags.MustRegexp("api-download-from-allow-list"),
 		denyList:  flags.MustRegexp("api-download-from-deny-list"),
 		maxRetry:  flags.MustInt("api-download-from-max-retry"),
 		disable:   flags.MustBool("api-disable-download-from"),
 	}
-	a.disableHealthCheckLogging = flags.MustBool("api-disable-health-check-logging")
+	a.disableHealthCheckRouteTelemetry = flags.MustBool("api-disable-health-check-route-telemetry")
+	a.disableRootRouteTelemetry = flags.MustBool("api-disable-root-route-telemetry")
+	a.disableVersionRouteTelemetry = flags.MustBool("api-disable-version-route-telemetry")
+	a.disableDebugRouteTelemetry = flags.MustBool("api-disable-debug-route-telemetry")
 	a.enableDebugRoute = flags.MustBool("api-enable-debug-route")

 	// Port from env?
@@ -328,17 +316,7 @@ func (a *Api) Provision(ctx *gotenberg.Context) error {
 	}

 	// Logger.
-	loggerProvider, err := ctx.Module(new(gotenberg.LoggerProvider))
-	if err != nil {
-		return fmt.Errorf("get logger provider: %w", err)
-	}
-
-	logger, err := loggerProvider.(gotenberg.LoggerProvider).Logger(a)
-	if err != nil {
-		return fmt.Errorf("get logger: %w", err)
-	}
-
-	a.logger = logger
+	a.logger = gotenberg.Logger(a)

 	// File system.
 	a.fs = gotenberg.NewFileSystem(new(gotenberg.OsMkdirAll))
@@ -378,12 +356,6 @@ func (a *Api) Validate() error {
 		)
 	}

-	if len(strings.TrimSpace(a.traceHeader)) == 0 {
-		err = multierr.Append(err,
-			errors.New("trace header must not be empty"),
-		)
-	}
-
 	if err != nil {
 		return err
 	}
@@ -442,28 +414,48 @@ func (a *Api) Start() error {
 	a.srv.HTTPErrorHandler = httpErrorHandler()

 	// Let's prepare the modules' routes.
-	var disableLoggingForPaths []string
+	var disableTelemetryForPaths []string
 	for i, route := range a.routes {
 		a.routes[i].Path = strings.TrimPrefix(route.Path, "/")

-		if route.DisableLogging {
-			disableLoggingForPaths = append(disableLoggingForPaths, strings.TrimPrefix(route.Path, "/"))
+		if route.DisableTelemetry {
+			disableTelemetryForPaths = append(disableTelemetryForPaths, strings.TrimPrefix(route.Path, "/"))
 		}
 	}
-
-	// Check if the user wishes to add logging entries related to the health
-	// check route.
-	if a.disableHealthCheckLogging {
-		disableLoggingForPaths = append(disableLoggingForPaths, "health")
+	// Check if the user wishes to disable telemetry for system routes.
+	// Note: root path will be used as prefix in the underlying middlewares.
+	if a.disableHealthCheckRouteTelemetry {
+		disableTelemetryForPaths = append(disableTelemetryForPaths, "health")
 	}

+	if a.disableRootRouteTelemetry {
+		disableTelemetryForPaths = append(disableTelemetryForPaths, "")
+	}
+
+	if a.disableVersionRouteTelemetry {
+		disableTelemetryForPaths = append(disableTelemetryForPaths, "version")
+	}
+
+	if a.disableDebugRouteTelemetry {
+		disableTelemetryForPaths = append(disableTelemetryForPaths, "debug")
+	}
+
+	// Always disable telemetry for favicon.
+	disableTelemetryForPaths = append(disableTelemetryForPaths,
+		"favicon.ico",
+	)
+
 	// Add the API middlewares.
+	hostname, err := os.Hostname()
+	if err != nil {
+		return fmt.Errorf("get hostname: %w", err)
+	}
+
 	a.srv.Pre(
 		latencyMiddleware(),
 		rootPathMiddleware(a.rootPath),
-		traceMiddleware(a.traceHeader),
 		outputFilenameMiddleware(),
-		loggerMiddleware(a.logger, disableLoggingForPaths),
+		telemetryMiddleware(a.logger, hostname, a.correlationIdHeader, disableTelemetryForPaths),
 	)

 	// Add the modules' middlewares in their respective stacks.
@@ -583,7 +575,7 @@ func (a *Api) Start() error {
 		eg.Go(f)
 	}

-	err := eg.Wait()
+	err = eg.Wait()
 	if err != nil {
 		return fmt.Errorf("waiting for modules readiness: %w", err)
 	}
@@ -600,7 +592,8 @@ func (a *Api) Start() error {
 			err = a.srv.StartH2CServer(fmt.Sprintf("%s:%d", a.bindIp, a.port), server)
 		}
 		if !errors.Is(err, http.ErrServerClosed) {
-			a.logger.Fatal(err.Error())
+			a.logger.ErrorContext(context.Background(), err.Error())
+			os.Exit(1)
 		}
 	}()

@@ -627,12 +620,12 @@ func (a *Api) Stop(ctx context.Context) error {
 		case <-ctx.Done():
 			return a.srv.Shutdown(ctx)
 		default:
-			a.logger.Debug(fmt.Sprintf("%d asynchronous requests", count))
+			a.logger.DebugContext(ctx, fmt.Sprintf("%d asynchronous requests", count))
 			if count > 0 {
 				time.Sleep(1 * time.Second)
 				continue
 			}
-			a.logger.Debug("no more asynchronous requests, continue with shutdown")
+			a.logger.DebugContext(ctx, "no more asynchronous requests, continue with shutdown")
 			err := a.srv.Shutdown(ctx)
 			if err != nil {
 				return fmt.Errorf("shutdown: %w", err)
--- a/pkg/modules/api/context.go
+++ b/pkg/modules/api/context.go
@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log/slog"
 	"mime"
 	"mime/multipart"
 	"net/http"
@@ -19,11 +20,14 @@ import (
 	"github.com/hashicorp/go-retryablehttp"
 	"github.com/labstack/echo/v4"
 	"github.com/mholt/archives"
-	"go.uber.org/zap"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/text/unicode/norm"

 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
+	semconvutil "github.com/gotenberg/gotenberg/v8/pkg/gotenberg/semconv"
 )

 var (
@@ -36,7 +40,7 @@ var (
 	ErrOutOfBoundsOutputPath = errors.New("output path is not within context's working directory")
 )

-// Context is the request context for a "multipart/form-data" requests.
+// Context is the request context for a "multipart/form-data" request.
 type Context struct {
 	dirPath      string
 	values       map[string][]string
@@ -45,7 +49,7 @@ type Context struct {
 	outputPaths  []string
 	cancelled    bool

-	logger     *zap.Logger
+	logger     *slog.Logger
 	echoCtx    echo.Context
 	mkdirAll   gotenberg.MkdirAll
 	pathRename gotenberg.PathRename
@@ -81,12 +85,12 @@ type downloadFrom struct {
 	// ExtraHttpHeaders are the HTTP headers to send alongside.
 	ExtraHttpHeaders map[string]string `json:"extraHttpHeaders"`

-	// Download as embed file
-	Embedded bool `json:"embedded"`
+	// Download as an attachment file.
+	Attachment bool `json:"attachment"`
 }

 // newContext returns a [Context] by parsing a "multipart/form-data" request.
-func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSystem, timeout time.Duration, bodyLimit int64, downloadFromCfg downloadFromConfig, traceHeader, trace string) (*Context, context.CancelFunc, error) {
+func newContext(echoCtx echo.Context, logger *slog.Logger, fs *gotenberg.FileSystem, timeout time.Duration, bodyLimit int64, downloadFromCfg downloadFromConfig) (*Context, context.CancelFunc, error) {
 	processCtx, processCancel := context.WithTimeout(echoCtx.Request().Context(), timeout)

 	// We want to make sure the multipart/form-data does not exceed a given
@@ -131,12 +135,12 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst

 			err := os.RemoveAll(ctx.dirPath)
 			if err != nil {
-				ctx.logger.Error(fmt.Sprintf("remove context's working directory: %s", err))
+				ctx.logger.ErrorContext(ctx, fmt.Sprintf("remove context's working directory: %s", err))

 				return
 			}

-			ctx.logger.Debug(fmt.Sprintf("'%s' context's working directory removed", ctx.dirPath))
+			ctx.logger.DebugContext(ctx, fmt.Sprintf("'%s' context's working directory removed", ctx.dirPath))
 			ctx.cancelled = true
 		}
 	}()
@@ -224,9 +228,9 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 					return fmt.Errorf("filter URL: %w", err)
 				}

-				logger.Debug(fmt.Sprintf("download file from '%s'", dl.Url))
+				logger.DebugContext(ctx, fmt.Sprintf("download file from '%s'", dl.Url))

-				req, err := retryablehttp.NewRequest(http.MethodGet, dl.Url, nil)
+				req, err := retryablehttp.NewRequestWithContext(ctx, http.MethodGet, dl.Url, nil)
 				if err != nil {
 					return fmt.Errorf("create request to '%s': %w", dl.Url, err)
 				}
@@ -235,7 +239,20 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 				for key, value := range dl.ExtraHttpHeaders {
 					req.Header.Set(key, value)
 				}
-				req.Header.Set(traceHeader, trace)
+				req.Header.Set(echoCtx.Get("correlationIdHeader").(string), echoCtx.Get("correlationId").(string))
+
+				// OpenTelemetry.
+				meter := gotenberg.Meter()
+				semconvClient := semconvutil.NewHTTPClient(meter)
+
+				tracer := gotenberg.Tracer()
+				traceCtx, span := tracer.Start(ctx, fmt.Sprintf("%s Download From", req.Method),
+					trace.WithSpanKind(trace.SpanKindClient),
+					trace.WithAttributes(semconvClient.RequestTraceAttrs(req.Request)...),
+				)
+				defer span.End()
+
+				otel.GetTextMapPropagator().Inject(traceCtx, propagation.HeaderCarrier(req.Header))

 				client := &retryablehttp.Client{
 					HTTPClient: &http.Client{
@@ -244,22 +261,27 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 					RetryMax:     downloadFromCfg.maxRetry,
 					RetryWaitMin: time.Duration(1) * time.Second,
 					RetryWaitMax: time.Until(deadline),
-					Logger:       gotenberg.NewLeveledLogger(logger),
+					Logger:       gotenberg.NewLeveledLogger(logger).WithContext(ctx),
 					CheckRetry:   retryablehttp.DefaultRetryPolicy,
 					Backoff:      retryablehttp.DefaultBackoff,
 				}

 				resp, err := client.Do(req)
 				if err != nil {
+					span.RecordError(err)
+					span.SetStatus(semconvClient.Status(0))
 					return WrapError(
 						fmt.Errorf("download file from to '%s': %w", dl.Url, err),
 						NewSentinelHttpError(http.StatusBadRequest, fmt.Sprintf("Unable to download file from '%s': %s", dl.Url, err)),
 					)
 				}
+
+				span.SetAttributes(semconvClient.ResponseTraceAttrs(resp)...)
+				span.SetStatus(semconvClient.Status(resp.StatusCode))
 				defer func() {
 					err := resp.Body.Close()
 					if err != nil {
-						logger.Error(fmt.Sprintf("close response body from '%s': %s", dl.Url, err))
+						logger.ErrorContext(ctx, fmt.Sprintf("close response body from '%s': %s", dl.Url, err))
 					}
 				}()

@@ -301,7 +323,7 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 				// normalized.
 				// See: https://github.com/gotenberg/gotenberg/issues/662.
 				filename = norm.NFC.String(filepath.Base(filename))
-				path := fmt.Sprintf("%s/%s", ctx.dirPath, filename)
+				path := fmt.Sprintf("%s/%s", dirPath, filename)

 				out, err := os.Create(path)
 				if err != nil {
@@ -310,7 +332,7 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 				defer func() {
 					err := out.Close()
 					if err != nil {
-						logger.Error(fmt.Sprintf("close local file: %s", err))
+						logger.ErrorContext(ctx, fmt.Sprintf("close local file: %s", err))
 					}
 				}()

@@ -323,8 +345,8 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 				}

 				ctx.files[filename] = path
-				if dl.Embedded {
-					ctx.filesByField[EmbedsFormField] = append(ctx.filesByField[EmbedsFormField], path)
+				if dl.Attachment {
+					ctx.filesByField[AttachmentsFormField] = append(ctx.filesByField[AttachmentsFormField], path)
 				}

 				return nil
@@ -346,7 +368,7 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 		defer func() {
 			err := in.Close()
 			if err != nil {
-				logger.Error(fmt.Sprintf("close file header: %s", err))
+				logger.ErrorContext(ctx, fmt.Sprintf("close file header: %s", err))
 			}
 		}()

@@ -366,7 +388,7 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 		defer func() {
 			err := out.Close()
 			if err != nil {
-				logger.Error(fmt.Sprintf("close local file: %s", err))
+				logger.ErrorContext(ctx, fmt.Sprintf("close local file: %s", err))
 			}
 		}()

@@ -394,10 +416,10 @@ func newContext(echoCtx echo.Context, logger *zap.Logger, fs *gotenberg.FileSyst
 		}
 	}

-	ctx.Log().Debug(fmt.Sprintf("form fields: %+v", ctx.values))
-	ctx.Log().Debug(fmt.Sprintf("form files: %+v", ctx.files))
-	ctx.Log().Debug(fmt.Sprintf("form files by field: %+v", ctx.filesByField))
-	ctx.Log().Debug(fmt.Sprintf("total bytes: %d", totalBytesRead.Load()))
+	ctx.Log().DebugContext(ctx, fmt.Sprintf("form fields: %+v", ctx.values))
+	ctx.Log().DebugContext(ctx, fmt.Sprintf("form files: %+v", ctx.files))
+	ctx.Log().DebugContext(ctx, fmt.Sprintf("form files by field: %+v", ctx.filesByField))
+	ctx.Log().DebugContext(ctx, fmt.Sprintf("total bytes: %d", totalBytesRead.Load()))

 	return ctx, cancel, err
 }
@@ -444,7 +466,7 @@ func (ctx *Context) CreateSubDirectory(dirName string) (string, error) {
 // Rename is just a wrapper around [os.Rename], as we need to mock this
 // behavior in our tests.
 func (ctx *Context) Rename(oldpath, newpath string) error {
-	ctx.Log().Debug(fmt.Sprintf("rename %s to %s", oldpath, newpath))
+	ctx.Log().DebugContext(ctx, fmt.Sprintf("rename %s to %s", oldpath, newpath))
 	err := ctx.pathRename.Rename(oldpath, newpath)
 	if err != nil {
 		return fmt.Errorf("rename path: %w", err)
@@ -470,8 +492,8 @@ func (ctx *Context) AddOutputPaths(paths ...string) error {
 	return nil
 }

-// Log returns the context [zap.Logger].
-func (ctx *Context) Log() *zap.Logger {
+// Log returns the context [slog.Logger].
+func (ctx *Context) Log() *slog.Logger {
 	return ctx.logger
 }

@@ -487,7 +509,7 @@ func (ctx *Context) BuildOutputFile() (string, error) {
 	}

 	if len(ctx.outputPaths) == 1 {
-		ctx.logger.Debug(fmt.Sprintf("only one output file '%s', skip archive creation", ctx.outputPaths[0]))
+		ctx.logger.DebugContext(ctx, fmt.Sprintf("only one output file '%s', skip archive creation", ctx.outputPaths[0]))
 		return ctx.outputPaths[0], nil
 	}

@@ -510,7 +532,7 @@ func (ctx *Context) BuildOutputFile() (string, error) {
 	defer func(out *os.File) {
 		err := out.Close()
 		if err != nil {
-			ctx.logger.Error(fmt.Sprintf("close zip file: %s", err))
+			ctx.logger.ErrorContext(ctx, fmt.Sprintf("close zip file: %s", err))
 		}
 	}(out)

@@ -519,7 +541,7 @@ func (ctx *Context) BuildOutputFile() (string, error) {
 		return "", fmt.Errorf("archive output files: %w", err)
 	}

-	ctx.logger.Debug(fmt.Sprintf("archive '%s' created", archivePath))
+	ctx.logger.DebugContext(ctx, fmt.Sprintf("archive '%s' created", archivePath))

 	return archivePath, nil
 }
--- a/pkg/modules/api/context_test.go
+++ b/pkg/modules/api/context_test.go
@@ -3,14 +3,15 @@ package api
 import (
 	"bytes"
 	"context"
+	"log/slog"
 	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
+	"os"
 	"testing"
 	"time"

 	"github.com/labstack/echo/v4"
-	"go.uber.org/zap"

 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
@@ -35,14 +36,14 @@ func TestNewContext_Cancellation(t *testing.T) {
 	rec := httptest.NewRecorder()
 	c := e.NewContext(req, rec)

-	logger := zap.NewNop()
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
 	fs := gotenberg.NewFileSystem(new(gotenberg.OsMkdirAll))
 	timeout := time.Duration(10) * time.Second
 	downloadFromCfg := downloadFromConfig{
 		disable: true,
 	}

-	ctx, cancel, err := newContext(c, logger, fs, timeout, 0, downloadFromCfg, "trace", "trace")
+	ctx, cancel, err := newContext(c, logger, fs, timeout, 0, downloadFromCfg)
 	if err != nil {
 		t.Fatalf("expected no error from newContext, got: %v", err)
 	}
--- a/pkg/modules/api/formdata.go
+++ b/pkg/modules/api/formdata.go
@@ -17,9 +17,9 @@ import (
 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )

-// EmbedsFormField represents the form field name for embedding files.
+// AttachmentsFormField represents the form field name for attaching files.
 const (
-	EmbedsFormField string = "embeds"
+	AttachmentsFormField string = "attachments"
 )

 // FormData is a helper for validating and hydrating values from a
@@ -365,20 +365,20 @@ func (form *FormData) Paths(extensions []string, target *[]string) *FormData {
 	return form.paths(extensions, target)
 }

-// Embeds binds the absolute paths of form data files that should be
-// embedded in the PDF. Only files uploaded with the "embeds" field name
+// Attachments binds the absolute paths of form data files that should be
+// attached in the PDF. Only files uploaded with the "attachments" field name
 // will be included.
 //
-//	var embeds []string
+//	var attachments []string
 //
-//	ctx.FormData().Embeds(&embeds)
-func (form *FormData) Embeds(target *[]string) *FormData {
+//	ctx.FormData().Attachments(&attachments)
+func (form *FormData) Attachments(target *[]string) *FormData {
 	if form.errors != nil {
 		return form
 	}

-	// Get files from the "embeds" field
-	if paths, ok := form.filesByField[EmbedsFormField]; ok {
+	// Get files from the "attachments" field
+	if paths, ok := form.filesByField[AttachmentsFormField]; ok {
 		*target = append(*target, paths...)
 	}

@@ -408,12 +408,12 @@ func (form *FormData) MandatoryPaths(extensions []string, target *[]string) *For

 // paths bind the absolute paths of form data files, according to a list of
 // file extensions, to a string slice variable.
-// embeds are excluded.
+// attachments are excluded.
 func (form *FormData) paths(extensions []string, target *[]string) *FormData {
-	embeds, ok := form.filesByField[EmbedsFormField]
+	attachments, ok := form.filesByField[AttachmentsFormField]

 	for filename, path := range form.files {
-		if ok && slices.Contains(embeds, path) {
+		if ok && slices.Contains(attachments, path) {
 			continue
 		}

--- a/pkg/modules/api/formdata_test.go
+++ b/pkg/modules/api/formdata_test.go
@@ -1613,15 +1613,15 @@ func TestFormData_Paths(t *testing.T) {
 			expectCount: 2,
 		},
 		{
-			scenario: "files except embeds",
+			scenario: "files except attachments",
 			form: &FormData{
 				files: map[string]string{
-					"foo.pdf":     "/foo.pdf",
-					"embed_1.pdf": "/embed_1.pdf",
-					"embed_2.xml": "/embed_2.xml",
+					"foo.pdf":           "/foo.pdf",
+					"attachments_1.pdf": "/attachments_1.pdf",
+					"attachments_2.xml": "/attachments_2.xml",
 				},
 				filesByField: map[string][]string{
-					"embeds": {"/embed_1.pdf", "/embed_2.xml"},
+					"attachments": {"/attachments_1.pdf", "/attachments_2.xml"},
 				},
 			},
 			extensions: []string{".pdf"},
@@ -1759,7 +1759,7 @@ func TestFormData_mustAssign(t *testing.T) {
 	form.mustAssign("foo", "foo", &target)
 }

-func TestFormData_Embeds(t *testing.T) {
+func TestFormData_Attachments(t *testing.T) {
 	expected := []string{"/bar.xml", "/baz.xml"}

 	var actual []string
@@ -1770,13 +1770,13 @@ func TestFormData_Embeds(t *testing.T) {
 			"baz.xml": "/baz.xml",
 		},
 		filesByField: map[string][]string{
-			"embeds": {"/bar.xml", "/baz.xml"},
+			"attachments": {"/bar.xml", "/baz.xml"},
 		},
 	}
-	form.Embeds(&actual)
+	form.Attachments(&actual)

 	if len(actual) != len(expected) {
-		t.Errorf("expected %d embeds but got %d", len(expected), len(actual))
+		t.Errorf("expected %d attachments but got %d", len(expected), len(actual))
 	}

 	if !reflect.DeepEqual(actual, expected) {
--- a/pkg/modules/api/middlewares.go
+++ b/pkg/modules/api/middlewares.go
@@ -5,6 +5,8 @@ import (
 	"crypto/subtle"
 	"errors"
 	"fmt"
+	"io"
+	"log/slog"
 	"net/http"
 	"path/filepath"
 	"strings"
@@ -13,9 +15,13 @@ import (
 	"github.com/google/uuid"
 	"github.com/labstack/echo/v4"
 	"github.com/labstack/echo/v4/middleware"
-	"go.uber.org/zap"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"

 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
+	semconvutil "github.com/gotenberg/gotenberg/v8/pkg/gotenberg/semconv"
 )

 var (
@@ -79,14 +85,14 @@ func ParseError(err error) (int, string) {
 // returns a response as "text/plain; charset=UTF-8".
 func httpErrorHandler() echo.HTTPErrorHandler {
 	return func(err error, c echo.Context) {
-		logger := c.Get("logger").(*zap.Logger)
+		logger := c.Get("logger").(*slog.Logger)
 		status, message := ParseError(err)

 		c.Response().Header().Add(echo.HeaderContentType, echo.MIMETextPlainCharsetUTF8)

 		err = c.String(status, message)
 		if err != nil {
-			logger.Error(fmt.Sprintf("send error response: %s", err.Error()))
+			logger.ErrorContext(c.Request().Context(), fmt.Sprintf("send error response: %s", err.Error()))
 		}
 	}
 }
@@ -130,32 +136,6 @@ func rootPathMiddleware(rootPath string) echo.MiddlewareFunc {
 	}
 }

-// traceMiddleware sets the request identifier in the [echo.Context] under
-// "trace". Its value is either retrieved from the trace header or generated if
-// the header is not present / its value is empty.
-//
-//	trace := c.Get("trace").(string)
-//	traceHeader := c.Get("traceHeader").(string).
-func traceMiddleware(header string) echo.MiddlewareFunc {
-	return func(next echo.HandlerFunc) echo.HandlerFunc {
-		return func(c echo.Context) error {
-			// Get or create the request identifier.
-			trace := c.Request().Header.Get(header)
-
-			if trace == "" {
-				trace = uuid.New().String()
-			}
-
-			c.Set("trace", trace)
-			c.Set("traceHeader", header)
-			c.Response().Header().Add(header, trace)
-
-			// Call the next middleware in the chain.
-			return next(c)
-		}
-	}
-}
-
 // outputFilenameMiddleware sets the output filename in the [echo.Context]
 // under "outputFilename".
 //
@@ -175,59 +155,28 @@ func outputFilenameMiddleware() echo.MiddlewareFunc {
 	}
 }

-// loggerMiddleware sets the logger in the [echo.Context] under "logger" and
-// logs a synchronous request result.
+// telemetryMiddleware manages telemetry. It sets the correlation ID in the
+// [echo.Context] under "correlationId".
 //
-//	logger := c.Get("logger").(*zap.Logger)
-func loggerMiddleware(logger *zap.Logger, disableLoggingForPaths []string) echo.MiddlewareFunc {
+//	correlationIdHeader := c.Get("correlationIdHeader").(string)
+//	correlationId := c.Get("correlationId").(string)
+func telemetryMiddleware(logger *slog.Logger, serverName, correlationIdHeader string, disableTelemetryForPaths []string) echo.MiddlewareFunc {
+	meter := gotenberg.Meter()
+	semconvSrv := semconvutil.NewHTTPServer(meter)
+
 	return func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c echo.Context) error {
 			startTime := c.Get("startTime").(time.Time)
-			trace := c.Get("trace").(string)
 			rootPath := c.Get("rootPath").(string)

-			// Create the application logger and add it to our locals.
-			appLogger := logger.
-				With(zap.String("log_type", "application")).
-				With(zap.String("trace", trace))
+			request := c.Request()
+			savedCtx := request.Context()
+			defer func() {
+				request = request.WithContext(savedCtx)
+				c.SetRequest(request)
+			}()

-			c.Set("logger", appLogger.Named(func() string {
-				return strings.ReplaceAll(
-					strings.ReplaceAll(c.Request().URL.Path, rootPath, ""),
-					"/",
-					"",
-				)
-			}()))
-
-			// Call the next middleware in the chain.
-			err := next(c)
-			if err != nil {
-				c.Error(err)
-			}
-
-			// Create the access logger.
-			accessLogger := logger.
-				With(zap.String("log_type", "access")).
-				With(zap.String("trace", trace))
-
-			for _, path := range disableLoggingForPaths {
-				URI := fmt.Sprintf("%s%s", rootPath, path)
-
-				if c.Request().RequestURI == URI {
-					return nil
-				}
-			}
-
-			// Last piece for calculating the latency.
-			finishTime := time.Now()
-
-			// Now, let's log!
-			fields := make([]zap.Field, 12)
-			fields[0] = zap.String("remote_ip", c.RealIP())
-			fields[1] = zap.String("host", c.Request().Host)
-			fields[2] = zap.String("uri", c.Request().RequestURI)
-			fields[3] = zap.String("method", c.Request().Method)
-			fields[4] = zap.String("path", func() string {
+			routePath := func() string {
 				path := c.Request().URL.Path

 				if path == "" {
@@ -235,21 +184,127 @@ func loggerMiddleware(logger *zap.Logger, disableLoggingForPaths []string) echo.
 				}

 				return path
-			}())
-			fields[5] = zap.String("referer", c.Request().Referer())
-			fields[6] = zap.String("user_agent", c.Request().UserAgent())
-			fields[7] = zap.Int("status", c.Response().Status)
-			fields[8] = zap.Int64("latency", int64(finishTime.Sub(startTime)))
-			fields[9] = zap.String("latency_human", finishTime.Sub(startTime).String())
-			fields[10] = zap.Int64("bytes_in", c.Request().ContentLength)
-			fields[11] = zap.Int64("bytes_out", c.Response().Size)
+			}()
+
+			// Evaluate if we should skip telemetry for this path.
+			skipTelemetry := false
+			for _, path := range disableTelemetryForPaths {
+				URI := fmt.Sprintf("%s%s", rootPath, path)
+				if c.Request().RequestURI == URI {
+					skipTelemetry = true
+					break
+				}
+			}
+
+			if skipTelemetry {
+				c.Set("logger", slog.New(slog.NewJSONHandler(io.Discard, nil)))
+
+				err := next(c)
+				if err != nil {
+					c.Error(err)
+				}
+				return nil
+			}
+
+			correlationId := request.Header.Get(correlationIdHeader)
+			if correlationId == "" {
+				correlationId = uuid.NewString()
+			}
+			c.Set("correlationIdHeader", correlationIdHeader)
+			c.Set("correlationId", correlationId)
+
+			ctx := otel.GetTextMapPropagator().Extract(savedCtx, propagation.HeaderCarrier(request.Header))
+
+			rAttr := semconvSrv.Route(routePath)
+			opts := []trace.SpanStartOption{
+				trace.WithAttributes(
+					semconvSrv.RequestTraceAttrs(serverName, request, semconvutil.RequestTraceAttrsOpts{})...,
+				),
+				trace.WithSpanKind(trace.SpanKindServer),
+				trace.WithAttributes(rAttr),
+			}
+			spanName := strings.ToUpper(c.Request().Method) + " " + routePath
+
+			tracer := gotenberg.Tracer()
+			ctx, span := tracer.Start(ctx, spanName, opts...)
+			defer span.End()
+
+			otel.GetTextMapPropagator().Inject(ctx, propagation.HeaderCarrier(c.Response().Header()))
+
+			c.Response().Header().Set(correlationIdHeader, correlationId)
+			c.SetRequest(c.Request().WithContext(ctx))
+
+			appLogger := logger.
+				With(slog.String("log_type", "application")).
+				With(slog.String("correlation_id", correlationId))
+
+			loggerName := strings.ReplaceAll(
+				strings.ReplaceAll(c.Request().URL.Path, rootPath, ""),
+				"/",
+				"",
+			)
+
+			c.Set("logger", appLogger.With(slog.String("logger", loggerName)))
+
+			// Call the next middleware in the chain.
+			err := next(c)
+			finishTime := time.Now()
+
+			status := c.Response().Status
+			if err != nil {
+				parsedStatus, _ := ParseError(err)
+				status = parsedStatus
+
+				span.SetAttributes(attribute.String("error", err.Error()))
+				c.Error(err)
+			}
+
+			span.SetStatus(semconvSrv.Status(status))
+			span.SetAttributes(semconvSrv.ResponseTraceAttrs(semconvutil.ResponseTelemetry{
+				StatusCode: status,
+				WriteBytes: c.Response().Size,
+			})...)
+
+			accessLogger := logger.
+				With(slog.String("log_type", "access")).
+				With(slog.String("correlation_id", correlationId)).
+				With(slog.String("remote_ip", c.RealIP())).
+				With(slog.String("host", c.Request().Host)).
+				With(slog.String("uri", c.Request().RequestURI)).
+				With(slog.String("method", c.Request().Method)).
+				With(slog.String("path", routePath)).
+				With(slog.String("referer", c.Request().Referer())).
+				With(slog.String("user_agent", c.Request().UserAgent())).
+				With(slog.Int("status", c.Response().Status)).
+				With(slog.Int64("latency", int64(finishTime.Sub(startTime)))).
+				With(slog.String("latency_human", finishTime.Sub(startTime).String())).
+				With(slog.Int64("bytes_in", c.Request().ContentLength)).
+				With(slog.Int64("bytes_out", c.Response().Size))

 			if err != nil {
-				accessLogger.Error(err.Error(), fields...)
+				accessLogger.ErrorContext(ctx, err.Error())
 			} else {
-				accessLogger.Info("request handled", fields...)
+				accessLogger.InfoContext(ctx, "request handled")
 			}

+			additionalAttributes := []attribute.KeyValue{
+				semconvSrv.Route(routePath),
+			}
+
+			semconvSrv.RecordMetrics(ctx, semconvutil.ServerMetricData{
+				ServerName:   serverName,
+				ResponseSize: c.Response().Size,
+				MetricAttributes: semconvutil.MetricAttributes{
+					Req:                  request,
+					StatusCode:           status,
+					AdditionalAttributes: additionalAttributes,
+				},
+				MetricData: semconvutil.MetricData{
+					RequestSize: request.ContentLength,
+					ElapsedTime: float64(time.Since(startTime)) / float64(time.Millisecond),
+				},
+			})
+
 			return nil
 		}
 	}
@@ -276,13 +331,11 @@ func basicAuthMiddleware(username, password string) echo.MiddlewareFunc {
 func contextMiddleware(fs *gotenberg.FileSystem, timeout time.Duration, bodyLimit int64, downloadFromCfg downloadFromConfig) echo.MiddlewareFunc {
 	return func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c echo.Context) error {
-			logger := c.Get("logger").(*zap.Logger)
-			traceHeader := c.Get("traceHeader").(string)
-			trace := c.Get("trace").(string)
+			logger := c.Get("logger").(*slog.Logger)

 			// We create a context with a timeout so that underlying processes are
 			// able to stop early and correctly handle a timeout scenario.
-			ctx, cancel, err := newContext(c, logger, fs, timeout, bodyLimit, downloadFromCfg, traceHeader, trace)
+			ctx, cancel, err := newContext(c, logger, fs, timeout, bodyLimit, downloadFromCfg)
 			if err != nil {
 				cancel()

@@ -336,7 +389,7 @@ func contextMiddleware(fs *gotenberg.FileSystem, timeout time.Duration, bodyLimi
 func hardTimeoutMiddleware(hardTimeout time.Duration) echo.MiddlewareFunc {
 	return func(next echo.HandlerFunc) echo.HandlerFunc {
 		return func(c echo.Context) error {
-			logger := c.Get("logger").(*zap.Logger)
+			logger := c.Get("logger").(*slog.Logger)

 			// Define a hard timeout if the route handler fails to timeout as
 			// expected.
@@ -353,7 +406,7 @@ func hardTimeoutMiddleware(hardTimeout time.Duration) echo.MiddlewareFunc {
 				// This deferred function allows us to recover from such scenarios.
 				defer func() {
 					if r := recover(); r != nil {
-						logger.Debug(fmt.Sprintf("recovering from a panic (possible cause being a hard timeout): %s", r))
+						logger.DebugContext(hardTimeoutCtx, fmt.Sprintf("recovering from a panic (possible cause being a hard timeout): %s", r))
 					}
 				}()

@@ -365,7 +418,7 @@ func hardTimeoutMiddleware(hardTimeout time.Duration) echo.MiddlewareFunc {
 			case err := <-errChan:
 				return err
 			case <-hardTimeoutCtx.Done():
-				logger.Debug("hard timeout as the route handler did not timeout as expected")
+				logger.DebugContext(hardTimeoutCtx, "hard timeout as the route handler did not timeout as expected")

 				return fmt.Errorf("hard timeout: %w", hardTimeoutCtx.Err())
 			}
--- a/pkg/modules/api/mocks.go
+++ b/pkg/modules/api/mocks.go
@@ -1,9 +1,10 @@
 package api

 import (
+	"log/slog"
+
 	"github.com/alexliesenfeld/health"
 	"github.com/labstack/echo/v4"
-	"go.uber.org/zap"

 	"github.com/gotenberg/gotenberg/v8/pkg/gotenberg"
 )
@@ -73,8 +74,8 @@ func (ctx *ContextMock) OutputPaths() []string {
 // SetLogger sets the logger.
 //
 //	ctx := &api.ContextMock{Context: &api.Context{}}
-//	ctx.SetLogger(zap.NewNop())
-func (ctx *ContextMock) SetLogger(logger *zap.Logger) {
+//	ctx.SetLogger(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
+func (ctx *ContextMock) SetLogger(logger *slog.Logger) {
 	ctx.logger = logger
 }