Logging

Logging for container deployments

The pdfRest API Toolkit Container emits structured JSON logs to standard output by default. Collect this output with your container platform's normal logging integration, then use the shared requestId UUID to find every record produced for one request.

Use the structured log reference when configuring a log processor, alert, or dashboard.

Request correlation ID

Each incoming request receives a UUID correlation ID. The same value appears as requestId in every request-scoped application and HTTP access record. Filter or group records by this field to trace one request from receipt through its final response. Operational records are not associated with a request and do not have a Correlation ID.

Formats and levels

Container images limit runtime verbosity to verbose. Requests for debug or silly therefore do not enable those levels in a container deployment.

Standard output and file logs

Standard output remains enabled in every configuration. File logging adds rotating files; it does not replace standard output.

Docker Compose

The default configuration needs no logging-specific environment variables:

services:
  pdfrest:
    image: pdfrest/pdf-api-toolkit:latest
    environment:
      - LICENSE_KEY=${LICENSE_KEY}

To retain additional rotating files, mount a host or managed volume at /logs:

services:
  pdfrest:
    image: pdfrest/pdf-api-toolkit:latest
    environment:
      - LICENSE_KEY=${LICENSE_KEY}
      - LOG_FILE_ENABLED=true
      - LOG_FILE_DIR=/logs
      - LOG_FILE_APP_NAME=server.log
      - LOG_FILE_HTTP_NAME=http-access.log
      - LOG_FILE_MAX_SIZE=10485760
      - LOG_FILE_MAX_FILES=5
    volumes:
      - pdfrest-logs:/logs

volumes:
  pdfrest-logs:

Kubernetes

Collect standard output with your cluster logging agent. When file retention is also required, mount an organization-managed persistent volume at /logs:

containers:
  - name: pdfrest
    image: pdfrest/pdf-api-toolkit:latest
    env:
      - name: LOG_FILE_ENABLED
        value: "true"
      - name: LOG_FILE_DIR
        value: /logs
    volumeMounts:
      - name: logs
        mountPath: /logs
volumes:
  - name: logs
    persistentVolumeClaim:
      claimName: pdfrest-logs

Sanitization

LOG_SANITIZATION controls protection applied at the log-output boundary. It accepts full, partial, and off, and defaults to partial.

Each unset override inherits LOG_SANITIZATION and accepts the same values:

Record shape options

LOG_AUDIT_NON_APPLICABLE_FIELDS controls fields that genuinely do not apply to a record. The default omit leaves them out; null emits them as JSON null. This setting does not change applicable data that cannot be resolved. Such values use explicit markers such as unknown or anonymous.

Troubleshooting

• An invalid log level, format, sanitization mode, file name, or file directory prevents the container from starting. Correct the value and restart it.
• Use your platform's container-log viewer for standard output. For mounted file logs, inspect the mounted volume from the host or storage service.
• Filter application and HTTP records on the same requestId UUID to trace one request across its lifecycle.

Structured log reference

Structured log format

With LOG_TYPE=json, the container emits JSON Lines: each log line is one JSON object. Configure ingestion systems to parse each line as JSON, then use eventType, requestId, status, outcome, and event-specific metadata for searches and alerts. Do not parse the optional human-readable message field.

Common fields

Request-scoped events carry a UUID requestId. Operational events are not tied to a request, so request-only fields are omitted by default or emitted as null when LOG_AUDIT_NON_APPLICABLE_FIELDS=null. A missing applicable value is not the same as a non-applicable field; it uses an explicit marker such as unknown or anonymous.

Examples

Successful request lifecycle event

{
  "level": "info",
  "eventType": "request.finish",
  "requestId": "0950b9bd-f046-4d3f-8ea3-d2894f1ae839",
  "actor": "anonymous",
  "sourceIp": "198.51.100.10",
  "serverName": "pdfrest-container",
  "serverIp": "192.0.2.20",
  "route": "/pdf-info",
  "method": "POST",
  "status": "succeeded",
  "outcome": "success",
  "durationMs": 47,
  "responseCode": 200,
  "timestamp": "2026-08-20T20:00:00.000Z"
}

Failed request lifecycle event

{
  "level": "error",
  "eventType": "request.finish",
  "requestId": "0950b9bd-f046-4d3f-8ea3-d2894f1ae839",
  "actor": "anonymous",
  "sourceIp": "198.51.100.10",
  "serverName": "pdfrest-container",
  "serverIp": "192.0.2.20",
  "route": "/pdf-info",
  "method": "POST",
  "status": "failed",
  "outcome": "failure",
  "durationMs": 12,
  "errorClass": "client_error",
  "responseCode": 400,
  "timestamp": "2026-08-20T20:00:01.000Z"
}

HTTP access event

{
  "level": "info",
  "message": "POST /pdf-info 200 42 - 0950b9bd-f046-4d3f-8ea3-d2894f1ae839 47.123 ms",
  "eventType": "http.request",
  "requestId": "0950b9bd-f046-4d3f-8ea3-d2894f1ae839",
  "actor": "anonymous",
  "sourceIp": "198.51.100.10",
  "serverName": "pdfrest-container",
  "serverIp": "192.0.2.20",
  "route": "/pdf-info",
  "method": "POST",
  "status": 200,
  "outcome": "success",
  "durationMs": 47.123,
  "responseSizeBytes": 42,
  "timestamp": "2026-08-20T20:00:00.000Z"
}

Operational event

{
  "level": "info",
  "eventType": "server.listen",
  "actor": "system",
  "serverName": "pdfrest-container",
  "serverIp": "192.0.2.20",
  "status": "started",
  "outcome": "pending",
  "port": 3000,
  "timestamp": "2026-08-20T19:59:55.000Z"
}

Event types

eventType is a stable, lowercase dotted identifier. The following families cover common Container events:

Event-specific metadata appears beside the common fields. For example, access records can include responseCode and responseSizeBytes; service events can include port. Consumers should preserve unrecognized top-level metadata so new event types remain useful without requiring a parser change.

Outcomes, errors, and sanitization

status preserves the event producer's state. outcome provides a small, consistent result vocabulary:

errorClass categorizes failures without requiring consumers to parse error text. Sanitization applies before JSON or text output: query values are removed in sanitized modes, secrets are masked, and customer content is summarized or omitted according to the configured policy. The timestamp is always emitted in UTC.