CloudLinux OS+

X-Ray

Description

Warning!

X-Ray is available out of the box for cPanel, Plesk, and DirectAdmin. For other control panels you should implement integration as described here

X-Ray is a tool developed for website performance monitoring and performance issues detection.

X-Ray can gather and visualize information about top N slowest system functions, external requests, software modules and database queries of the client’s website.

Installation

Make sure you have CloudLinux OS+ subscription (only non-reseller accounts apply)
Make sure you have installed LVE Manager version 6.2 or later. You can install or update it with the following commands:
- installation
```
# yum install lvemanager
```
- update
```
# yum update lvemanager
```
X-Ray will be activated on all your servers during 4 hours. You will see the X-Ray tab in the LVE Manager UI.
For instant activation, run the following command:
```
# rhn_check
```
If the rhn_check command is not found, run the following command:
```
# yum install rhn-check rhn-setup
```
Then install the alt-php-xray package
- Via user interface
  - Go to the X-Ray tab.
  - Click Install to start installation.
- Via SSH by running the following command:
```
# yum install lvemanager alt-php-xray
```
After installation, use the Start tracing button to create your first tracing task for a slow site.

How to manage X-Ray

X-Ray provides two options for monitoring domain requests speed: Tracing task and Continuous task.

Warning

To use Continuous task, update your LVE Manager and alt-PHP-X-Ray packages to versions lvemanager-6.2.9-1 and alt-php-xray-0.2-1 by running the following command:

yum update lvemanager alt-php-xray

Tracing task is a task created manually for a specific URL to collect server requests. The task will end either after a specified number of requests to the URL or after a specified time (maximum after two days). It is not possible here to automatically email a report but it is possible to export the report in PDF and send to a user.
Continuous task is a task that initiates a daily hourly tracing requests for a specified domain and email a monitoring report. Continuous task can't stop automatically, you need to stop it manually.

In fact, continuous task allows to automatically create a tracing task for each new day, with the ability to get a report for the past day.

Tracing tasks tab

The Tracing tasks tab contains a list of all tracing tasks created both manually and automatically via continuous tasks.

The Created column shows how a task was created – automatically (by continuous task) or manually.

Continuous tracing tab

Warning

To use Continuous task, update your LVE Manager and alt-PHP-X-Ray packages to versions lvemanager-6.2.9-1 and alt-php-xray-0.2-1 by running the following command:

yum update lvemanager alt-php-xray

The Continuous tracing tab contains a list of continuous tasks for which tracing tasks will be created automatically for a new day for a specific domain.

Managing tracing task

Creating a new tracing task

Go to the X-Ray tab
Click the Start tracing button to create a new task
In the opened popup specify a website URL to trace
Click the Run button
Tracing will run in the default mode. In the default mode X-Ray traces the first 20 requests for a specified URL

URL should be a valid URL of the domain which exists on the current hosting server. The URL field supports wildcard matching. To learn more about wildcard matching, click How to use special characters.
Advanced settings allow you to set an IP address and tracing options: by time or by number of queries.

Advanced settings

Client’s IP: it is an IPv4 address of a machine to trace. For example, if you have a production website that processes requests from different IP addresses and you do not want to add these requests to the tracing task. So, you can set a specific IP address and X-Ray will analyze requests only from this specific IP address. Record for
Time period: how much time X-Ray collect the requests (2 days max)
Requests: the amount of requests that X-Ray will collect

After creating, the task appears in the list of tracing tasks.

Viewing tracing tasks list

Tasks created Manually are simply tracing tasks.

Tracing status

A tracing task can have the following statuses:

Running – tracing is in progress
Stopped – tracing was stopped by administrator
On hold – the same URL already exists in the lists. Task processing will not start automatically. Administrator should start it manually.
Completed – period of time is finished or number of requests is reached.

Collected requests for tracing task

Warning!

Collected requests are available in the UI for two weeks.

Click to open a list of collected requests.

Tracing tasks

The slowest request is highlighted.

