Troubleshooting

This article describes some strategies for troubleshooting common problems you may encounter when setting up and running Webtrends software. It also provides information about common report viewing problems you may encounter whether you use Webtrends software or Webtrends On Demand.

Troubleshooting Software Upgrade, Installation, and Performance

The following sections discuss common problems that can occur during installation and describe how to resolve them. Webtrends provides built-in installation and performance checking for Webtrends software users. Checks include a full system check during installation and an alerting and monitoring system that alerts you when problems on your Webtrends installation computer(s) may lead to performance problems. These checks can diagnose many common performance problems. For more information about the system check, see “Installation Checking,” below For more information about alerting and monitoring, see “Alerting and Monitoring,” below.

Common Installation Problems

The following problems can occur during installation and can usually be resolved with simple configuration changes.

Services Will Not Start

If you install Webtrends but cannot launch the program, begin by checking Windows Control Panel to see if all the Webtrends services have started. All Webtrends service names begin with the prefix Webtrends -.

Services typically fail to start for one of two reasons:

• Depending on the user account you specified when installing Webtrends, you may not have appropriate rights to Webtrends services. During installation, you specify which user accounts to run services under. Keep in mind that the account(s) you select should have administrative rights on the local computer as well as rights to any network resources you want to use when running Webtrends. For example, if you plan to store web data files on another computer in the network and connect to the files using a UNC path, specify a domain account with rights to that location.
• Port conflicts can cause services to fail.

Port Conflict Reported

Webtrends uses ports to communicate with all the components in your installation. If you receive an error indicating a port conflict, or if your Webtrends services fail to start, you may be running another application that uses the same ports as Webtrends. We recommend using the default ports for the System Database and the User Interface Server when you install Webtrends. By default, the System Database uses the MySQL port (3306). Use port 1433 for a SQL Server installation. Webtrends v8.1 and higher uses Microsoft IIS port 7099 for the User Interface Server (previous versions used Apache). Other applications cannot share these ports. For more detailed information about ports, see the Webtrends Implementation and Maintenance Guide.

License Not for This Version

Because license keys are version-specific, you may receive a message during installation indicating that your license key does not apply to the current version. If your support contract is up to date, you can contact Webtrends Support for a new or updated key. Otherwise, you can contact a Webtrends Sales representative to purchase an upgrade.

Activate Product (No Connection to License Server)

After you complete your installation, Webtrends attempts to contact the License Activation Server using the Internet in order to verify your license key. If you see the Activate Product dialog box when you start the product for the first time (or after you try to add a license key), you may have a problem with your Internet connection that prevents Webtrends from contacting the License Server. The Activate Product dialog box gives detailed instructions for validating your license key on a computer that is not connected to the Internet.

Script Blockers Active/Cannot Create Database

During installation, you may see a message indicating that script blockers are enabled, or Webtrends may not be able to create the MySQL database. If you experience this problem, you must disable any script blockers before completing the installation.

Cannot Log in After Installation

You can log in using the same user name and password you use to log on to the local computer when you installed Webtrends.

Typically, this login is different from the user name and password you provided for the MySQL database during installation. The database login information is only used internally.

Cannot Access Visitor Intelligence

Upgrading to Marketing Lab v2.1 requires the Visitor Intelligence cube to undergo a complete reprocessing before you can use Visitor Intelligence reports. Please wait until cube reprocessing has finished before trying to access Visitor Intelligence.

Installation Checking

During installation, Webtrends checks the system resources and configuration of the installation computer. Webtrends checks for the following:

• Adequate CPU speed, system memory, and hard disk space for your installation of Webtrends
• Antivirus software that may conflict with Webtrends analysis
• Script blocking software that may conflict with Webtrends analysis

The system resources check makes sure you install Webtrends on a computer that can handle Webtrends analysis for a Web site in production. If your system resources are insufficient, or if you have installed software that conflicts with Webtrends analysis, you may not be able to install Webtrends. Keep in mind that this check is meant to detect computers with that have a high probability of failing in production, and does not guarantee that your computer can handle the demands of running Webtrends for a site with heavy traffic. You should consider how many page views your Web server logs and review the Webtrends system requirements before choosing a computer to run Webtrends.

