Configuration (legacy agent)

The following content pertains to configuration for the legacy AppOptics PHP Agent.

AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider migrating to SolarWinds Observability.

If you have already transitioned to the new SolarWinds Observability PHP Library, see the SolarWinds PHP Library documentation for configuration information.

SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.

The configuration files used by php can be listed by running php --ini. Note that this will give the command-line-specific files on some distributions, denoted by /cli/; web systems on the other hand use the /cgi/ configs. For most platforms, you’ll find an appoptics.ini configuration file after installing the instrumentation module.

How to set configuration

All configuration options can be set in the INI file(s) used by your PHP installation, in most cases there will be an appoptics.ini file under your PHP configuration load path added during agent install.

You must restart the web server or PHP process in order for any changes to take effect.

Certain configurations can also be overridden via a system environment variable. If the same configuration is set in both places (for example, service key in both system environment variable APPOPTICS_SERVICE_KEY and appoptics.ini appoptics.service_key), then the setting is applied with this precedence:

System Environment Variable > Configuration in INI File

Report backtraces

Many public API methods have a backtrace parameter, which is set to ‘true’ by default.

Suppress reporting for sensitive data

PHP instrumentation has the ability to sanitize sql database queries in case you don't want query parameters displayed in your account. By default this functionality is enabled, but you can use the enable_sanitize_sql option to configure the instrumentation to start collecting and reporting query parameters.

appoptics.enable_sanitize_sql = 0

Complete configuration options

The following is the complete list of instrumentation configuration options.

Service Key

config option: appoptics.service_key

system environment variable: APPOPTICS_SERVICE_KEY

description: The service key is required. It identifies the service being instrumented within your Organization. It should be in the form of <api token>:<service name>.

Since version 3.1.0 the <service name> part of this option can be changed at a per-directory or virtualhost level. Example on how to change the service name for different vhosts in httpd.conf:

Listen *:3080
<VirtualHost *:3080>
  php_value appoptics.service_key 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:vhost-3080
</VirtualHost>
Listen *:3081
<VirtualHost *:3081>
  php_value appoptics.service_key 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:vhost-3081
</VirtualHost>

Nginx example:

server {
  listen 80;
  server_name host.domain.com
  location ~\.(php|html)
  fastcgi_param PHP_VALUE  "appoptics.service_key={API_TOKEN}:{SERVICE_NAME}";
}

history: Introduced in version 3.0.0

example: appoptics.service_key = 0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service

Tracing

config option: appoptics.tracing

description: Specify whether tracing and metrics should be initiated for incoming requests to the service. See Transaction Settings File on how to set this at a transaction level.

possible values:

enabled: (Default) Continue or start a trace, and report metrics.
disabled: Never continue or start traces, nor report metrics.

history: Introduced with the original instrumentation.

example: appoptics.tracing = enabled

Debug Level

config option: appoptics.debug_level

description: Logging level to adjust the logging verbosity. Increase the logging verbosity to one of the debug levels to get more detailed information added to the agent logs.

possible values:

-1: disable
0: fatal
1: error
2: warning (the default)
3: info
4: debug low
5: debug medium
6: debug high

history: Introduced in version 3.0.2

example: appoptics.debug_level = 6

Hostname Alias

config option: appoptics.hostname_alias

description: An optional logical/readable hostname that can be used to easily identify the host.

history: Introduced in version 3.0.2

example: appoptics.hostname_alias = apm-host-east

Max Transactions

config option: appoptics.max_transactions

description: The maximum number of transaction names to track when aggregating metric and histogram data by individual service transaction within the metrics flush interval. Changing this value will have a noticable impact on the used memory and can help reduce the memory footprint of the agent. Default is 50.

history: Introduced in version 3.0.11

example: appoptics.max_transactions = 100

Max Ready Wait Time

config option: appoptics.max_ready_wait_time

description: The maximum wait time (in milli seconds) for AppOptics to become ready for receiving traces. A value of 0 will turn off waiting which ensures AppOptics won't block the app on startup. Default is:

