Configure the PHP Library

To list the config files used by PHP, run the command: php --ini. Files specific to command-line implementations are identified by the path /cli/, whereas files specific to web systems are located in /cgi/ directories. For most platforms, you’ll find an solarwinds-apm.ini config file after installing the PHP Library.

How to set configuration

All configuration options can be set in the config file(s) used by your PHP installation. The PHP Library installation adds the file solarwinds-apm.ini config file to the standard PHP config directory.

Restart the web server or PHP process for changes to the configuration to take effect.

If the same configuration option is set in both a config file and an environment variable, the setting is applied with the following precedence:

System environment variable
Configuration in INI file

For example, if you define the Service key by setting both the SW_APM_SERVICE_KEY system environment variable and the solarwinds-apm.service_key in solarwinds-apm.ini, the value entered in SW_APM_SERVICE_KEY will be used.

Report backtraces

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

Suppress reporting for sensitive data

By default, PHP instrumentation sanitizes query literals from SQL statements. When SQL database queries are sanitized, query parameters are not displayed in your account. While sanitizing the SQL statements, the library removes literals by automatically trying to determine the quoting character used.

To configure the instrumentation to start collecting and reporting query parameters, modify the enable_sanitize_sql INI directive.

solarwinds-apm.enable_sanitize_sql = 0

Complete configuration options

The following is the complete list of instrumentation configuration options.

Service key

INI directive

solarwinds-apm.service_key

System environment variable

SW_APM_SERVICE_KEY

Description

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability does not affect the Service key.

The service key can also be defined at the virtual host (vhost) level, and would override the service key(s) defined as an environment variable or INI directive.

The same API token should be used for every service key defined in your process.

The following example changes the service name for two different vhosts in httpd.conf:

Listen *:3080
<VirtualHost *:3080>
  php_value solarwinds-apm.service_key ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:vhost-3080
</VirtualHost>
Listen *:3081
<VirtualHost *:3081>
  php_value solarwinds-apm.service_key ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:vhost-3081
</VirtualHost>

The following is an example using Nginx:

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

The service name set at the webserver directory or vhost level overrides the service name portion of the service key set in the environment variable or INI configuration file. The exception is if the override value is the same as the service name set in the environment variable or INI configuration file, the override will be ignored and the service name will be set based on the precedence order of environment variable then INI configuration file.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.service_key = ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:my-service

Collector

INI directive

solarwinds-apm.collector

Description

Overrides the default collector endpoint the library reports to. The value should be double quoted and in the format <endpoint>:<port>.

History

Introduced with version 7.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.collector = "example.collector.solarwinds.com:443"

Trusted certificate path

The library uses the trusted CA certificates installed in the system to verify the TLS connection to the collector. To override the default, define the trusted certificate path configuration option with an absolute path to a specific trusted certificate file in PEM format.

System environment variable

SW_APM_TRUSTEDPATH

System property

solarwinds-apm.trustedpath

INI directive

solarwinds-apm.trustedpath

Required

History

Introduced with version 7.2.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.trustedpath="/path/to/cacert.pem"

Tracing

INI directive

solarwinds-apm.tracing

Description

Specifies 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 version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.tracing = enabled

Debug level

INI directive

solarwinds-apm.debug_level

Description

Adjusts the logging verbosity level. Increase the logging level to a higher debug level to add more detailed information to the library logs.

Possible values

`-1`	Disable
`0`	Fatal
`1`	Error
`2`	(Default) Warning
`3`	Info
`4`	Debug low
`5`	Debug medium
`6`	Debug high

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.debug_level = 6

Hostname alias

INI directive

solarwinds-apm.hostname_alias

Description

An optional descriptive hostname that can be used to easily identify the host.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.hostname_alias = apm-host-east

Max transactions

INI directive

solarwinds-apm.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 noticeable impact on the used memory and can help reduce the memory footprint of the library. The default is 50.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.max_transactions = 100

Max ready wait time

INI directive

solarwinds-apm.max_ready_wait_time

Description

The maximum wait time (in milliseconds) for the PHP Library to become ready to receive traces. To prevent the PHP Library from blocking the app on startup, turn off waiting by setting solarwinds-apm.max_ready_wait_time to 0. The default maximum ready wait time is:

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

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.max_ready_wait_time = 500

Max flush wait time

INI directive

solarwinds-apm.max_flush_wait_time

Description

