Troubleshoot the PHP microagent

This is a non-exhaustive list of troubleshooting strategies. If you need help, please email us at support@sqreen.com or contact us through our web chat.

Increase log verbosity

The Sqreen microagent logs messages to a text file. These messages contain warnings about possible abnormal behavior and describe some actions the microagent is executing. Increase the verbosity of these messages to help you troubleshoot issues with the Sqreen microagent.

Use two environment variables to configure Sqreen's log verbosity:

Env variable name Role Default value Options
SQREEN_LOG_LOCATION Specifies a custom file to which the microagent writes logs. the terminal custom file path
SQREEN_LOG_LEVEL Sets the microagent logging level. WARN or CRITICAL INFO, DEBUG

Use INFO level in production environments.

Use DEBUG only for short periods of time due to the amount of data it generates.

Deprecated application tokens

Problem: There is a problem with my application token.

Solution: Sqreen microagents used to use application tokens. These tokens were unique to an application. Sqreen has deprecated application tokens.

Sqreen now uses organization tokens. These tokens are available throughout the organization to which your account belongs.

While Sqreen continues to support application tokens for backward compatibility in the short term, we encourage you to convert your applications to use organization tokens.

Expired tokens

Problem: My organization token is not working. The error message reads 401 Unauthorized.

Solution: If your Sqreen plan expires, the microagent and the organization tokens remain in your app, but the microagent cannot authenticate with the Sqreen Platform anymore.

To resolve the issue, you can uninstall the Sqreen microagent from your app, or you can contact Sqreen to renew your plan subsciption. With a renewed subscription, your microagent will be able to authenticate with the Sqreen Platform using the same organization tokens.

phpinfo() page does not list the PHP extension

Problem: The phpinfo() page does not list the Sqreen extension.

Solution: There is a problem with the PHP configuration that prevents it from loading the Sqreen PHP extension. Refer to the Install manually documentation. You can retrieve the following information from the table:

  • the PHP extension version
  • the daemon version
  • the connection status between the extension and the daemon (on the Connected line, in the first section). The PHP extension and the daemon use TCP to communicate. The PHP extension connects to 127.0.0.1:7773 by default. The daemon listens on port 7773 by default (binding on 0.0.0.0)

phpinfo.png

A sqreen-agent process is not running

Problem: A sqreen-agent process is not running.

Solution: Run the following command to check that the process is running.

$ ps aux | grep sqreen
sqreen  19456   0,0  0,0  2522856   6656 s013  S+   Ven10     0:55.18 sqreen-agent
If it is not running, ensure that you installed the sqreen-agent and configured it to start automatically. Refer to Install manually for details.

User tracking is not working

Problem: User tracking does not appear to be working.

Solution: Ensure user tracking occurs within the HTTP request's context. If you use the Sqreen SDK for user monitoring to track user signup and login (signup_track or auth_track calls), ensure that the SDK makes these calls while the HTTP request is in progress.

The HTTP request contains required contextual information, and these calls fail silently, if they occur while not processing an HTTP request. For example, if you push user events to an asynchronous queue, and invoke the Sqreen SDK there, the calls fail silently.

User ID is only reported during an attack

Problem: Sqreen only reports the user identification during an attack.

Solution: This is expected behavior. The identify call in the Sqreen SDK only sends information to the Sqreen Platform during a request in which it detects an attack. By contrast, the signup_track and auth_track calls in the Sqreen SDK always send information to the platform.

Cannot locate source of error

Problem: I am having trouble determining what is causing errors.

Solution:

  • Check the PHP errors in the FPM or Apache logs for Sqreen-related entries.
  • Check the sqreen-agent logs which inform you that the agent started successfully:
    $ cat /var/log/sqreen/sqreen.log
    [INFO][2017-09-04 09:42:29,013 #15348.MainThread] sqreen-agent:91 Starting up on TCP socket 0.0.0.0:7773
    [INFO][2017-08-31 09:42:29,013 #15348.MainThread] sqreen-agent:104 Sqreen-agent successfully started
    
  • Check the agent debug logs. You can configure the agent to report debug logs:
    $ sqreen-agent --log_level=DEBUG
    [INFO][2017-09-04 09:42:29,013 #15348.MainThread] sqreen-agent:91 Starting up on TCP socket 0.0.0.0:7773
    [INFO][2017-08-31 09:42:29,013 #15348.MainThread] sqreen-agent:104 Sqreen-agent successfully started
    

PHP extension cannot reach the daemon

Problem: The PHP extension cannot reach the Sqreen daemon.

Solution: Run the following command from the PHP extension host to confirm the setup is correct. If you are using different hosts for the daemon and the PHP extension, replace 127.0.0.1 with the address and port of the host running the daemon.

curl 127.0.0.1:7773

  • Times out: If the command times out, the connection succeeded. Everything is running as expected and the daemon is listening.
  • Terminates: If the command terminates with a Connection refused error, this suggests that the host cannot join the daemon. Check your network configuration.

Application dependencies are not available

Problem: Application dependencies are not available in the Sqreen Dashboard.

Solution: Application dependencies are only available when installed through composer. More specifically, dependencies are obtained from the file vendor/composer/installed.json which the composer generates during the installation process.

PHP extension did not update

Problem: When I updated the microagent to the latest version, the daemon updated but not the extension.

Solution: Sometimes, the daemon updates, but not the extension. To pick up the latest version, redeploy your application.