0 ms (off), for non-CLI usage, e.g. Apache, Nginx (PHP-FPM)
2000 ms, for CLI usage (see Enable CLI)

history: Introduced in version 3.2.0

example: appoptics.max_ready_wait_time = 500

Max Flush Wait Time

config option: appoptics.max_flush_wait_time

description: The maximum wait time (in milli seconds) for flushing data before terminating the app. A value of 0 will turn off flushing which ensures AppOptics won't block the app on termination. Default is 5000 ms.

history: Introduced in version 3.2.0

example: appoptics.max_flush_wait_time = 2000

Sanitize SQL Mode

config option: appoptics.enable_sanitize_sql

description: Instrumentation has the ability to sanitize query literals from sql statements. By default this is enabled and the agent removes literals by automatically trying to determine the quoting character used. Set to one of the other options to change the sanitization mode, or to disable.

possible values:

0: Disable SQL sanitizing.
1: (Default) Enable SQL sanitizing and attempt to automatically determine which quoting form is used.
2: Enable SQL sanitizing and drop double quoted characters.
4: Enable SQL sanitizing and retain double quoted characters.

history: Introduced in version 0.4.7.

example: appoptics.enable_sanitize_sql = 0

Enable Error Callback

config option: appoptics.enable_error_callback

description: By default the extension reports all errors to AppOptics, obeys the ‘@' suppression operator, and uses the instrumentation default error reporting level. To direct the instrumentation not to send any error data at all to AppOptics set this INI directive to 0.

possible values:

0: Disable error reporting.
1: (Default) Report all errors to AppOptics.

history: Introduced in version 1.3.2.

example: appoptics.enable_error_callback = 0

Report Suppressed Errors

config option: appoptics.report_suppressed_errors

description: PHP features the @ operator which overrides the global error reporting settings and suppresses errors for any expression it precedes. By default the instrumentation also ignores these suppressed errors. To report them—as long as they occur at the current error reporting level—set the following INI directive to 1.

possible values:

0: (Default) Honor the @ operator, which suppresses errors.
1: Report suppressed errors.

history: Introduced in version 1.3.2.

example: appoptics.report_suppressed_errors = 1

Use Error Reporting

config option: appoptics.use_error_reporting

description: PHP error reporting levels are controlled in two ways, by altering the error_reporting directive in php INI files, or at run time via the error_reporting function. By default these have no effect on how the instrumentation reports errors to AppOptics. By default the instrumentation reports all errors except E_STRICT and E_DEPRECATED, regardless of the aforementioned settings that your application honors. To make the instrumentation follow the same error reporting settings as your app set the following INI directive to 1.

possible values:

0: (Default) Report all errors except E_STRICT and E_DEPRECATED.
1: Follow the same error reporting settings as your app.

history: Introduced in version 1.3.2.

example: appoptics.use_error_reporting = 1

Enable Wrap Error Log

config option: appoptics.enable_wrap_error_log

description: Completely aside from the level of error reporting in php or the instrumentation, php also offers a logging function called error_log(), which can be used to write arbitrary log data to a file. By default the instrumentation reports these lines of log text to AppOptics. To disable this set the following INI directive to 0.

possible values:

0: Do not report logging text generated by error_log().
1: (Default) Report logging text generated by error_log().

history: Introduced in version 1.3.2.

example: appoptics.enable_wrap_error_log = 0

Enable CLI

config option: appoptics.enable_cli

description: Enable or disable Command Line Interface (CLI) tracing. Default is 0.

PHP command line option -d --define or -c --php-ini can be used to set this configuration for a particular CLI invocation, rather than globally, to limit the impact of tracing. An example crontab entry to enable tracing:

*/5 * * * * /usr/bin/php -d appoptics.enable_cli=1 /opt/job/script.php

And an example to disable tracing for a particular invocation when CLI tracing is enabled globally:

*/5 * * * * /usr/bin/php -d appoptics.enable_cli=0 /opt/job/script.php