Alerting and Monitoring

The Administration module monitors your Webtrends computers for the same problems covered by the installation check as well as other error conditions and problems. If one of your computers develops a condition such as insufficient memory that can cause a performance problem, Webtrends shows the Active Alerts page when an administrator (or a user with rights to the Administration module) starts Webtrends or logs in to Webtrends Administration.

Using the Active Alerts Interface

The Active Alerts interface lists all alerts that are active. Alerts are active until you acknowledge or defer them. When an alert is active, Webtrends takes any actions associated with the alert, such as showing the Active Alerts page on startup or stopping analysis, and continues to show the alert in the Active Alerts dialog box until it is acknowledged or deferred.

Conditions that Webtrends Monitors

The following table shows the types of conditions that Webtrends monitors for alerting, as well as the default actions Webtrends performs when the condition occurs. Users with rights to the Administration module can modify these responses using the Alert Configuration dialog box.

Resolving Alerts

When you receive an alert, you can acknowledge it or defer it. Acknowledging an alert removes it from the Active Alerts list, but the next time Webtrends checks for the alert condition, a new alert will be generated unless you have fixed the problem. Deferring an alert removes the alert from the Active Alerts list and prevents Webtrends from generating a new alert for the next 24 hours.

Resolving Alert Conditions

You can use the following suggestions to solve problems diagnosed by Webtrends alerts.

Anti-Virus

We recommend disabling anti-virus programs on your Webtrends computers because virus scanning can lock files that Webtrends needs. If the anti-virus program locks even a few files during a Webtrends analysis, Webtrends’ inability to write to these files can cause analysis to be incomplete and fail. Although the presence of anti-virus software does not guarantee a failure, running anti-virus and Webtrends on the same computer is not recommended.

Rather than disable virus scanning, you can configure the program not to scan log files, data files, or configuration files. (Depending on your Webtrends installation, some of these files may be located on network drives or, in a distributed installation, on other computers.) However, anti-virus software can safely scan Webtrends executables.

Although you can set your anti-virus program to run when Webtrends is not analyzing data, or to exclude the directory where Webtrends is installed, Webtrends generates alerts based on whether anti-virus is running on the same computer as Webtrends. You can use the Alert Configuration dialog box to change the default response to anti-virus scanning.

Disk Space

To resolve disk space problems, you can obviously add hard disk space to your computer. You can also modify several settings to decrease the disk space required by analysis and by report storage.

To decrease the disk space required by analysis:

1. In the left pane, click Administration > Application Settings > System Management > Role Settings.
2. Click Scheduler.
3. Reduce the value in the Concurrent Tasks for agent text box. This value specifies how many analysis tasks the agent on a computer can run at the same time. Running multiple tasks requires extra disk space.
4. Click System Management > Global Roles and select Standard Analysis Engine.
5. Reduce the Pre-Analysis Disk Usage Target setting. This setting determines how much disk space is occupied by the analysis cache before it is trimmed.

To decrease the amount of disk space used to store report database:

1. In the left pane of Administration, click Application Settings > System Management > Retention >Report.
2. Adjust the number of weekly, monthly, quarterly, and yearly reports Webtrends stores.

Memory

If you continually receive alerts about memory usage on the same computer, the computer may not have enough memory. One solution is to add memory to that computer, or to install Webtrends on a computer with more memory. You can also change Webtrends settings to lower memory usage.

To lower Webtrends memory usage, you can decrease the number of concurrent tasks enabled. You can also adjust profile settings to minimize memory-intensive operations like DNS lookups, GeoTrends database reporting, and large numbers of custom reports, and to limit tables that consume especially large amounts of memory. For more information about table limiting, see “Optimizing Reports Using Table Limiting.”

To decrease the concurrent tasks for a computer:

1. In the left pane, click Administration > Application Settings > System Management > Hosts.
2. Click View Role Settings for the computer you want to modify.
3. Click Scheduler.
4. Reduce the value in the Concurrent Tasks for agent text box. This value specifies how many analysis tasks the agent on a computer can run at the same time. Running multiple tasks requires extra memory.

