Skip to main content

System configuration

System configuration

Configuring Acoustic Tealeaf

After you have installed Acoustic™ Tealeaf, you must complete additional configuration tasks to fully prepare your runtime environment.

Configuring Tealeaf components

Depending on which Acoustic Tealeaf components you enabled, you might need to configure services, features, and component functionality.

For a multi-machine implementation, configure all the machines before starting any of the Tealeaf services.

Common configuration tasks include:
Configuring the System Timezone
Tealeaf requires that a single time zone be defined across all Tealeaf servers in the system. For some operations, such as searching, the time zone may change the meaning of parameters such as today or yesterday. Among other features, this system-wide time zone is used as the basis for determining when scheduled reports are executed and delivered.
Configuring the Alert Service
This service manages execution and delivery of event-based alerts. You can configure this service to send email messages depending on threshold values defined for the event or Top Mover.
Configuring the Transport Service
The Transport component is responsible for accepting hits from the Capture server, performing a series of pipeline operations, and then delivering the hit to the Processor component.
Configuring the CX Canister
After installation, you may need to perform additional configuration of the Tealeaf CX Canister for single server or multi-server installations.

Configuration settings can be used to deploy the Canister and indexing functions across multiple servers, or you can install multiple Canisters on the same machine or across multiple machines.

Configuring CX Indexing
A session index is a database that stores the locations of meaningful words and fields in each session. Because an index does not contain all text from each session, it can hold a large quantity of session information in a single file.
Configuring the Report server
The Report Server consists of the Portal Web Application, the databases, and the Data Service. You can configure the Report server timezone and change various Report server configuration settings.
Configuring the Search server
Search server implements several low-level functions used by the Tealeaf system to retrieve session data and to monitor the systems that maintain it. You can configure Search server settings.
Configuring the Scheduling Service
The Scheduling Service can be used to schedule repeated Tealeaf-specific jobs. During installation, the Scheduling Service is configured to automatically start up, yet some default jobs are disabled. You can change these settings as you see fit.

Configuring Portal settings

After you log into the Portal, you can configure it for use.

You can use the Tealeaf Management System (TMS) to perform many of the operations for configuring Tealeaf servers and services. The TMS provides users and administrators with a centralized component for administering Acoustic Tealeaf.

Configuration tasks
Task Description
Configuring the Portal announcements

Portal announcements are messages displayed to all Portal users upon login. These messages can be used to display current system status, scheduled maintenance windows, or other issues.

With each installation or upgrade, it is recommended that you create a Portal announcement message to your users. The announcements provide information as to the current stage of the machine, its state, and whether there are any current issues that might impact Tealeaf users.
Configuring miscellaneous settings for Portal

In the Miscellaneous settings panel, you can define a variety of settings, including the Tealeaf administrator's contact information.
Configuring Portal authentications

By default, the Portal is configured to use Portal authentication, which leverages the Portal's user management capabilities to control access.

Additionally, you can configure the following authentications:
  • NT (AD - Active Directory) authentication
  • Mixed Mode authentication
  • Web Services authentication
  • Single Sign On (SSO) Authentication
Identifying additional severs to the Portal

During the installation process, reference information for any installed Reporting Server, Replay Server, Visitor Server, and any Canister Servers(s) are inserted into the database for use by the Portal.

If there are other Tealeaf servers in the environment, the Portal must be made aware of them.
Creating user accounts for the Portal
You can create user groups for the following Tealeaf products:
  • cxImpact
  • cxView
  • cxReveal
Configure and define reporting mechanisms for the Portal
Reporting mechanisms include:
  • Scorecards

    Scorecards are used to report in graphical or tabular format useful metrics on data captured by Tealeaf.

  • Dashboards

    Dashboards can be used to arrange multiple reporting components into a single page.

  • Status report

    The Tealeaf Status report delivers status information on the Portal and other components of the Tealeaf system.

  • Search and List Templates

    Search and List Templates can be configured to enable specific search fields for specified groups.
The following are examples or Portal announcement messages: 
- Stage: Proof of Concept
  Stage: Proof of Concept
  State: Functional
  Notes:
  This system is intended to demonstrate Tealeaf capabilities only. This system
  should not be used for any functions other than demonstrating system
  functionality.

  For more information, contact your Tealeaf administrator. From the Portal
  menu, select Help > Contact Tealeaf Administrator.
- Stage: Development
  Stage: Development
  State: Functional
  Notes:
  This system is under construction. Users may experience problems using the
  system.

  For more information, contact your Tealeaf administrator. From the Portal
  menu, select Help > Contact Tealeaf Administrator