Also see the option Max Ready Wait Time to block execution until AppOptics becomes ready.

possible values: 0 (disable), 1 (enable). Default: 0.

history: Introduced in version 3.0.0.

example: appoptics.enable_cli = 0

Disable Backtraces

config option: appoptics.enable_backtrace

description: Enable/disable backtraces to be reported with spans. This option is useful when debugging issues related to memory usage or broken (incomplete) traces. Backtrace information can increase data size significantly which leads to increased memory usage on the host and can even cause broken traces if the size is too big. This option allows to temporarily disable backtraces to test whether or not a particular issue could be related to backtrace data.

possible values: 0 (disable), 1 (enable). Default: 1.

history: Introduced in version 2.0.0.

example: appoptics.enable_backtrace = 1

Disable the Agent

config option: appoptics.enable

description: The agent can be effectively disabled at the vhost level with this option, which is helpful for environments with multiple vhosts. Setting this option in the INI file will affect the global scope of PHP. It can also be set on vhosts individually (e.g. .htaccess or httpd.conf).

Note that this option will not fully disable the agent and therefore will still establish a connection to AppOptics. If you wish to fully disable the agent please comment out the line extension=appoptics.so in your INI file or uninstall the agent. See also Tracing on how to disable tracing and metrics at the service level, and Transaction Settings File on how to disable tracing and metrics at a transaction level.

Example on how to enable/disable the agent for different vhosts in httpd.conf:

Listen *:3080
<VirtualHost *:3080>
  php_value appoptics.enable 0
</VirtualHost>

Listen *:3081
<VirtualHost *:3081>
  php_value appoptics.enable 1
</VirtualHost>

possible values: 0 (disable), 1 (enable). Default: 1.

history: Introduced in version 3.3.1.

example: appoptics.enable = 1

Enable Code Profiling

config option: appoptics.enable_profiling

description: Enable or disable code profiling. For more information see Code Profiling.

possible values: 0 (disable), 1 (enable). Default: 0.

history: Introduced in version 3.4.0.

example: appoptics.enable_profiling = 1

Change Code Profiling Interval

config option: appoptics.profiling_interval

description: The interval in milliseconds at which code profiling takes snapshots. Only valid if appoptics.enable_profiling is set to 1. For more information see Code Profiling.

possible values: 20 - 2,147,483,647. Default: 20.

history: Introduced in version 3.4.0.

example: appoptics.profiling_interval = 20

Transaction Settings File

config option: appoptics.transaction_settings_file

description: Path to the INI file that contains the transaction settings for filtering specific transactions, which can be used to exclude transactions from being traced. The path should be absolute (e.g. /etc/php/conf.d/ao-transaction-settings.ini) or relative to the execution directory of your app. Each setting must be nested under a new [index]. Example content of an INI file:

[0]
type = url
regexp = ".*/abc/.*"
tracing = "disabled"
[1]
type = url
extensions = "css html"
tracing = "disabled"

In the example above all transactions that have "/abc/" in the request URL or end in the file extension .css/.html will be disabled for tracing. The first setting that matches a transaction will be used. This option works well in combination with appoptics.tracing which could be used to enable/disable tracing globablly and then use transaction specific settings to enable/disable certain transactions only. Ensure that the regular expression conforms to the Boost/C++11 standard. If a regular expression is invalid an error will be logged and the setting will be ignored. Different settings files can be configured on a vhost level. See transaction filtering for more information.

history: Introduced in version 3.5.0.

example: appoptics.transaction_settings_file = /etc/php/conf.d/ao-transaction-settings.ini

Automatic Insertion of Trace ID into Logs

config option: appoptics.log_trace_id

description: Enable or disable appending the Trace ID of the currently running request to internal errors/warnings and PHP logs generated with error_log. The sample flag (whether or not request is being sampled) is added to the end of the Trace ID and will be of the form "-0" for non-sampled and "-1" for sampled requests. If you want to add the Trace ID to log messages generated by logging frameworks such as Monolog or log4PHP, see Trace Context in Logs.