The maximum wait time (in milliseconds) for flushing data before terminating the app. To prevent the PHP Library from blocking the app on termination, turn off waiting by setting the solarwinds-apm.max_flush_wait_time to 0. The default maximum flush wait time is 5000 ms.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.max_flush_wait_time = 2000

Sanitize SQL mode

INI directive

solarwinds-apm.enable_sanitize_sql

Description

PHP instrumentation can sanitize query literals from SQL statements. This is enabled by default and the library removes literals by automatically trying to determine the quoting character used. To change the sanitization mode or to disable SQL sanitization, set this to one of the other possible values.

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 with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_sanitize_sql = 0

Enable error callback

INI directive

solarwinds-apm.enable_error_callback

Description

Directs the instrumentation whether to send error data to the SolarWinds APM collector. By default, all errors are reported, the @ suppression operator is obeyed, and the instrumentation default error reporting level is used. To direct the instrumentation not to send any error data at all to the SolarWinds APM collector, set this INI directive to 0.

Possible values

`0`	Disable error reporting.
`1`	(Default) Report all errors to the SolarWinds APM collector.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_error_callback = 0

Report suppressed errors

INI directive

solarwinds-apm.report_suppressed_errors

Description

The PHP error control @ operator overrides the global error reporting settings and suppresses any errors for the expression it precedes. By default, the PHP Library also ignores errors suppressed by the @ operator. To report errors that occur at the current error reporting level, set this INI directive to 1.

Possible values

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

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.report_suppressed_errors = 1

Use error reporting

INI directive

solarwinds-apm.use_error_reporting

Description

PHP error reporting levels are controlled by either altering the error_reporting directive in PHP INI files or defining the reporting level at runtime with the error_reporting function. Regardless of your error_reporting levels in the PHP INI or in the runtime function, the PHP Library reports all errors by default, except E_STRICT and E_DEPRECATED errors. To require the library to follow the error reporting settings that are set in your app, set the solarwinds-apm.use_error_reporting 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 with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.use_error_reporting = 1

Enable wrap error log

INI directive

solarwinds-apm.enable_wrap_error_log

Description

In addition to the error reporting already provided by PHP and the PHP Library, custom error messages can be sent to a log file with the PHP logging function error_log(). When this function is used, the PHP Library reports the log data to the SolarWinds APM collector. To disable this, set the solarwinds-apm.enable_wrap_error_log 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 with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_error_log = 0

Enable CLI

INI directive

solarwinds-apm.enable_cli

Description

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

The 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 solarwinds-apm.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 solarwinds-apm.enable_cli=0 /opt/job/script.php

Use the Max Ready Wait Time option to block execution until the SolarWinds APM collector is ready.

Possible values

`0`	Disable CLI.
`1`	Enable CLI.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_cli = 0

Disable backtraces

INI directive

solarwinds-apm.enable_backtrace

Description

Enables or disables reporting backtraces with spans. If backtrace information increases data size significantly, the host may have increased memory usage or traces may break. Temporarily disabling backtraces with this option helps determine whether backtraces are causing memory usage issues or incomplete traces.

Possible values

`0`	Disable reporting backtraces.
`1`	(Default) Enable reporting backtraces.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_backtrace = 1

Disable the library

INI directive

solarwinds-apm.enable

Description

Disable PHP instrumentation globally or for an individual vhost. To disable instrumentation for an individual vhost, define solarwinds-apm.enable in the .htaccess or httpd.conf file. To disable instrumentation for the global scope of PHP, set the solarwinds-apm.enable value in the INI file instead.

Setting solarwinds-apm.enable in the INI file does not fully disable the library; the library still connects to the SolarWinds APM collector. To disable the library, comment out the line extension=solarwinds-apm.so in your INI file or uninstall the library. To disable tracing and metrics at the service level, see Tracing; to disable tracing and metrics at the transaction level, see Transaction settings file.

An example enabling and disabling the library for different vhosts in a httpd.conf file is:

Listen *:3080
<VirtualHost *:3080>
  php_value solarwinds-apm.enable 0
</VirtualHost>

Listen *:3081
<VirtualHost *:3081>
  php_value solarwinds-apm.enable 1
</VirtualHost>

Possible values

`0`	Disable instrumentation.
`1`	(Default) Enable instrumentation.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable = 1

Enable code profiling

INI directive

solarwinds-apm.enable_profiling

Description

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

Possible values

`0`	(Default) Disable code profiling.
`1`	Enable code profiling.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_profiling = 1

Change code profiling interval

