Related pages:

If you are instrumenting a PHP CLI Application with the AppDynamics PHP Agent, after installing the agent you need to take a few additional configuration steps described here. 

Instrumenting PHP CLI Applications

When instrumenting a PHP CLI application, you need to provide for the startup of the proxy daemon, as follows: 

  1. Create the proxy control directory, which is used for agent/proxy communication.
  2. In your PHP configuration file—php.ini or appdynamics_agent.ini depending on your environment. Include the following settings:
    • agent.cli_enabled = 1
    • agent.auto_launch_proxy = 0
    • agent.proxy_ctrl_dir  = <proxy control directory>
      If you are using the RPM installer to install the agent you may have configured the proxy control directory using the APPD_PROXY_CTRL_DIR environment variable. See Install the PHP Agent by RPM. This environment variable takes precedence over the setting in the ini file.

  3. Before running any traffic through the CLI, run the proxy from the directory into which you installed the PHP agent, passing the proxy control directory and proxy log directory as arguments.

    proxy/runProxy <proxy_control_dir> <log_dir>

    For example:

    proxy/runProxy /tmp/proxy.communication /tmp/agentLogs

For the full set of options to runProxy, see Start the PHP Agent Proxy Manually.

If you have PHP CLI applications and an Apache web server on the same machine, your setup depends on whether you want all the traffic reported against a single AppDynamics node or separate nodes. A separate proxy is required for each AppDynamics node that you want to monitor in the controller.

If you want all the CLI traffic to be reported against one node and all the web traffic to be reported against a different node, configure Apache to auto-launch the proxy (the default) and configure CLI to use a manually-launched proxy. This requires separate .ini files—one for the web PHP with agent.auto_launch_proxy set to 1 and another for PHP CLI with agent.auto_launch_proxy set to 0.

If you want the web traffic and the CLI traffic to be reported against the same node, configure both Apache and CLI to use the same manually launched proxy.

Long-Running CLI Applications with the Suhosin Patch

A side effect of the Suhosin patch is that it prevents the PHP Agent from ensuring cleanup in long-running CLI applications.

If your PHP has the Suhosin patch, it is possible that resources will not be freed in long-running applications. Thus memory leaks could result if the application itself does not explicitly free these resources.

The long-running-cli feature defends PHP applications in an environment in which both of the following conditions exist:

  • PHP with the Suhosin patch is running on Debian or Ubuntu. It is common for Debian and Ubuntu PHPs to have this patch. 
    This feature is not needed for PHPs with only the Suhosin extension, which is different from the patch. Be aware that some PHPs use both the extension and the patch.
  • Using the PHP Agent API, you are instrumenting a CLI application that has multiple unbounded business transactions running on the same process,

How the Long-Running CLI Feature Works

At installation time, if the installer determines that PHP has the Suhosin patch and CLI is enabled—agent.cli_enabled=1—the value of the installer option results as follows: 

  • If true, a fatal error is generated and the installer terminates. With the option set, the installer refuses to instrument a long-running CLI application on a PHP installation with the Suhosin patch.
  • If false—the default—the installation continues and warns that memory leaks could occur in long-running CLI processes.

If the installer determines that PHP does not have the Suhosin patch, the installation continues. Long-running CLI processes are supported by the agent, since there is no Suhosin patch.

If the agent could not determine whether your PHP has the Suhosin patch at installation but it does detect the patch at runtime, having set the installer option to 'true' prevents the agent from instrumenting any CLI  processes, not just long-running ones. This prevents the Suhosin-patched PHP from exiting.

If CLI is enabled and the installer did not terminate because of the detection of the Suhosin patch, AppDynamics recommends that you install the agent with the enable-cli-long-running option—shell script installs—or the APPD_CONF_CLI_LONG_RUNNING_ENABLED environment variable —for RPM installs—set to true. This will defend your PHP if the patch is detected at runtime.

If the CLI part of your application does not get instrumented, because the installer detected the Suhosin patch, you can unset the option by setting the agent.cli_long_running option in the PHP ini file to off. Or alternatively, you can re-install with the installer.