Total displays how many requests were collected according to tasks requirements.
Pending displays how many of collected requests are not visible in the table yet.
Throttled displays the number of requests during the execution of which the LVE limits were exceeded.
Slow displays the number of requests lasting more than one second.

There are filters for the request types and the indicator of a filter used now.

If slow requests were not detected during the tracing task, the following is displayed. Here, you can also view all requests.

X-Ray collects the following data for each request:

Top issues – the slowest items of a request
Software modules/plugins by execution time (only for WordPress plugins)
Database queries by execution time
External requests by execution time
Other system functions by execution time

Software modules/plugins

The Software modules/plugins section displays the following data:

Software type – a type a module/plugin. For now, X-Ray can analyze only WordPress software
Software module – a name of the WordPress plugin
Duration – plugin execution time
Duration (%) – plugin execution time as a percentage of the total duration of the request

Database queries

The Database queries section displays the following data:

Query – the executed SQL-query
File – the file and the line of the executed query and backtrace
Software module – a WordPress plugin name from which the request was completed. If the request does not belong to any of the WordPress plugin, the name of the function that executed the given request is displayed
Calls – the number of identical SQL queries
Duration – execution time as a percentage of the total duration of a request and the function processing time (in brackets)

External requests

The External requests section displays the following data:

URL – the URL of the executed request
File – the file and the line of the executed request and backtrace
Duration – execution time as a percentage of the total duration of a request and the function processing time (in brackets)

System functions

The System functions section displays the following data:

Function – the executed function
File – the file and the line of the executed request
Duration – execution time as a percentage of the total duration of a request and the function processing time (in brackets)

Stopping tracing task

Click to stop the tracing task.

The tracing task status will be changed to Stopped. Data will not be collected anymore but you can see already collected information or continue tracing later by clicking .

Deleting tracing task

Click to delete the tracing task.

Warning!

When you have deleted a tracing task, all collected data will be unavailable.

Managing continuous tasks

Creating a new continuous task

Click the Create continuous tracing button

Specify URL in the Domain field and email in the Email for reports field and click the Create button.

You can see a new task in the Continuous tracing tab in the X-Ray UI.

If you stop a continuous tracing task, a new task for the next 24 hours will not be created. The task for the current day will be finished at midnight and the report will be emailed.
If you delete a continuous tracing task, the task for the current day will be finished at midnight and the report will be emailed.

Viewing continuous tasks list

You can find a list of continuous tracing tasks in the Continuous tracing tab.

You can find automatically created tasks in the Tracing tasks tab marked as Automatically in the Created column.

The statuses for automatically created tasks are the same as for tracing task.

To view detailed info about an automatically created task, click . You will get requests grouped by hour.

Click to a group to open a list of the requests.

The following data is collected for each request:

Software modules/plugins by execution time (only for WordPress plugins)
Database queries by execution time
External requests by execution time
Other system functions by execution time

Stopping automatic tracing task

Stopping automatic tracing task (a part of continuous tracing task) affects only the automatic tracing task for the current day. A new task for the next day will be created at the end of the day.

To stop the continuous tracing task completely, see Creating a new continuous task, paragraph 4.

Deleting automatic tracing task

Deleting automatic tracing task (a part of continuous tracing task) affects only the automatic tracing task for the current day. A new task for the next day will be created at the end of the day.

To delete the continuous tracing task completely, see Creating a new continuous task, paragraph 5.

Continuous task daily report

Users get daily reports on their emails. An example of a report is shown below:
Click the link in the email to show the detailed report:
You can view requests grouped by hour:
You can also view the detailed information about request:

End-user X-Ray plugin

Warning

To use the end-user X-Ray plugin, update your LVE Manager and X-Ray packages to the lvemanager-6.3.9-1 (or later) and alt-php-xray-0.3-1 (or later) by running the following command:

# yum update lvemanager alt-php-xray

How to enable/disable the end-user X-Ray plugin

You can hide or show the end-user X-Ray plugin icon by ticking or unticking the proper checkbox in the LVE Manager.