- Stage: Staging
  Stage: Staging
  State: Functional
  Notes:
  This system is currently being tested for production release. Please report
  any problems.

  For more information, contact your Tealeaf administrator. From the Portal
  menu, select Help > Contact Tealeaf Administrator.
- Stage: Production

Configuring the system time zone

During installation, the time zone is defined as the current time zone of the install machine. The System time zone can be changed using the TMS.

Tealeaf requires that a single time zone be defined across all servers in the system. For some functions, such as searching, the time zone might change the meaning of parameters such as today or yesterday. Among other features, this system-wide time zone is used as the basis for determining when scheduled reports are executed and delivered.

The system timezone is used in the following functions:

  • All reporting data is assigned a timestamp based on the global system time zone. For reporting purposes, a day and its hourly buckets are defined by the midnight-to-midnight interval in the global system time zone.
  • Event timestamps are recorded when the event occurred. Events may occur at the beginning of a session, on individual pages, and at the end of a session.
    • This precise timestamp improves the event count calculations, which are performed on an hourly basis.
    • If the session spans two hourly buckets, the events of the session may be spread across two different intervals. For example, if the event fires at 11:55 and the session ends at 12:05, search drilldowns look for sessions in the 11-12 bucket yet won't discover the specific session, which ended in a different hour. Reporting data is more accurate, but drilldowns may show discrepancies.
  • All completed sessions are still indexed at GMT. Tealeaf session and index data are aggregated on a daily basis, based on the GMT day. During search operations, the Search Server applies a time zone offset so that returned session data applies to your local time zone.

Notes about timezone

Tealeaf supports all Coordinated Universal Time (UTC) formatted time zones. The use of a time zone that is not defined as standard Coordinated Universal Time (UTC) time zone is not supported. Depending on your version of Windows™, the Portal may display the time zone indicator using either UTC or GMT. These indicators are present in the time zone displayed in the upper-right corner of the Portal and are present in any saved time zone data.

All time zone values for Tealeaf components and applications are calculated from the system time zone, except for Search Server. All sessions and canister data are stored using GMT timestamps, so no timezone references are needed for Search Server.

Individual users may set their local time zone. A user's time zone primarily affects searching for data.

For time zones that include Daylight Savings Time during the year, reporting values when the hour jumps forward show a gap of one hour while values when the hour jumps backward result in double-counts. Tealeaf administrators can use Portal Announcements to notify users of the time change and its effects.

During the installation process, the system time zone should be carefully considered and selected. After changing the system time zone on an actively processing Tealeaf system, some data may be lost when the next trimming of the canisters is performed. The volume of potentially lost data is the number of hours by which the time zone was shifted.

Time zones for search: For each user group, you may configure a time zone to applied when performing searches.

The search time zone overrides the Tealeaf time zone for purposes of resolving the day when a session occurred. For example, if you select to search for sessions that occurred "today," the returned sessions occurred since the start of midnight for your group or individual user time zone settings.

Group time zones

To change the time zone setting for a user group, you can follow the instructions for modifying language in this section. In the same location in the Portal Management page, the time zone setting for the group can be selected from the Default Time Zone (used in Search).

User time zones

To change the time zone setting for an individual user, you can follow the instructions for modifying language in this section.

In the same location in the Portal Management page, the time zone setting for the user can be selected from the Default Time Zone (used in Search). This setting overrides the group time zone setting for the user's primary group.

User-configured time zones

Individual users may configure their own time zone setting.

  • For Tealeaf solutions in which all servers are located in the same time zone, a configuration change might not be required.
  • Because Daylight Savings Time is shifted at 2:00 AM, no daily data is lost by shifting the time one hour forward or backward.

For a multiple-machine implementation that spans multiple time zones, all machines must roll at the same time. For example, if the processing server is in New York and another processing server is in Los Angeles, you must configure a single time zone that both machines recognize. Otherwise, operations such as searching within a specific time period can produce incorrect results.

Note: All Tealeaf servers must be configured to use the same roll time zone. Failure to synchronize on the same time system time zone can cause unpredictable behaviors.
  1. Login to the Portal as an admin user.
  2. From the Portal menu, navigate to TMS.
  3. In the Servers view, select the desired server to drill down to components.
  4. Select the component to display the configurations.
  5. Double-click Global configuration settings to open the Config Info dialog.
  6. Click Edit.

    The Configuration Editor is displayed.

  7. Click Roll Time Zone. Select the desired time zone from the list and then click Apply.
  8. Enter a description for the change in the Version Description field, and click Save to save the changes.
  9. If prompted to add tasks to push the new configuration, select all servers and click OK.
  10. To push the configuration change to the selected server, click Submit.

