Documentation forSolarWinds Observability

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:

  1. System environment variable
  2. 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 adding 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 can be changed at a directory or virtual host (vhost) level. 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}";
}

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"

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

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

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

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.