Visitor Service

Overview

The VisitorService retrieves visitor data from the visitors (targeting:targetingdata) data store. You can update and persist a Visitor object to the data store using Visitor#save(). Both the retrieval methods and the Visitor#save() operation are implemented in VisitorServiceImpl.

During request processing, visitor retrieval is synchronous. The application requires visitor data to personalize the page before serving the response. Updates to visitor data are persisted asynchronously to avoid delaying the HTTP response.

You can configure several operational parameters for the visitor service. The default configuration is shown below:

/targeting:targeting:
  /targeting:services:
    /visitors:
      maxRetrieveThreads: 10
      maxStoreThreads: 10
      retrieveQueueSize: 20
      retrieveTimeout: 50
copy

These defaults are suitable for most environments. If you observe frequent retrieveTimeout occurrences in production, adjust the parameters as needed.

Parameter Reference

maxRetrieveThreads

Defines the maximum number of threads used to retrieve visitor data. To prevent concurrent HTTP requests from blocking each other during visitor data retrieval, set maxRetrieveThreads to at least 10. Lower values increase the risk of exhausting the retrieve queue and serving requests without relevance due to timeouts.

maxStoreThreads

Specifies the maximum number of threads for storing visitor data concurrently. Typically, you do not need to modify this value. Visitor data is stored in batches—either after accumulating requests for one second or when a batch reaches 100 visitor data objects. Only when incoming HTTP requests exceed the batch processing capacity are multiple threads used.

retrieveQueueSize

Sets the maximum number of queued visitor data retrieval jobs. When this limit is reached, the Visitor Service rejects new visitor data requests, and the HTTP request proceeds without relevance. This limit prevents excessive request blocking and helps the application degrade gracefully under high load.

When increasing retrieveQueueSize, ensure it remains smaller (ideally at least 20% smaller) than the maximum number of concurrent requests allowed by your servlet container. For example, if Tomcat is configured for 100 concurrent requests, set retrieveQueueSize no higher than 80. This approach maintains the automatic scale-down protection—serving pages without relevance is preferable to overloading the application or exceeding the container’s acceptCount. For Tomcat-specific details, refer to the Tomcat 8 documentation on maxThreads and acceptCount.

retrieveTimeout

Specifies the maximum time in milliseconds that the Visitor Service waits for visitor data retrieval. If retrieval exceeds this duration, the HTTP request continues without visitor data. This setting prevents the application from waiting excessively, for example, if the database is slow or unresponsive.

retrieveTimeout is the most common parameter to adjust in production, especially if the connection to the data store is slow or if retrieveQueueSize is large and many concurrent requests are queued. Increasing this value allows more time for retrieval but increases the risk of delayed page responses when visitor data is slow to load.

JMX Monitoring

You can monitor the visitor service and its data stores using JMX MBeans.

If the VisitorStat MBean reports a high value for RetrieveVisitorDataTimeoutCounter, consider adjusting the retrieveTimeout parameter. Review the explanations above to determine the appropriate configuration for your environment.