Go to LVE Manager → Options Tab → User interface settings.

Note

The X-Ray plugin icon in the end-user interface is hidden when the checkbox is ticked.

How to manage the end-user X-Ray plugin

The web interface of the end-user X-Ray plugin is almost the same as the X-Ray administrator interface.

But there are some differences and they are described further.

End-users can create tasks only for their domains from the drop-down list:
To specify URL or wildcard, end-users should use the input field next to the domain:

You can read about all other basic interface elements and managing tracing tasks in the Managing tracing task section.

Note

Tracing tasks created by an end-user will also be displayed in the administrator interface and administrators can manage the end-user's tasks the same way as they manage their own. At the same time, tasks created by the administrator or other end-users will not be displayed in the UI of the current user.

End-user X-Ray plugin limitations

The end-user X-Ray plugin does not support creating continuous tasks.
The end-user has a limit of tracing tasks running at a time. Before starting the next task, the end-user should wait for the completion of the previous ones or forcefully stop the running ones. Otherwise, the user will get the next error:

Note
The current limit is one tracing task per user.
The administrator and the end-user can’t run the tracing task for the same Domain/URL at the same time. Once, the administrator started a specific tracing task, the end-user will not be able to duplicate it. And the same is true for the administrators – they will just see the running task for the specific domain and see the notification that they're trying to create a tracing task with a duplicated URL.
If continuous tracing is enabled for the domain, the end-user will not be able to create a new task for this domain because the same rule works - it will be a duplicate of the existing tracing tasks. The next warning will appear:

To solve this, the existing running tasks for the same Domain/URL should be stopped or completed. You can find more details about this in the FAQ.
If a user's tracing task was created for a domain which is using the FPM handler there's an additional limitation. To avoid frequent reloads of the particular FPM service, Start tracing , Stop tracing or Continue tracing action would be blocked in case if the latest reload of a corresponding FPM service was done less than 1 minute ago.
If a user gets such an error message - it means that 1 reload in 1 minute for a particular FPM service has been already done. Just try performing the same operation once again in a while.

X-Ray automated throttling detection

The X-Ray automated throttling detection system checks if the account exceeds LVE limits by CPU during the HTTP request execution.

If CPU limiting was detected for a particular request, it is indicated in the X-Ray UI that the system itself has slowed down the request processing and this is apparently not a performance issue in the PHP code.

Requests with exceeded LVE limits are indicated in the administrator/user interface of the X-Ray plugin in the following way.

Requests with exceeded LVE limits are also marked if the administrator views the request.

Requests with exceeded LVE limits are marked in the PDF report as well.

X-Ray client

X-Ray client is a PHP extension named xray.so. It analyzes the processing time of the entire request and its parts and then sends the data to the X-Ray agent.

List of supported PHP versions

The list of currently supported PHP versions:


ALT PHP:	EA PHP:	Plesk PHP	DirectAdmin PHP	Other panels PHP
alt-php54 alt-php55 alt-php56 alt-php70 alt-php71 alt-php72 alt-php73 alt-php74	ea-php54 ea-php55 ea-php56 ea-php70 ea-php71 ea-php72 ea-php73 ea-php74	php54 php55 php56 php70 php71 php72 php73 php74	php54 php55 php56 php70 php71 php72 php73 php74	54 55 56 70 71 72 73 74

Warning!

php-zts and custom PHPs, rolled in selector, are not supported

Functions that X-Ray client can hook

Database queries

Functions from the MySQL extension:
- mysql_query
- mysql_db_query
- mysql_unbuffered_query
Functions from the MySQLi extension:
- mysqli_query
- mysqli::query
- mysqli_multi_query
- mysqli::multi_query
- mysqli_real_query
- mysqli::real_query
Functions from the PDO extension:
- PDO::exec
- PDO::query
- PDOStatement::execute

External requests

Function curl_exec

System PHP functions

It may be any PHP system function which can be related to a PHP engine or other PHP extension, for example fopen() or json_encode(). A list of these functions can be found here.