Frameworks
Integrations
Mendix
SharePoint
Modular UI
Legacy UI
AnnotationManager
Annotation Types
Customize
Version 11
Version 10
v10.12
v10.11
v10.10
v10.9
v10.8
v10.7
v10.6
v10.5
v10.4
v10.3
v10.2
v10.1
v10.0
Version 8
v8.12
v8.11
v8.10
v8.9
v8.8
v8.7
v8.6
v8.5
v8.4
v8.3
v8.2
v8.1
v8.0
Version 7
Version 6
v6.3
v6.2
v6.1
v6.0
Version 5
Version 4
Version 3
Version 2
WebViewer Server
WebViewer BIM
After deploying the server you may encounter grey pages, the following are common causes and solutions to this issue.
Possible cause: User stickiness is not being maintained to a single server, this causes requests to go to the wrong server.
Solution: Add stickiness which keeps a user stuck to a single server permanently, or use our query parameter "BCID" to maintain stickiness.
Possible cause: Your user's connection is timing out causing disconnections during document processing.
Solution: Increase timeouts across all infrastructure pieces between the client and server to 30+ seconds.
Possible cause: Your intervening proxy servers between WebViewer & WebViewer Server have not been properly configured for Websockets.
Solution: Refer to your proxy server's infrastructure documentation on how to implement websockets, the following are for NGINX and HAProxy.
https://www.haproxy.com/haproxy-configuration-tutorials/load-balancing/websocket/https://nginx.org/en/docs/http/websocket.html
Possible cause: The server your user was connected to became unhealthy, resulting in a redirection during initial load.
Solution: Monitor your server's health checks and GetPerf API to prevent users from connecting to soon-to-be unhealthy and unhealthy servers.
Possible cause: Your server is overloaded and requires a capacity upgrade. This results in users being constantly disconnected.
Solution: Consider raising the number of CPUs available to the server. If the memory is showing as at its limit, increase it as well. Improving the disk speed for the on disk cache may also result in improved performance. You may also want to consider autoscaling your servers for load. We recommend using our GetPerfInfo API for determining if you want to scale.
After deploying your server, you find your client is unable to connect to the server.
Possible cause: The webviewerServerURL provided to your WebViewer constructor is incorrect.
Solution: Verify the correct URL is being provided that is able to access the server. You can test the URL via the health check API localhost:8090/blackbox/HealthCheck.
Possible cause: Websockets are not properly configured on your infrastructure or not supported.
Solution: Ensure all parts of your infrastructure can support websockets, including load balancer and proxy servers.
Possible cause: You did not bind the correct ports on the server.
Solution: When starting docker, bind the ports correctly. By default port 8090 (HTTP) and port 8443 (HTTPS) should be bound to external ports. https://docs.docker.com/engine/network/#published-ports
WebViewer Server requires that you place your key in both
On the client side the key would be used like so:
On the server side, place the key in your docker-compose.yaml file under pdfd-tomcat > environment:
If you are using the Windows installer, you would place the key within the wvs_config.json.
Possible cause: The links provided to WVS lack a file extension.
Solution: Ensure your links have a file extension, or provide an extension (ext) argument via loadDocument containing the proper extension.
Possible cause: The file is not accessible by WebViewer Server.
Solution: Grant WebViewer Server permission to access the file server or structure the infrastructure so that WebViewer Server can reach the file server.
Possible cause: You are passing localhost links to the container when the file server is not in the same network.
Solution: Use the real IP address of the servers when providing file links, Docker networks are isolated from your normal machine network.
Possible cause: The file server requires authentication.
Solution: Implement authentication passing for the file URL, you may find our cookie forwarding options or custom headers options useful for doing this.
Possible cause: Low disk space.
Solution: Provide a larger disk to the server, we require 50GB at minimum but recommend enough that your disk large enough such that it will not become maxed out in a matter of minutes during high load.
Possible cause: Your caching options should be reconfigured.
Solution: Adjust these settings - see default behaviour for WebViewer Server's caching.
Possible cause: Your Docker agent is storing old container images.
Solution: Adjust your settings so old Docker images are pruned, and prune existing Docker images. The WebViewer Server Docker image is nearly 2GB, so if enough versions are pulled, the data consumed can be quite large. These images can normally be pruned on local machines via docker system prune.
Possible cause: The host system is configured for verbose core dumps.
Solution: Lower the verbosity of these core dumps. This means when the application crashes, WebViewer Server will generate a massive debugging file > 1 GB, these are not managed or deleted. They may consume a large amount of disk space. The following website details how to configure core dumps and prevent this behaviour.
https://linux-audit.com/understand-and-configure-core-dumps-work-on-linux/
Possible cause: You are running in client only mode.
Solution: This may occur if webviewerServerURL was not correctly set in the WebViewer constructor or your WebViewer Server is not available. Ensure the URL provided there is accessible and valid your server is passing health checks.
Possible cause: You are lacking certain license permissions.
Solution: Speak to sales about adding new permissions, such as Office/HTML2PDF and CAD, to your license key. If this is the cause, you will note license failure errors in your logs, they will point to what license feature is missing.
Possible cause: You are using a version of WebViewer Server older than 1.5.8. Solution: Use the newest version of WebViewer Server.
The network load balancer does not support Websockets, however, the classic and application balancers do.
If using the classic load balancer all communication will have to be done over SSL and TCP ports rather than HTTP and HTTPS. This is because this balancer does not provide native support for Websockets. This requires a custom configuration of the load balancer. We recommend moving to an application load balancer.
WebViewer Server is a read/write intensive application. A single document load would result in around 5~ files being written on average, and those 5 files would all be read by a client. This leads to the server being severely limited by low disk speeds. In turn, one of the key pieces of a well performing server is offering a good disk.
Giving your server an NVMe disk directly dedicated to the server will be the most ideal situation. By having one directly connected to the server you will get the fastest possible read and write speeds and not be subject to external interference.
Network shared storage offers the advantage of allowing caches to be shared between servers, but this can lead to problems if the network storage does not offer enough speed for your load.
The best thing to do is verify first what kind of speeds your network storage provides in terms of read and writes, this can be done via real world disk tests such as using dd to test disk write speeds.
Testing Write Speed
Testing Read Speed
Prior to this test, you should create a file at /tmp/tempfile. The write test will have created this file if done prior.
If these speeds are not capable of exceeding 80 MB/s (~2500 IOPS) with a single server in use, you will likely encounter issues in your server when at load. It should also be considered that this max speed will be lowered if you have multiple servers attached to a single network disk. We do not recommend shared network storage when dealing with a high load environment, but it is possible to make it work if your network share has enough performance.
These instances are subject much to the same issues as network shared storage is, but do generally not have to deal with external entities consuming read/write speeds. These instances should be tested if you are unsure about their performance. If your provider cannot guarentee a certain IOPS or base speed for the disk, these disks may be sharing a pipeline with other users and provide lower speeds than expected. If using any attached instance one should have a confirmation that they will maintain a certain IOPS level. One such example of this is GP3 from Amazon, which provides a baseline of 3000 IOPS.
Many Azure attached disks lack a guaranteed minimum and should be avoided. Dedicated disks would be preferred here.
The logs produced by WebViewer Server can be hard to understand, in this section, we'll go over common flows and how the logs work.
This section goes over how to read things which occur in the logs, all information here is based on the 2.2.4 version of WebViewer Server.
You will see two types of log messages, the first are the Tomcat application logs. The second are logs directly from the internal worker.
Logs prefixed with bb-worker are logs directly from the internal worker, all other logs are from Tomcat. Logs from bb-worker may come in bursts rather than in time with other log information. Enabling TRN_DEBUG_MODE will increase the number of logs you see by raising the log level to Debug.
The client connects to the server via a websocket. After this, the client would begin sending requests over the websocket.
The websocket is given the ID 7445d53b-97c4-4a1a-abb7-bd853d400bd3, there is 1 user currently connected to the server.
Here we begin fetching the URL sent to WebViewer Server: http://192.168.1.251/testdocs/1.ppt.
We see the first occurence of the job ID, this is 7445d53b-97c4-4a1a-abb7-bd853d400bd3. You may use this ID to cross reference certain log statements.
WebViewer Server queues a collection of jobs for the document, note the unique filename key for this document CYIVlM4MyneW9y9L4p3hiZJ3Qc3rJR04ywYg2hIKdgU. You can cross reference this key with logs to determine what file the work belongs to.
This task requires a conversion, so we add it to the special conversion queue.
Work on the actual document starts here, the actual file is fetched to begin work.
Conversion starts here, when a file needs to be converted the conversion must complete before any other tasks can start.
The convert operation is assigned a job here, 410aa502-a594-459e-b880-42bce42be547 - this key is used by the internal worker. This is followed by the contents of the job - you can see the type of job from the op field in the statement - in this case, it's convert. This allows you to link a specific file to an operation directly.
The internal worker starts the job, you may find that this print statement does not come till later due to buffering.
Conversion is completed and returned to Tomcat.
At this point, the PDF is ready and other jobs start processing.
The first item for the document is returned, this is the pageinfo job generated from the converted PDF. This information would come back on the websocket, WebViewer would then use it to fetch the result.
At this point, more similar jobs would be started and returned. This is the general flow when any user loads a document.
A common issue is when a crash occurs on the server. When a crash occurs on the server, this results in a HeartbeatException error. This error is due to the internal heartbeat for a document job failing. The document which was part of this would have crashed the internal worker, and caused it to restart. You will likely see several failures when this error occurs.
This error may constantly repeat, which would signify multiple crashes. This may be caused by one of two things:
When the worker crashes due to a file as a result of this error, it will mark that file as 'dangerous' and will refuse to process it in future executions.
These logs will regularly appear throughout the log, they signify the server's current status. While most of what is here is self explanatory, the queue sizes line should be clarified. This line represents how many active jobs are on each of our queues.
This log statement will appear if your server job queues are becoming backed up, in this case - this server is in a state of failure due to errors blocking the queue.
This should follow a health failure, in this case, a queue overload failure.
Logs from BlackBoxWSEndpoint and ConnectionService will generally talk about the user websockets connecting and disconnecting. This represents connected users.
Sometimes these logs may contain exceptions, they are generally innocuous and represent a user abruptly disconnecting. It may also signify issues at the infrastructure level outside of WebViewer Server causing abrupt disconnections.
These logs represent the cachemanager, this manager controls the disk cache. These logs will generally tell you the current settings and any cleanup that was done to the cache.
Throughout logs there will be references to highQ, lowQ and convQ. These represent the queues. If they are higher than 0 this means files are waiting to be worked on. If they reach high numbers, exceeding 100, you should investigate if your server is able to handle the load being sent to it. The ideal situation is this value always staying at 0.
HighQ is the queue used for all processing of documents other than conversions. LowQ is the queue used for processing internal tasks. ConvQ is the queue used for processing file conversions.
Generally, we would expect the server to take only a few seconds to be ready for load after startup. There is a short grace period of time where initial setup occurs. This means an instance should not be used until **10 seconds after initial startup. During this startup folders are created and options are set, we recommend tracking the initial startup in logs to see what settings/versions the server started with. The first 100 lines should cover any startup information.
Any shutdown interrupts sent to the server should be immediately responded to with at most, a 5 second delay.
Did you find this helpful?
Trial setup questions?
Ask experts on DiscordNeed other help?
Contact SupportPricing or product questions?
Contact Sales