possible values:

disabled:      do not append (Default)
enabled:       append for all requests
sampled_only:  append only for sampled requests

history: Introduced in version 3.6.0.

example: appoptics.log_trace_id = enabled

Enable Laravel Tracing

config option: appoptics.enable_laravel_tracing

description: Enable/disable tracing for laravel.

possible values: 0 (disable), 1 (enable). Default: 1.

history: Introduced in version 3.7.0.

example: appoptics.enable_laravel_tracing = 1

Enable Laravel Backtraces

config option: appoptics.laravel_enable_backtrace

description: Enable or disable collecting backtraces for laravel traces. Enabling this option will increase usage of memory and network bandwidth since laravel backtraces are quite large.

possible values: 0 (disable), 1 (enable). Default: 0.

history: Introduced in version 3.7.0.

example: appoptics.laravel_enable_backtrace = 0

Change EC2 Metadata Timeout

config option: appoptics.ec2_metadata_timeout

description: Timeout for retrieving EC2 metadata (in milli seconds). This option is useful for apps running on AWS EC2 or OpenStack instances, to increase the retrieval timeout. It is safe to set this value to 0 for apps that don't run on EC2/OpenStack.

possible values: 0 - 3000. Default: 1000

history: Introduced in version 3.8.0.

example: appoptics.ec2_metadata_timeout = 1000

Enable Trigger Tracing

config option: appoptics.trigger_tracing

description: Enable or disable trigger tracing. A triggered trace is a special trace that bypasses sampling decisions. See Trigger Trace for more information.

possible values:

enabled: (Default) Allow special handling of HTTP requests that are flagged as trigger trace.
disabled: No special handling of HTTP requests that are flagged as trigger trace.

history: Introduced in version 3.8.0.

example: appoptics.trigger_tracing = enabled

Use HTTP Proxy

config option: appoptics.proxy

system environment variable: APPOPTICS_PROXY

description: The agent can connect to the AppOptics backend through a proxy. The config value should either be http://<proxyHost>:<proxyPort> for a proxy server that does not require authentication, or http://<username>:<password>@<proxyHost>:<proxyPort> for a proxy server that requires Basic authentication. Note that while HTTP is the only type of connection supported between the agent and proxy (hence only http:// is allowed in the schema of the config value), the agent traffic to AppOptics is still encrypted using SSL/TLS. Provide the config value inside double quotes.

It is recommended to use the agent-specific configuration. However, the agent's underlying network library will use a system-wide proxy defined in the environment variables grpc_proxy, https_proxy or http_proxy if agent-specific configuration is not set. Refer to gRPC environment variables for more information.

history: Introduced in version 4.0.0.

examples:

appoptics.proxy = "http://my-proxy:3306"
appoptics.proxy = "http://user:password@my-proxy:3306"

Hide URL Parameters

config option: appoptics.hide_url_parameters

description: This config controls whether URL query parameters are reported or not. If enabled, AppOptics will stop collecting and reporting URL parameters (e.g. http://example.com/site?param=123 will be reported as http://example.com/site).

possible values: 0 (disable), 1 (enable). Default: 0.

history: Introduced in version 4.0.0.

example: appoptics.hide_url_parameters = 1

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.

Search SolarWinds Support

Configuration (legacy agent)

How to set configuration

Report backtraces

Suppress reporting for sensitive data

Complete configuration options

Service Key

Tracing

Debug Level

Hostname Alias

Max Transactions

Max Ready Wait Time

Max Flush Wait Time

Sanitize SQL Mode

Enable Error Callback

Report Suppressed Errors

Use Error Reporting

Enable Wrap Error Log

Enable CLI

Disable Backtraces

Disable the Agent

Enable Code Profiling

Change Code Profiling Interval

Transaction Settings File

Automatic Insertion of Trace ID into Logs

Enable Laravel Tracing

Enable Laravel Backtraces

Change EC2 Metadata Timeout

Enable Trigger Tracing

Use HTTP Proxy

Hide URL Parameters