If the computer’s operating system allows it, you can also add memory by enabling the /3GB switch in the boot.ini file to allocate 3GB of memory to Webtrends. For more information about enabling the /3GB switch, see the Microsoft Knowledge Base article “Memory Support and Windows Operating Systems” at http://www.microsoft.com/whdc/system/platform/server/PAE/PAEmem.mspx

You may also have one or more profiles that require too much memory, especially if you receive a memory alert for more than one computer. To check for profiles that consume large amounts of memory, check the status history for the analysis job to see if the time of the alert correlates with a particular profile. For more information about checking status, see “Checking Analysis Status,” below. If you find that a particular profile is causing the problem, modify the profile configuration to reduce memory consumption. To reduce memory usage, try lowering table limits, reducing the number of custom reports, adjusting the Internet Resolution settings, and limiting Visitor History data collection.

CPU Count

To improve the ratio of tasks to CPUs, lower the number of concurrent tasks enabled on this computer. For best performance, you should not enable more than two concurrent tasks per processor. However, before you enable even two concurrent tasks, you should determine whether you have sufficient memory.

To decrease the concurrent tasks for a computer:

1. In the left pane, click Administration > Application Settings > System Management > Hosts.
2. Click View Role Settings for the computer you want to modify.
3. Click Scheduler.
4. Reduce the value in the Concurrent tasks per agent text box. This value specifies how many analysis tasks the agent on a computer can run at the same time. Running multiple tasks requires extra system resources.

Script Blocker

You must disable any script blocking applications for Webtrends analysis to run. If you begin an analysis with script blocking enabled, analysis will fail.

Custom Reports

To resolve the alert condition and avoid memory problems during analysis, reduce the number of custom reports to no more than 30 per profile.

To reduce the number of custom reports per profile, you should distribute the reports among two or more profiles. You can do this by copying the original profile, disabling some of the custom reports in the original profile, and enabling those reports in the copy or copies. Make sure that any custom reports you want to include for a profile are enabled both in the report template associated with the profile and in the Advanced > Reports dialog of the profile settings.

Page View Limit

To resolve the alert condition, contact a Webtrends Sales representative to add a license that authorizes more page views per year.

To obtain a license for more page views, contact your Webtrends Sales representative or your reseller. When counting page views for licensing purposes, Webtrends counts all hits as page views except:

• Hits to .bmp, .css, .gif, .jpeg, .jpg, .js, .png, .dtd, or .wbmp files
• Hits generated by Webtrends itself, such as sample data or HTML page title retrieval
• Hits that were counted in a previous analysis

Failed Scheduled Job

A failed scheduled job can have any number of causes, such as failed connectivity or profile configuration problems. You can find more information about what caused the problem by checking the detailed job status. For more information, see “Checking Analysis Status,” below.

Stalled Scheduler

A problem with a stalled Scheduler means that no jobs can run. To resolve this problem, make sure that at least one computer has a Scheduler Agent running and is configured to schedule tasks. Click Administration > System Management > Hosts to check the Scheduler Agent status. You can restart the Scheduler Agent service in the Windows Services panel. Also, check the Job Queue to make sure there are no long running tasks that are blocking other jobs from executing. To access the Job Queue, click Scheduler > Job Queue. If one long-running job is blocking other jobs, you can cancel that job to allow other jobs to run. For more information about troubleshooting analysis, see “Checking Analysis Status,” below.

Stalled Scheduled Job

Stalled scheduled jobs can also block analysis. To resolve this problem, make sure that at least one computer has a Scheduler Agent running and is configured to schedule tasks. Click Administration > Application Settings > System Management > Hosts to check the Scheduler Agent status. Also, if the job is assigned to a host group, make sure that there is at least one active computer in the host group. You can check which host group a job is assigned to by editing the scheduled job in the Scheduled Jobs dialog box and selecting Host Binding. For more information about troubleshooting analysis, see “Checking Analysis Status,” below.

Stalled Visitor Data Mart Profile