INI directive

solarwinds-apm.profiling_interval

Description

The interval code profiling takes snapshots, in milliseconds. If solarwinds-apm.enable_profiling is not set to 1., this value is ignored. See Code profiling.

Possible values

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

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.profiling_interval = 20

Transaction settings file

INI directive

solarwinds-apm.transaction_settings_file

Description

This is the path to the INI file that contains the transaction settings for filtering specific transactions. The path can be either absolute (for example, /etc/php/conf.d/sw-transaction-settings.ini) or relative to the execution directory of your app. Make sure the INI file exists at the path you define.

Use this transaction settings INI file to exclude transactions from being traced. Each setting in the INI file must be nested under a new [index]. When multiple settings are defined, the first setting that matches a transaction will be used.

The transaction settings file can be used to selectively disable specific transaction traces when solarwinds-apm.tracing is enabled. If solarwinds-apm.tracing disables tracing globally, then transaction specific settings will be ignored.

The regular expression must conform to the Boost/C++11 standard. If a regular expression is invalid, an error is logged and the setting ignored. Settings files can also be configured at the vhost level.

An example of an INI file's contents:

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

In the example above, all transactions that either have /abc/ in the request URL or that have a file extension of either .css or .html are disabled for tracing.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.transaction_settings_file = /etc/php/conf.d/sw-transaction-settings.ini

Automatic insertion of trace context into logs

Application logs for your service entity are not included in the data sent by APM libraries. Configure your server or application to send application logs to SolarWinds Observability. See Add logs from services.

INI directive

solarwinds-apm.log_trace_id

Description

Adds the Trace Context of the currently running request to the end of internal errors, internal warnings, and PHP logs generated with the error_log function. The Trace ID, Span ID, and Trace Flags are added in the following format: trace_id=abcdef1234567890abcdef1234567890 span_id=abcdef1234567890 trace_flags=01. To add the Trace Context to log messages generated by logging frameworks such as Monolog or log4PHP, see Trace Context in Logs.

Possible values

`disabled`	(Default) Do not append
`enabled`	Append for all requests
`sampled_only`	Append only for sampled requests

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.log_trace_id = enabled

Automatic insertion of trace context into queries

INI directive

solarwinds-apm.sqltagger

Description

This option enables or disables injecting trace context as a comment into the beginning of a SQL statement for sampled requests. See Trace context in queries.

Trace context in queries is only supported for the PDO (MySQL and PostgreSQL drivers) and MySQL Improved Extension functions described in the table below. This setting has no effect for other extensions.

Name	Function	Support
PDO	`pdo::exec`
	`pdo::query`
	`pdostatement::execute`
MySQL Improved extension	`multi_query`
	`query`
	`real_query`
	`send_query`
	`stmt_execute`
	`execute`

Possible values

`0`	(Default) Disable
`1`	Enable

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.sqltagger = 1

Enable Laravel tracing

INI directive

solarwinds-apm.enable_laravel_tracing

Description

Enable or disable tracing for laravel.

Possible values

`0`	Disable
`1`	(Default) Enable

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_laravel_tracing = 1

Enable Laravel backtraces

INI directive

solarwinds-apm.laravel_enable_backtrace

Description

Enable or disable collecting backtraces for laravel traces. Collecting backtraces for laravel traces will increase usage of memory and network bandwidth since laravel backtraces are quite large.

Possible values

`0`	(Default) Disable
`1`	Enable

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.laravel_enable_backtrace = 0

Change EC2 metadata timeout

INI directive

solarwinds-apm.ec2_metadata_timeout

Description

Amount of time (in milliseconds) to wait to retrieve EC2 metadata before timing out. You may want to increase the retrieval timeout for apps running on AWS EC2 or OpenStack instances. For apps that do not run on EC2 or OpenStack instances, it is safe to set this value to 0, which instructs the library to use the default timeout value.

Possible values

0 - 3000. Default: 1000

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.ec2_metadata_timeout = 1000

Enable trigger tracing

INI directive

solarwinds-apm.trigger_tracing

Description

Enable or disable trigger tracing. A triggered trace is a special trace that bypasses sampling decisions.

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 with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.trigger_tracing = enabled

Use HTTP proxy

INI directive

solarwinds-apm.proxy

System environment variable

SW_APM_PROXY

Description

