Activating logging

Purpose of logging feature

Especially in higher volume environments it can be of interest to have detailed information about the pdfToolbox processes as they happen. Suitable logging data can be a good foundation both for monitoring processing of PDF files as well as for post mortem analyses or analyses aiming to improve overall behavior of the whole processing system.

The logging feature that forms a part of pdfToolbox provides logging information in the form of JSON files that get written immediately at the following steps during an invocation of pdfToolbox:

  • When pdfToolbox is launched; only very basic data about the PDF file to be produced – such as file name  –  is available at this time, plus some information about the environment or the command line parameters
  • When pdfToolbox initiates processing of a PDF file; additional data about the PDF to be processed is provided – only aspects though that do not require no 'deeper' analysis in order not to hamper runtime behavior – such as file size or PDF version or size of the first page; in addition all variables – as evaluated at the beginning of processing – are included as well.
  • When pdfToolbox completes processing of a PDF file; at this stage various aspects of overview information is readily available, such as colors, fonts or ICC profiles used, output intents, conformance with PDF/X or other PDF standards.

Command line and Server versus Desktop

Logging is available in command line, Server and Desktop versions. It is not expected that logging on desktop is normally being used. Instead, on Desktop activating logging will help understand how logging works, and often makes it easier to design and test use of logging data outside of an automated production setup.

How to process logging data

Research has shown that most callas software customers who operate higher volume environments prefer any logging data to be provided rather as many small files using JSON over using other formats or a small number of large files. Beyond the way the logging data is provided, no assumptions are being made how these data are processed. 

Activating logging in command line version

There are 2 parameters that can be used to activate logging in the CLI version of callas products:

--trace

Parameter:

--trace[=folderpath]

Example:

./pdfToolbox --trace='/some-logging-folder' './some-pdftoolbox-profile.kfpx' './input.pdf' -o='./output.pdf'

Subfolder structure

By default the logging feature creates a subfolder structure inside the target folder for logging based on values for year, month and day, plus the app_uuid value (which can also be found inside each of the logging files):

 

YYYY
  MM
    DD
      app_uuid
        launch.json
        init.json
        finish.json
Click to copy 
2016
  10
    31
      0a0ceba3-7ca9-421f-a973-8caae2950690
        launch.json
        init.json
        finish.json
Click to copy

The JSON log files

There is an extensive article about the 3 JSON logging files, which will be created:

The JSON log files

Suppressing creation of subfolder structure

Parameter:

--trace_nosubfolders

Example:

./pdfToolbox --trace='/some-logging-folder'  --trace_nosubfolders './some-pdftoolbox-profile.kfpx'   './input.pdf'  -o='./output.pdf'

Activating --trace logging in Server version

In the "pdfToolbox Server: Job" configuration window, add the following to the text field under "Additional CLI parameters":

--trace[=folderpath]

Example:

--trace='/some-logging-folder'

Suppressing creation of subfolder structure in Server version

In the "pdfToolbox Server: Job" configuration window, add the following to the text field under "Additional CLI parameters":

--trace[=folderpath] --trace_nosubfolders

Example:

--trace='/some-logging-folder'  --trace_nosubfolders

Important note: If logging is to be enabled for processing of all files in pdfToolbox Server, this setting must be added to each job configuration.

--logexecution

Works similar to the "Log Profile Exceution" function on the desktop application, where logs are created during Profile execution into a separate folder. 

Parameter usage:

./pdfToolbox "Place content.kfpx" "simple sample file.pdf" --logexecution

Please note that for --logexecution, the resultant logging folder is written into the User Preferences folder.