Synchronizing the time on Tealeaf servers

It is critical that the time on all Tealeaf servers be closely synchronized. All servers should be synchronized to a common source that is itself synchronized to a reliable master clock.

In the Control Panel of each Windows server, you can use the Date and Time applet to verify that the time zone, date, and time are set properly.

Servers automatically keep their clocks in sync with the clock on the domain controller to which the server connects. If the Tealeaf system does not belong to a domain, contact Support for assistance in configuring scripted or 3rd-party time synchronization solutions.

Synchronizing the PCA server time with the Transport Service time

Because the PCA server might not have access to the enterprise master clock, it should be configured to synchronize its time with the main Tealeaf Transport Service to which it connects.

The PCA server time is the most critical of the time settings. All PCA servers should be within a few seconds of each other. The PCA server creates the [timestamp] section of each request. The dates and times that recorded here are in GMT time.

  1. Log in to the PCA server using SSH and the root user ID.

    You can use the PuTTY program, often installed on the server hosting the main Transport Service in a data center.

  2. Run the datecommand , which displays the date, time, and time zone that is configured on the PCA server.

Configuring the timezone for CX RealiTea Viewer

You can configure the timezone for CX RealiTea Viewer. Typically, the RTV time zone matches the timezone of the RTV user.

  1. In RTV, select Tools > Options.
  2. Select the Replay tab.
  3. Select the correct time zone from the TimeZone drop-down.

Configuring the Login ID to be searchable

As part of the set of provided data objects, Acoustic Tealeaf includes a hit attribute and an event for detecting the Login ID displayed in your web application. You must configure data objects to detect the Login ID.

A hit attribute is used to define the patterns in request or response data that demarcate an element of data that you wish to track through an event.

An event is triggered by a condition. In this case, the condition is the presence of the Login ID hit attribute. When this hit attribute is detected, the event is fired, which stores the Login ID value as the first session attribute (Login ID).

Tealeaf supports the creation of up to 64 session attributes. A session attribute is a session-level variable that can be populated and updated based on events.

To enable these data objects, you must configure them to detect the Login ID's that are published by your web application. In this End-to-End scenario, you can complete the steps required to configure the Login ID hit attribute, event, and session attribute and then surface this data for use in search and search results.

To configure the Login ID to be searchable:

  1. Access the Event Manager.
  2. See the business use case for searchable login IDs..

Configuring dimensions

In Acoustic Tealeaf, you can configure predefined dimensions to track contextual information about the activities of visitors to your web application.

These predefined dimensions are the:
URL
The URL dimension identifies the URL of the hit.
Host
The host dimension identifies the host of your web application.
Application
The application dimension identifies the application name.
Server
The server dimension identifies the name of the server hosting your application.

When configured properly, values for these dimensions are captured in the Tealeaf pipeline and periodically logged to the database.

Using the Tealeaf Event Manager, you can map values for these dimensions to values that are useful for reporting purposes by creating whitelists of accepted values. For example, multiple URLs may be mapped to a single URL value: search.

To initialize the predefined dimensions:

  1. When the installation is complete, logging of these dimensions has been enabled. As traffic is being captured and processed by Tealeaf, applicable values for these dimensions are being logged into the Tealeaf database.
  2. These dimensions are initially configured to report from a whitelist of values, which means that the dimension reports from these whitelist values only. Upon installation, the whitelist is empty.

    Before you can begin using these dimensions, you must specify the whitelist of values, which can be gathered from the logs into which detected values are inserted. After installation, please wait one hour or a suitable period of time to gather a sufficient sample of values into the logs.

  3. To make changes to these dimensions, open the Tealeaf Event Manager.
    1. Login to the Portal.
    2. From the Portal menu, select Configure > Event Manager

      The Tealeaf Event Manager is displayed.

    3. Click the Dimensions tab.
    4. In the left panel, click the URL/Host/App/Server report group.

      The dimensions are displayed for editing.

Tealeaf also provides the following dimensions:
  • Connection Type
    Depending on the computed speed of traffic between visitor and web server, this dimension buckets the visitor's session into one of four connection types:
    • Dial Up
    • ISDN
    • DSL
    • T1
  • Content Type

    This dimension contains the value of the HTTP header for CONTENT_TYPE captured from the hit.

    If the header value begins with /text or /application, the reported value is Page. Otherwise, the value is set to unknown.

    No additional configuration is required.

  • Request Canceled

    If the hit was canceled by the visitor or the server, this value is set to true.

    No additional configuration is required.

  • Traffic Type
    This dimension identifies the type of user agent that is initiating the session. Possible values include Browser, Bot, and Mobile, among others.
    Note: Detection of user agents, including the type of traffic requirements deploying the Reference session agent in your Windows pipeline and enabling extended user agent parsing.

