Our Windows print service: installation, configuration, printing, the window, the command line and monitoring.

VeloxFactory does not talk to printers directly. A companion Windows application, the VeloxFactory Print Service, runs on any machine that has the target printers installed. It receives print tasks from VeloxFactory, prints the PDF on the right printer and reports the result back. Both sides communicate only over the VeloxFactory REST API and the WebSocket server (Laravel Reverb). There is no shared database and no shared file system.

This chapter describes version 2.0.

At a glance

How it works

VeloxFactory                               Print Service (Windows)
------------                               -----------------------
Print task created  -- WebSocket event -->  Receiver (WebSocket / poll)
                    <-- GET task + PDF ---  Journal: known task? skip
                                            Worker -> printer lock -> PDFium -> Windows spooler
                    <-- set-printed -------  Outbox (retried until delivered)
                    <-- set-status error --  on permanent failures

1. Receive. A new print task triggers the WebSocket event report-print-task.created on the private channel private-report-print-tasks. The event only carries the task id and the broadcast id. In addition, the service polls the pending tasks of its broadcast ids (details in Receiving and processing print tasks).
2. Fetch. The service loads the task including the PDF (withMedia=true). The printer machine therefore needs HTTP access to VeloxFactory, not only WebSocket access.
3. Deduplicate. The job journal decides whether the task is new. Known tasks are skipped.
4. Print. A worker takes the task, waits for the printer if another job is running on it, checks the Windows queue (offline, paper out) and prints. Transient problems are retried.
5. Confirm. Success is written to the outbox first and then sent with PATCH /api/v1/report-print-task/{id}/set-printed. If VeloxFactory is unreachable, the outbox retries until it succeeds. Permanent failures are reported with set-status and a categorised error message.

Operating modes

A named mutex per instance makes sure only one engine runs. The window detects a running headless engine automatically and switches to monitor mode.

In this chapter

The Print Service has no installer. The program is delivered as a git repository that contains only the released build. Updates are a git checkout, driven by a script that stops the service gracefully first. Configuration, token, job journal and logs live in a separate data folder and survive every update.

Requirements

Folder layout

C:\kiwisoftware\VeloxPrint\
  app\          clone of the release repository, program only, updated by update.ps1
    bin\        kiwisoftware.VeloxFactory.PrintService.App.exe and its libraries
    update.ps1
    README.md
  data\         created by the app, never part of git
    config.json     configuration without token
    secrets.json    API token, encrypted
    state.db        job journal, outbox, statistics, log buffer, engine status (SQLite)
    logs\           rolling log files

Where the data folder is:

1. --config <path> sets it explicitly: all files of the instance live next to that configuration file.
2. If the program runs from a folder named app or below it, the data folder is data next to that app folder.
3. Otherwise it is %ProgramData%\kiwisoftware\VeloxPrint\.

The first start with administrator rights creates the data folder and sets these permissions. Setting up the scheduled task adds the service account.

First installation

1. Create the service account

The scheduled task runs under its own account. It must exist before the task is set up, the Print Service does not create it. PowerShell as administrator:

$pw = Read-Host -AsSecureString "Password"
New-LocalUser -Name "svc-veloxprint" -Password $pw -FullName "VeloxFactory Print Service" `
  -Description "Service account VeloxFactory Print Service" -PasswordNeverExpires -UserMayNotChangePassword

1. Do not add the account to the Administrators group, the standard Users group is enough.
2. Use -PasswordNeverExpires. An expired password stops the task until it is set up again.
3. For printers on a print server in a domain, use a domain account (DOMAIN\svc-veloxprint) instead. Only a domain account can authenticate at the print server.
4. Do not use SYSTEM. It accesses print servers with the computer account, shares often refuse that.

2. Clone the release

PowerShell as administrator:

New-Item -ItemType Directory C:\kiwisoftware\VeloxPrint
git clone https://git.fischernetz.xyz/bfischer/veloxfactory-printservice-release.git C:\kiwisoftware\VeloxPrint\app

3. Configure

1. Start C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe as administrator. The first elevated start creates data\ and restricts its permissions.
2. Settings → Connection: base URL of VeloxFactory and API token. Test connection checks reachability, token, channel authorization, WebSocket handshake and rate limit headers.
3. Settings → WebSocket (Reverb): host, port, scheme and app key of your Reverb server.
4. Settings → Receiving: the broadcast ids of this site.
5. Save. See the Configuration reference for every setting.

4. Set up the scheduled task

Settings → Operation → Set up scheduled task, enter the service account (.\svc-veloxprint for a local account) and its password. Alternatively on the command line (as administrator):

& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --install-task --user .\svc-veloxprint

The setup:

1. grants the account the right Log on as a batch job,
2. sets the permissions of the data folder and secrets.json for the account,
3. registers the Windows event log source VeloxFactory Print Service,
4. creates or updates the task with the settings below.

The window shows the task under Settings → Operation: state, account, last and next run, last result and the XML definition. It can start and remove the task there, too.

5. Verify

1. Printers: print a test page on every printer the site uses.
2. Start the task (Settings → Operation → Start or reboot). The window switches to monitor mode.
3. Create a print task in VeloxFactory for one of the broadcast ids and watch it on the Dashboard.

Updates and rollback

PowerShell as administrator:

# newest release
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1

# a specific release, also the way back to an older one
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1 -Version 2.0.1

1. Releases are git tags (v2.0.1). git -C C:\kiwisoftware\VeloxPrint\app log --oneline shows the source commit of every release.
2. New settings are added to config.json with their defaults on the next start.
3. Never change files inside app\. The script refuses to update a modified folder. Settings belong into data\.

Several instances on one machine

Each instance needs its own configuration file. Its name becomes the prefix of all files of the instance, so several instances can share one data folder:

data\config.json               default instance
data\lager-nord.json           second instance
data\lager-nord.secrets.json
data\lager-nord.state.db
data\logs\lager-nord\

$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json                                   # window of this instance
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint

The task of that instance is called VeloxFactory Print Service (lager-nord). Give every instance its own broadcast ids.

All settings of an instance live in config.json in the data folder (see Installation and updates). The API token is not part of it, it is stored encrypted in secrets.json. Normally you edit everything in the window under Settings. The file can also be edited in a text editor, the running engine picks up the change by itself.

How the configuration is handled

Example

{
  "schemaVersion": 1,
  "instance": { "id": "5d0c2f4e-...", "name": "Warehouse North", "serviceAccount": "SRV01\\svc-veloxprint" },
  "api": { "baseUrl": "https://vf.example.com", "timeoutSeconds": 30, "allowUnencrypted": false, "serverTimeZone": "Europe/Berlin" },
  "receive": {
    "mode": "Hybrid",
    "broadcastIds": ["Standard", "Warehouse"],
    "includeWithoutBroadcastId": false,
    "pollingIntervalSeconds": 30,
    "safetyPollIntervalSeconds": 120,
    "pageSize": 10
  },
  "websocket": { "scheme": "wss", "host": "vf.example.com", "port": 443, "appKey": "your-reverb-app-key", "channel": "private-report-print-tasks" },
  "processing": {
    "paused": false, "pauseReason": null, "pausedUntil": null,
    "maxParallelJobs": 4,
    "serializePerPrinter": true,
    "retryCount": 3,
    "retryBackoffSeconds": [5, 30, 120],
    "printTimeoutSeconds": 120,
    "confirmation": "Spooled",
    "dryRunFolder": null
  },
  "printerDefaults": { "scaling": "ActualSize", "autoRotate": true, "dpi": null, "copiesMode": "Driver", "paperSource": null, "duplex": "Default", "color": "Default" },
  "printers": [
    { "queueName": "WH-LABEL-01", "localName": "\\\\printsrv01\\WH-LABEL-01", "dpi": 300 },
    { "queueName": "PDF24", "copiesMode": "Loop" }
  ],
  "logging": { "minimumLevel": "Information", "retentionDays": 30, "maxFileSizeMb": 250, "eventLog": true, "jsonFile": false },
  "statistics": { "retentionDays": 365, "resetAt": null },
  "health": { "enabled": false, "port": 8765 },
  "ui": { "errorNotifications": true, "windowWidth": null, "windowHeight": null, "windowMaximized": false }
}

instance

api

The API token is entered in Settings → Connection and stored in secrets.json. Required rights: global:use-api, report-print-task:read, report-print-task:update, optional printer:read. The token never appears in logs, exports or diagnostic packages.

receive

websocket

Ignored in mode Polling. The URL is built as {scheme}://{host}:{port}/app/{appKey}?protocol=7&client=veloxprint&version={x}.

processing

printerDefaults and printers

printerDefaults applies to every printer. An entry in printers overrides single values for one queue name; a value missing there (or null) falls back to the default. Details and advice in Printers and printing.

logging, statistics, health, ui

This page follows a print task through the Print Service: how it arrives, which instance takes it, how it is printed, retried and confirmed, and what protects it against being printed twice.

Receive modes

Why the safety poll

Reverb delivers an event once and does not keep it. An event sent during a short network interruption is lost, and a connection can look alive without delivering events. The safety poll finds such tasks at the latest after its interval. Tasks the journal already knows are skipped, so polling never prints twice.

The poll request

GET /api/v1/report-print-task?status=pending&perPage=10&page=1&withMedia=true
    &withRelations=false&withAudit=true&broadcastId=Standard,Warehouse&withoutBroadcastId=false

1. The filter runs on the server: only tasks of the own broadcast ids are returned.
2. withMedia=true delivers the PDFs directly, no second request per task.
3. withAudit=true delivers the creation time for the lead time statistics.
4. If more pages exist, the next page is requested immediately instead of after the interval.

The WebSocket connection

1. Pusher protocol 7 against Laravel Reverb, private channel private-report-print-tasks, authorized with POST /api/v1/broadcasting/auth and the API token.
2. The event report-print-task.created carries { model, id, broadcastId }. If the broadcast id matches, the service loads the task with GET /api/v1/report-print-task/{id}?withMedia=true.
3. Keep-alive: every pusher:ping of the server is answered with pusher:pong. After 25 s without traffic the service sends its own ping and drops the connection if no pong arrives within 30 s.
4. Reconnect with exponential backoff from 1 s to 60 s, ±20 % jitter. After every successful subscribe a catch-up poll fetches what was created in the meantime.
5. A first connection failure is logged as warning. An outage longer than 5 minutes writes event id 3000.

Broadcast ids: which instance prints what

Every print task and every printer in VeloxFactory can carry a broadcast id, usually one per site or printer group. An instance only takes tasks whose broadcast id is in its receive.broadcastIds, both from events and from polls.

Tasks without broadcast id are taken only with includeWithoutBroadcastId. VeloxFactory sends no WebSocket event for them, so they arrive only by polling: in Hybrid within safetyPollIntervalSeconds, in mode WebSocket only at start and after a reconnect. Give print tasks a broadcast id whenever they should print immediately.

Rate limit

The VeloxFactory API limits requests per IP address, by default 10 per minute (API_RATE_LIMIT_PER_MINUTE). The service reads the limit from X-RateLimit-Limit and the rest from X-RateLimit-Remaining in every response and shows both on the dashboard.

1. On HTTP 429 every API call of the process waits until Retry-After (60 s if the header is missing), then the same request is sent again. Print tasks wait, they do not fail. The API state shows Rate limited, event id 2002 is written.
2. The service does not slow down in advance. A low remaining count is only displayed.
3. Settings → Receiving shows the base load of the chosen mode in calls per minute (Hybrid with 120 s: 0.5) and warns when it exceeds half of the limit.
4. The limit counts per IP. All print services, scripts and MCP clients behind the same NAT share it. For print environments raise API_RATE_LIMIT_PER_MINUTE in the .env of your VeloxFactory instance.

Processing

Receiver -> queue -> journal check -> worker (max. maxParallelJobs) -> printer lock -> queue check -> print -> outbox

1. Journal check. A task the journal knows in state Printing or later is skipped. A task that was confirmed or reported before and is pending again (reprint) is loaded fresh; only if VeloxFactory really shows it as pending is it printed again.
2. Fetch. Tasks from a WebSocket event are loaded now, tasks from a poll already carry their PDF. A task that no longer exists or is no longer pending is dropped.
3. Printer. The queue name of the task is resolved to the local printer (alias, see Printers and printing). The Windows default printer is never used; a task without printer name fails with PrinterNotFound.
4. Printer lock. With serializePerPrinter only one job runs per printer, ordered by task id. Jobs for different printers run in parallel up to maxParallelJobs.
5. Queue check. Before printing, the Windows queue is checked. Not installed fails immediately. Offline, paper problem or error goes into retry without printing.
6. Print. See Printers and printing. The spooler document name is VF #{id} {file name}, so the job can be found in the Windows print queue.
7. Confirm. With confirmation = Spooled the task is confirmed as soon as the spooler accepted it. With Completed the service waits until the spooler job has finished (at most printTimeoutSeconds).

Retries

With the defaults (retryCount 3, retryBackoffSeconds [5, 30, 120]) a task waits about 2.5 minutes before it is reported as failed. For label printers that are offline longer, for example during a roll change, use more retries or a longer last value, e.g. [5, 30, 120, 300, 600] with retryCount 5.

Error reports

Permanent failures are reported with PATCH /api/v1/report-print-task/{id}/set-status, status error and an errorMessage of the form [Category] message, shortened to 1,000 characters. Categories: PrinterNotFound, PrinterOffline, RenderFailed, Timeout, SpoolerError, Unknown. The task shows the message in VeloxFactory.

Job journal and outbox

VeloxFactory has no endpoint to claim a task. The local journal in state.db takes that role and records every task with its state:

Outbox. Confirmations and error reports are written to the outbox first and then sent. If the API is unreachable, the outbox retries with backoff (5 s, doubling, at most every 5 minutes) until it succeeds. If VeloxFactory answers 404 (task deleted) or 422 (rejected), the entry is dropped. After a crash, spooled tasks without outbox entry get their confirmation again. The dashboard tile Queue shows open outbox entries as to confirm.

Reprint. To print a task again, use Jobs → Print again in the window. It resets the task to pending in VeloxFactory (PATCH set-printed with false), the next poll prints it. Resetting the task in VeloxFactory itself has the same effect.

Pause processing

A pause stops printing without stopping the service. Use it for printer maintenance, a roll change or while wrong tasks are cleaned up in VeloxFactory.

1. Set it on the dashboard (Pause / Resume) or under Settings → Processing with reason and optional end time. The pause is stored in config.json, so it survives a restart and a pause set in the window also pauses the headless engine.
2. While paused: the WebSocket stays connected, events are noted but not processed, periodic polls are skipped. Tasks already in the pipeline wait before their next print attempt; the waiting time does not count as a retry. A print call already in progress is not interrupted. The outbox keeps delivering confirmations.
3. New tasks stay pending in VeloxFactory.
4. On resume the service polls immediately and prints everything that arrived meanwhile.
5. The engine state is Paused with reason and end time. The health endpoint still answers 200.

Dry run

For tests and demonstrations without paper. With processing.dryRunFolder set (or --dry-run <folder> on the command line, which applies to that run only) every task is received, fetched and resolved as usual, but instead of printing the PDF is written to <folder>\<task id>_<file name>. Nothing is confirmed, the task stays pending in VeloxFactory.

A print task names its printer by the printerName of the VeloxFactory printer master data (see Printers: master data for your print targets). The Print Service calls this the queue name and maps it to a Windows printer on its machine. This page covers that mapping, the per-printer settings, how pages are printed and which printers are not suitable.

Installing printers for the service

The headless service runs under its own account without a desktop. What that account cannot see, it cannot print on.

Install a print server connection machine-wide (as administrator, takes effect after the spooler restarts or the next logon):

rundll32 printui.dll,PrintUIEntry /ga /n\\printsrv01\WH-LABEL-01
Restart-Service Spooler

The printer list

The Printers page of the window compares four sources:

1. the VeloxFactory printer master data (GET /api/v1/printer, needs printer:read), filtered on the own broadcast ids. Printers without broadcast id only appear with includeWithoutBroadcastId,
2. the printers installed on this machine,
3. printers with own settings in config.json,
4. printers that received jobs in the last 7 days but are in none of the sources above (Only in recent print jobs).

Local printers that no row points to are listed at the end as Not in VeloxFactory, useful as alias targets and for test pages.

Actions per row: copy the printer name, print a test page, edit the printer settings, open the Windows print queue.

Alias: local printer name

The alias (localName) sends the jobs of a queue name to a Windows printer with a different name. VeloxFactory does not need to know about it.

"printers": [
  { "queueName": "WH-LABEL-01", "localName": "\\\\printsrv01\\WH-LABEL-01" },
  { "queueName": "OFFICE-A4",   "localName": "Brother HL-L3210CW series Printer" }
]

1. Without alias the Windows printer must have exactly the queue name (case-insensitive).
2. Typical uses: the same printer has a different name on every workstation, a temporary replacement printer, or a PDF printer for tests.
3. The alias is set in the printer editor, field Local name. The same name as the queue name, or empty, stores no alias.
4. The alias lives in the local config.json. Every machine needs its own entry.

Printer settings

printerDefaults in Settings → Printer defaults applies to all printers. The printer editor on the Printers page overrides single values for one printer (Use default keeps the default). The effective value is: printer override, else default, else the driver's setting.

All settings apply to the single print job only. The service never changes the configuration of the Windows printer. Some drivers ignore job settings for duplex, colour or tray and use their own defaults; in that case change the setting in the printing preferences of the Windows printer.

How pages are printed

1. The PDF stays in memory, nothing is written to disk.
2. PDFium (the PDF engine of Chromium) draws every page directly onto the device context of the printer, in the device resolution and without an intermediate bitmap. Text, lines and barcodes are sent as vector graphics and print as sharp as the printer can.
3. The target rectangle is computed per page from the printer's resolution and printable area, so pages of different size or orientation in one document work.
4. Output uses the Windows spooler without any print dialog. The document name in the spooler is VF #{task id} {file name}.
5. PDFium is not thread-safe; its calls are serialised inside the service, jobs on different printers still run in parallel.

Limitations:

1. Pages with transparency (for example PNG images with alpha channel) are output by PDFium as an image in device resolution.
2. Form fields (AcroForm) are not printed.
3. Lines with width 0 in the PDF are drawn as the thinnest line the device can print, one printer dot. On high-resolution printers they become very thin. Give lines and borders in the JRXML an explicit width, e.g. lineWidth="0.5".

Printers that open a dialog

Some printers ask for a file name or open an application window when printing. In the headless service there is no desktop: the dialog is invisible and waits forever. The job ends after printTimeoutSeconds and is reported as Timeout.

The service marks these printers with Prints with a dialog, not suitable headless. Detected by port (PORTPROMPT:, XPSPort:, PDF24:, FAX:, SHRFAX:) or driver name (Microsoft Print To PDF, Microsoft XPS Document Writer, OneNote, PDF24, Fax). In the window they work, the test page asks for confirmation first. For PDF tests without dialog use the dry run or configure PDF24 with automatic saving.

Test page

The test page is an A4 PDF in the VeloxFactory design, generated locally without API access. It contains instance name, printer, time and account, a line pair pattern that shows the effective resolution, grey scale steps, a Code 39 barcode and a frame 10 mm from the paper edge to check margins and scaling. It is printed with the settings of the printer, including alias.

Print it from the Printers page or on the command line:

& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --test-print WH-LABEL-01

Started without parameters, the Print Service opens its window in the VeloxFactory design (light, dark or system theme). The header shows the pages, the instance name and the mode badge: Interactive when the engine runs inside the window, Monitor when a headless engine runs and the window only shows its state. Screenshots follow.

Dashboard

Below the tiles: the last 20 jobs and the last 5 errors. A click opens the job.

Console

The live log, written for users: Task #4711 received (WebSocket, Standard) → WH-LABEL-01, 2 copies instead of raw protocol events.

1. Columns: time, level (icon and colour), area (API, WS, Print, Engine), task, message.
2. Filters: levels as chips, area, text search, a single task, errors only. Clear filters resets them.
3. Autoscroll can be paused. Copy a line, export the selection or all visible lines, click a task to open it.
4. Protocol details (ping, pong, channel auth) are logged on level Debug and hidden by default.
5. Buffer: 10,000 lines in the window. In monitor mode the lines come from state.db, which keeps the last 50,000 entries.

Jobs

The local history from the job journal: id, time, printer, file, copies, pages, channel (WebSocket or poll), duration, status, trace id. Filters for period, status and printer, search by #id, file name, trace id or error text.

The detail view shows the timeline of states, error text and attempts. Actions:

Printers

Comparison of VeloxFactory printers, local printers, own settings and printers of recent jobs, with state, hints, test page, printer editor and a link to the Windows print queue. Described in Printers and printing.

Statistics

Local statistics of this instance, nothing is sent to VeloxFactory.

1. Tiles for today and 7 days: jobs printed and failed, error rate, pages.
2. Jobs over time per hour (24 h, 7 days, 30 days), pages and copies per printer, top error categories.
3. Lead time from creation in VeloxFactory to confirmation (median, P95), share of WebSocket and poll, WebSocket availability and reconnects, API calls and 429 events.
4. Export as CSV. The mouse wheel over a chart zooms the chart only.
5. Retention statistics.retentionDays (365 days); after 30 days the data is kept as daily aggregates.

Settings

1. Save writes config.json, the engine applies it without restart. Unsaved changes are asked for when leaving the page.
2. Test connection checks: reachability, token (GET /report-print-task?perPage=1), printer master data (printer:read), channel authorization and WebSocket handshake (15 s), rate limit headers compared with the base load.
3. Reset statistics counts from now on. The job journal stays, it protects against double printing.
4. Clear logs empties the console history and deletes all log files of the instance except today's.
5. Without write access to the data folder the window offers Restart as administrator.

Info

Version, .NET runtime, Windows account (with Administrator when elevated), mode, instance id, paths of configuration, data and log folder with buttons to open them, and Create support package (see Monitoring and troubleshooting).

Notification area

In interactive and monitor mode the Print Service has a tray icon with status colour (green OK, yellow warning, red error) and a menu: open, pause, exit. Closing the window hides it in the notification area; in interactive mode the engine keeps running. Exit stops the engine gracefully: running jobs finish, the outbox is flushed. Print errors show a Windows notification unless ui.errorNotifications is off.

The program file is kiwisoftware.VeloxFactory.PrintService.App.exe in app\bin. Without parameters it opens the window. All other functions are available as parameters, for the scheduled task, scripts and software distribution.

Parameters

1. Paths (--config, --dry-run, --support-package) must be absolute. The Task Scheduler starts in C:\Windows\System32, a relative path would end up there.
2. Mapped network drives do not exist for the service account. Use local paths or UNC paths.
3. An unknown parameter or a missing value prints the usage and ends with exit code 1.

Exit codes

Exit codes 1 and 3 of a headless start are visible in the Task Scheduler as Last run result. The Task Scheduler restarts the task every minute; fix the configuration or token, the next start picks it up.

Examples

$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"

# check configuration and connection
& $exe --validate-config
#   Configuration: C:\kiwisoftware\VeloxPrint\data\config.json
#   [OK]      Configuration is valid
#   [OK      ] Reachability: https://vf.example.com
#   [OK      ] Token: Token accepted, report-print-task:read granted.
#   [OK      ] WebSocket: Subscribed to private-report-print-tasks on vf.example.com:443.

# scheduled task for the default instance and for a second instance
& $exe --install-task --user .\svc-veloxprint
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint

# test page
& $exe --test-print WH-LABEL-01

# engine in a console window for debugging (stop the scheduled task first)
& $exe --headless --console

# dry run into a folder
& $exe --dry-run C:\Temp\veloxprint-dryrun --console

# diagnostic package
& $exe --support-package C:\Temp\veloxprint-support.zip

# graceful stop of the default instance
& $exe --stop

The headless service has no window, so it reports through log files, the Windows event log and an optional local health endpoint. For support cases it bundles everything into one diagnostic package.

Log files

data\logs\veloxprint-20260925.log
data\logs\veloxprint-20260925_001.log        same day, after the size limit
data\logs\veloxprint-20260925.json           optional, logging.jsonFile
data\logs\lager-nord\veloxprint-...          instance with --config lager-nord.json

2026-09-25 07:16:48.120 +02:00 [INF] [Print] [#35] Task #35 received (WebSocket, Standard) -> WH-LABEL-01, 1 copy
2026-09-25 07:16:49.402 +02:00 [INF] [Print] [#35] Task #35 spooled to WH-LABEL-01, 1 page
2026-09-25 07:16:49.655 +02:00 [INF] [API] Task #35 confirmed as printed

Format: time with offset, level (VRB, DBG, INF, WRN, ERR, FTL), area (API, WS, Print, Engine), task id where known, message.

1. One file per day, a new file (_001, _002) when logging.maxFileSizeMb (250 MB) is reached.
2. Files older than logging.retentionDays (30) are deleted, by age, not by count.
3. Lines of a task carry its task id and trace id; the trace id links it to the history record and print task in VeloxFactory.
4. The API token never appears in any log.

Windows event log

Warnings and errors go to the event log Application, source VeloxFactory Print Service, with fixed event ids for monitoring systems such as Checkmk, PRTG, Zabbix or SCOM. The source is registered when the scheduled task is set up; without it the event log output stays off. Switch it off with logging.eventLog.

Local health endpoint

Optional, switched on under Settings → Operation (health.enabled, port health.port, default 8765). It listens only on 127.0.0.1, needs no URL reservation and no administrator rights, and is not reachable from other machines. A monitoring agent on the same machine polls it.

GET http://localhost:8765/health

{
  "status": "ok",
  "engine": "Running",
  "hostMode": "Headless",
  "version": "2.0.1",
  "startedAt": "2026-09-25T05:01:12+00:00",
  "api": {
    "state": "Ok",
    "lastApiSuccess": "2026-09-25T07:16:49+00:00",
    "lastApiError": null,
    "rateLimit": { "limit": 60, "remaining": 58, "rateLimitedUntil": null }
  },
  "websocket": { "state": "Subscribed", "since": "2026-09-25T05:01:14+00:00", "reconnectAttempt": 0 },
  "queue": { "active": 0, "waiting": 0, "retrying": 0, "outbox": 0 },
  "printers": { "ok": 3, "withProblems": 0 }
}

Worth alerting on besides the status: queue.outbox above 0 for a longer time (printed but not confirmed), queue.retrying above 0 (printer problem), printers.withProblems above 0, websocket.state not Subscribed.

Diagnostic package

Info → Create support package, or --support-package C:\Temp\support.zip. The ZIP contains:

The API token is removed from every file.

Common problems