This alert occurs when a Visitor Data Mart profile has stopped importing log data into the Event Database. To resolve the problem, ensure that the Event Database Loader and the SQL Server are both running. To check the status of the Event Database Loader, click Administration > Application Settings > Monitoring > Service Health. To make sure the SQL Server is running, check the Windows Services panel on the computer where the SQL Server component is installed, and ensure that the Webtrends Event Database SQL Server is started.

If your log files are stored on a network share, make sure that the Event Database Engine service is configured with the appropriate user rights to access the log files. For more information about the required rights for Webtrends services, see “Services Will Not Start,” above.

Stalled Express Analysis Profile

This alert occurs when the Express Analysis Engine has stopped importing log data into the database. To resolve the problem, ensure that the Express Analysis Engine is running. If your log files are stored on a network share, make sure that the Event Database Engine service is configured with the appropriate user rights to access the log files. For more information about the required rights for Webtrends services, see “Services Will Not Start,” above.

Product Update

To resolve this alert, download the updates described in the alert.

Checking Analysis Status

If you have problems with Webtrends analysis that are not diagnosed using Alerts, a logical next step is to use the Scheduler to check on your analysis. You can get a general idea of how your analysis ran by looking at the status icon for each profile in the Web Analysis module. However, for deeper insight, you should check the job status details and the Job Queue.

To begin troubleshooting an analysis problem:

1. In the left pane, click Administration > Scheduler > Scheduled Jobs.

2. Click View Job Detail next to the analysis job you want to track. The detailed status shows information about the progress of the job, including any errors that were generated while the job was running. If a job fails, detailed status often provides information about the reason for failure and the task that was occurring when the analysis failed.

3. If the detailed status indicates that the job did not fail or complete, click Job Queue in the left pane. The Job Queue provides information about any tasks that were added to the queue. If you have more than one job running, the Job Queue can tell you which tasks have the highest priority and which tasks are waiting. You can also use the Job Queue to cancel any tasks that are queued.

4. If the Job Queue indicates that your job is still not complete, you may want to check your Analysis Throttling settings. Analysis Throttling breaks your data into manageable pieces and analyzes them one at a time to avoid excessive resource consumption. By default, Webtrends updates the report after each segment of data is analyzed. However, if Analysis Throttling is not set to update the report, Webtrends may continue processing for a long time without generating a report. To adjust the Analysis Throttling settings, click Web Analysis > Options > Analysis in the left pane and click Analysis Throttling. We recommend setting Webtrends to analyze a maximum of 1 day, rerun analysis immediately after the maximum amount of data is analyzed, and update report data between each analysis period.

5. If your job was never added to the queue at all, you may want to check the status of your Webtrends services. You can view the status of all your Webtrends services using the Service Health dialog box. To access this dialog box, click Application Settings > Monitoring > Service Health in the left pane of Administration. You can also use the Service Health dialog box to start and stop all the services except the Webtrends Scheduler. To restart the Scheduler if it is stopped, use the Windows Services panel.

6. If you still cannot diagnose the problem, you may want to adjust the debug level and retry the analysis before calling Technical Support. This can provide additional information in your error logs that can help determine the source of the issue. For more information about locating your error logs and adding debug information, see “Checking the Error Logs,” below.

Configuring Server Localization Preferences

If the operating system of your Webtrends server is not set to a language that uses double byte characters and you are trying to view a report in one of these languages, some characters in graph labels may not render properly.

To set your server to render all characters properly:

1. Open the Regional and Language Options dialog in the Windows Control Panel.
2. Click the Languages tab.
3. Select Install files for complex script and right-to-left languages.
4. Select Install files for East Asian languages.
5. Click OK.
6. Reboot the server.

Checking the Error Logs

If you have a problem that needs further investigation, a Webtrends Support representative may ask you to check the error logs or zip them up and email them to Support. As of Webtrends v7.1, error logs have been consolidated into the following directory:

installation directory/logs

To log additional troubleshooting information before contacting Support, you can adjust the debugging level and try repeating the procedure to collect more information about the problem.

To adjust the debugging level:

1. Open the installation directory/storage/config/wtm_wtx.ini file.
2. Set the debuglevel value to 15 and save the file.
3. Use the Windows Services panel to restart the Webtrends Scheduler service.