What are microservice log files?
Erply microservices are used for hardware integrations in order to let the POS web based application communicate with a device (printer, card reader, etc).
These microservices give the option to record logs of messages exchanged between the POS web app and the device. This is especially useful for troubleshooting issues with an hardware integration. Logs are recorded in a file, saved on the computer where the hardware is configured (ie. the computer where the printer is plugged in for example).
How to enable logging
Logging is enabled by setting a parameter in the configuration file of a microservice.
This can be set from Erply POS Wizard: https://posow.erply.com
Accessing a microservice configuration file with Erply Wizard
- Go to Erply Wizard and log in with your Erply credentials
- Go to Hardware -> Installation App -> Installation and make sure the Installer App is installed and detected running
- Go to Micro-service Manager. Under Update existing micro-service, select the integration for which you want to enable logs (for example Cayan)
- The next screen will present two text blocks
- On the left is the current configuration file as it is on the local machine
- On the right is a text editor that allows you to make changes to that configuration file
Set logging target
In order to record log files on the computer, in the microservice install folder, you need to set the logTarget parameter to FILE.
"logTarget": "FILE"
Set logging level
There are 4 levels of logging: "info", "warn", "error", "debug"
By default the log value is set to "error".
If you are trying to troubleshoot an integration issue, “debug” will give you the most information.
"logLevel": "DEBUG"
Push changes to the configuration file with Erply Wizard
On the configuration file editor (right text block), locate the “logTarget” and "logLevel" parameters and set the values accordingly.
After changing the values, make sure that the button below the right text block is green and reads “Valid JSON”. If the edited version of the configuration file is incorrect, the button will turn red and read “Invalide JSON”
Click on “Save new configuration” below the left text block to push the changes to the local configuration file (recorded on the computer):
At the bottom of the page, click the Stop button, then click again as it has switched to Start button. This is to restart the microservice so that it loads the new configuration.
⚠️ Changing logging parameters is not retroactive.
If you are changing the log level to capture more comprehensive information (eg from INFO to DEBUG), the change will only affect future usages of the integration/microservice.
Where are microservice log files saved?
This is for when "logTarget": "FILE"
On Windows
When installing Erply installer and microservices, they are installed by default under: C -> Program Files -> Erply
Under the Erply folder, each microservice and version has its own subfolder.
Eg: C -> Program Files -> Erply -> cayan-integration -> v1.5.15
On MacOS
The Erply folder is created under the root Library folder.
How to access log files in MacOS?
- Open Finder
- Click Go in the top menu bar, then Go to Folder
- Type /Library/Erply and click Go
- Open the name of the microservice (eg cayan-integration), then open the folder named after the microservice version
- If logs were enabled, there will be a logs folder. You cannot open it while the microservice is running.
How to retrieve log files to share with support on MacOS?
- Right click on the logs folder and select copy “logs”
- Go to a folder where you can email the logs from, like Downloads
- Paste the logs folder (command + V or Edit -> Paste Items from the top menu bar)
- You will get a warning “You may need to enter the name and password for an administrator on this computer to change the item named “logs”.”
Click Continue - Enter the computer password (not the appleID password)
- Rename the logs folder that has been pasted and transfer it to the support team.
What is log rotation?
When logs are recorded on the computer (logTarget: FILES), logs are not kept indefinitely. In order not to clutter the computer, the size and number of files are limited. Only the most recent logs are kept.
For example, if log rotation is set to only keep 2 files, and each file is set to only contain 2 days worth of information, on day 5, logs files for days 2 to 5 will be kept, but the log file for day 1 will be deleted.
How to edit log rotation rules?
Log rotation rules can be set in a microservice configuration file:
logRotateBytes: specifies the maximum size the log file can grow before rotating it
logRotateDuration: specifies the time in days when to rotate the log file (maximum age)
logRotateMaxFiles: specifies the number of log files to keep