Optional configuration. This option can be used to connect to the SolarWinds APM collector through a proxy. It can be set in the config file solarwinds-apm.proxy element or through the environment variable SW_APM_PROXY. While HTTP is the only type of connection supported between the library and proxy (hence only http:// is allowed in the schema of the config value), the library traffic to SolarWinds Observability is still encrypted using SSL/TLS. The config value should be contained in double quotes.

Possible values

Proxy that requires Basic Authentication: http://<username>:<password>@<proxyHost>:<proxyPort>

Proxy that does not require authentication: http://<proxyHost>:<proxyPort>

SolarWinds recommends using the library-specific configuration. However, the library's underlying network library uses a system-wide proxy defined in the environment variables grpc_proxy, https_proxy or http_proxy if library-specific configuration is not set. Refer to gRPC environment variables for more information.

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Examples

solarwinds-apm.proxy = "http://my-proxy:3306"

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

Hide URL parameters

INI directive

solarwinds-apm.hide_url_parameters

Description

Controls whether URL query parameters are reported or not. If enabled, the library will stop collecting and reporting URL parameters. For example, with hide URL parameters enabled, http://example.com/site?param=123 will be reported as http://example.com/site.

Possible values

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

History

Introduced with version 6.0.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.hide_url_parameters = 1

Enable wrap mysqli

INI directive

solarwinds-apm.enable_wrap_mysqli

Description

Enable or disable mysqli procedural interface tracing. The default is 1.

Disabling instrumentation might affect various SolarWinds Observability features and should only be used for troubleshooting.

Possible values

`0`	Disable mysqli procedural interface instrumentation.
`1`	(Default) Enable mysqli procedural interface instrumentation.

History

Introduced with version 8.5.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_mysqli = 1

Enable wrap mysqli OOP

INI directive

solarwinds-apm.enable_wrap_mysqli_oo

Description

Enable or disable mysqli OOP interface tracing. The default is 1.

Disabling instrumentation might affect various SolarWinds Observability features and should only be used for troubleshooting.

Possible values

`0`	Disable mysqli OOP procedural interface instrumentation.
`1`	(Default) Enable mysqli OOP interface instrumentation.

History

Introduced with version 8.5.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_mysqli_oo = 1

Enable wrap curl

INI directive

solarwinds-apm.enable_wrap_curl

Description

Enable or disable curl tracing. The default is 1.

Disabling instrumentation might affect various SolarWinds Observability features and should only be used for troubleshooting.

Possible values

`0`	Disable curl instrumentation.
`1`	(Default) Enable curl instrumentation.

History

Introduced with version 8.5.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_curl = 1

Enable wrap pdo

INI directive

solarwinds-apm.enable_wrap_pdo

Description

Enable or disable pdo tracing. The default is 1.

Disabling instrumentation might affect various SolarWinds Observability features and should only be used for troubleshooting.

Possible values

`0`	Disable pdo instrumentation.
`1`	(Default) Enable pdo instrumentation.

History

Introduced with version 8.5.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_pdo = 1

Enable wrap phpredis

INI directive

solarwinds-apm.enable_wrap_phpredis

Description

Enable or disable phpredis tracing. The default is 1.

Disabling instrumentation might affect various SolarWinds Observability features and should only be used for troubleshooting.

Possible values

`0`	Disable phpredis instrumentation.
`1`	(Default) Enable phpredis instrumentation.

History

Introduced with version 8.5.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_phpredis = 1

Enable wrap HTTP

INI directive

solarwinds-apm.enable_wrap_http

Description

Enable or disable HTTPS stream tracing. The default is 1.

Disabling instrumentation might affect various SolarWinds Observability features and should only be used for troubleshooting.

Possible values

`0`	Disable HTTPS stream instrumentation.
`1`	(Default) Enable HTTPS stream instrumentation.

History

Introduced with version 8.5.0 of the PHP Instrumentation Library.

Example

solarwinds-apm.enable_wrap_http = 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

Configure the PHP Library

How to set configuration

Report backtraces

Suppress reporting for sensitive data

Complete configuration options

Service key

Collector

Trusted certificate path

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 library

Enable code profiling

Change code profiling interval

Transaction settings file

Automatic insertion of trace context into logs

Automatic insertion of trace context into queries

Enable Laravel tracing

Enable Laravel backtraces

Change EC2 metadata timeout

Enable trigger tracing

Use HTTP proxy

Hide URL parameters

Enable wrap mysqli

Enable wrap mysqli OOP

Enable wrap curl

Enable wrap pdo

Enable wrap phpredis

Enable wrap HTTP