After a sufficient period has elapsed to capture a good sample of data for each dimension into the logs, you may specify the whitelists for each of the dimensions.

Optionally, you can configure the dimension to use a whitelist and observed values. This option allows values that are detected in the capture stream to automatically be made available for reporting purposes, in addition to any whitelist values you specify.

Note: Given the volume of URLs in the typical web application, configuring the URL dimension to whitelist + observed values is not recommended.

Creating deviations

Acoustic Tealeaf CX provides the capability of creating and storing standard deviation calculations for any selected event or dimension.

Standard deviation calculations, also known as movers, require several days of stored data (depending on configuration) before they can be used in actionable reports.

After installing Tealeaf CX, you might want to create some movers off of the events that already exist in Tealeaf.

Configuring session timeout settings

By default, Acoustic Tealeaf is pre-configured to time out sessions that grow too large, last too long, or are left idle for a period of time.

When these limits are exceeded, the Canister breaks the session into fragments, each of which is assigned the same TLTSID value.

The TLSessioning session agent continues to use the same TLTSID value for sessions that have timed out.

In the Services Controls tab of the Canister configuration, you can specify Session Size Limits, which define the maximum number of hits, size in bytes, or time per session.

Tealeaf also times out sessions that have been allowed to stand idle for a period of time. If no new pages are added to a session for a predefined period of time, the session is closed. If the visitor resumes browsing, a new session identifier is issued.

Changing top-level domains

If Acoustic Tealeaf is monitoring multiple top-level domains, a visitor who browses across the domains may generate a new TLTSID from the Tealeaf Cookie Injector.

For example, switching from www.site1.com to www.site2.com may cause the issuance of a new unique Tealeaf identifier, since the browser does not include www.site1.com in the first request to www.site2.com.
Cross-domain sessions may be stitched together if there is a known value present in the session when it jumps from one domain to the next. Possible solutions:
  1. You could add functionality to your Web applications to forward the TLTSID cookie value into the other domains to which the TLTSID cookie itself cannot be submitted by the browser. You could use JavaScript to set TLTSID cookies into the browser's cookie cache for the other domains.
  2. If a query parameter is inserted into the URL that can be searched and evaluated when the visitor exits one domain and enters the other, the session fragments may be stitched together using the TLSessioning session agent. For example, you could submit the TLTSID value in the query string of requests to other domains and modify the Web applications to consume that TLTSID query string value and to set a TLTSID cookie with that value from the Web or application servers.

Configuring session close events

You can configure Tealeaf events in order to close a session if an event condition is met.

For example, suppose a visitor is using an application to manage multiple customer accounts in a single session. You can define a session close event to close the session whenever the Close Account screen is reached for each customer that is being processed by the visitor. In this case, it is more appropriate to evaluate the dataset as separate sessions, instead of as a single visitor-centric session.

Session close events cause multiple sessions to contain the same TLTSID cookie. Sessions closed by events are not fragmented sessions and cannot be merged back together.

In Advanced Mode, session close events are configured using the JavaScript CloseSession function with a SessionCloseReason session property.

Configuring cycle services

To avoid possible operations problems, cycle the services on all Processing servers (Canisters) and Report servers once per day during off-peak hours.

Cycling services alleviates the following issues:
Space and memory issues
On the Processing server, Canister services use a lot of memory. At the end of the day, memory that is used for the Short-Term Canister can be highly fragmented and therefore less efficient. Recycling the services results in a defragmentation of the Canister memory automatically and ensures consistent performance in the Short-Term Canister.
Residual data and information
Cycling services flushes out any residual information about existing sessions and prepares the system for the next day.
Health checks on the Long-term Canister
On the Processing server, cycling services process also runs scripts through TLTMaint.exe to verify the integrity of the Long-Term Canister.

By default, the Scheduling service is configured to run a cycle services job on each Tealeaf server at 12:30 AM, local time.

All Tealeaf servers can be cycled at the same time. The Processing servers and Reporting servers are the most important servers to cycle on a daily basis.

If you deployed a Health-Based Routing server in your system, configure cycle services on the Processing servers so that the HBR always has a Processing server available to which to send hits. Otherwise, data might be lost.

Related articles

community icon

Join the community

Ask questions, share best practices, and connect with fellow marketers.

Ask a question

Academy

Read how-to articles, guides, and more to help you on the path to success.

Learn more