Use the OpenTelemetry-based SolarWinds APM PHP library (Alpha)

The new SolarWinds APM PHP library version 9.0.0-alpha.1 and later is now based on OpenTelemetry. This library uses the OTel standard for collecting and exporting telemetry data to help you monitor and understand how your PHP applications perform. It enables distributed tracing and observability, with both automatic and manual instrumentation options. It also integrates with the SolarWinds Observability SaaS platform and works with modern PHP frameworks.

Before you begin

Ensure that you have installed the prerequisites:

• PHP 8.1+
• PECL
• Composer
• pie

Install the OTel-based SolarWinds APM PHP library

The major differences between the SolarWinds alpha PHP release and the OpenTelemetry PHP are the SDK and an extra solarwinds/apm_ext C extension along with the SolarWinds OTel Collector setup, for seamless integration with SolarWinds Observability and enhanced performance.

Dependencies

The solarwinds/apm is pure-PHP starting with 9.0.0-alpha.1, thus can be installed on most Linux and Windows systems.

The solarwinds/apm_ext is pure C/C++ starting at 1.0.0 and requires pie. The extension can be installed on most Linux and Windows (x86_64) systems.

Installation steps

Install the SolarWinds APM library:

composer require solarwinds/apm:^9.0@alpha

Install a PSR-compatible HTTP client (required for OTLP exporter):

composer require guzzlehttp/guzzle

Set your service key (via environment variable):

export SW_APM_SERVICE_KEY=<YourServiceKey>

Set the APM collector endpoint which provides sampling settings (the default is apm.collector.na-01.cloud.solarwinds.com). Also make a note of the OTLP ingestion endpoint that corresponds to your tenant, for example, otel.collector.na-01.cloud.solarwinds.com:443. By default, telemetry exports to a local OTLP endpoint. For an example of exporting directly or through a local OpenTelemetry Collector to SolarWinds Observability, see the linked example application.

export SW_APM_COLLECTOR=<YourAPMcollectorURL>

Next, install solarwinds/apm_ext which caches sampling settings to reduce request latency:

Linux

pie install solarwinds/apm_ext

Windows

php pie.phar install solarwinds/apm_ext

To minimize export delays, opentelemetry-php recommends an agent collector to receive the telemetry. SolarWinds recommends using the SolarWinds OpenTelemetry Collector for better integration with SolarWinds Observability. Please refer to SolarWinds OpenTelemetry Collector documentation for installation instructions.

See also this example application, which demonstrates automatic, zero-code instrumentation and also includes the configuration to receive telemetry from the PHP application and export to SolarWinds Observability.

Configure your application

Exporter

The default is OTel’s standard otlp OTLP/HTTP exporter configured to export local to al OTel Collector endpoint. The SolarWinds OTel Collector started during setup would batch telemetry data from the APM library and export to SolarWinds OTel endpoint.

The console and none exporters are also supported by 9.0.0-alpha.1, and can be enabled as shown below:

export OTEL_TRACES_EXPORTER=console
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console

SolarWinds does not recommend setting these values outside of diagnostic use cases.

Complete list of configuration options

9.0.0-alpha.1 supports OpenTelemetry SDK configuration and their variables.

See CONFIGURATION.md for SolarWinds-specific configuration variables.

Instrumentation SDK

One SolarWinds-specific SDK option is available to set a custom transaction name at the beginning of your application:

use Solarwinds\ApmPhp\API\TransactionName;
TransactionName::set('custom-transaction-name');

For manual instrumentation, 9.0.0-alpha.1 supports OTel PHP manual instrumentation, which includes examples. Additionally, see a SolarWinds manual instrumentation example here.

PHP trace context in logs

When Exporting Application Logs service.name, traceId, spanId, and flags will be automatically added to the OpenTelemetry logs.

Example log output:

{
  ...
  "resource":{"attributes":[{"key":"service.name","value":{"stringValue":"php-example"}}]},
  ...
  "logRecords":[{"timeUnixNano":"1762572315653380000","observedTimeUnixNano":"1762572315653559040","severityNumber":9,"severityText":"INFO","body":{"stringValue":"hello, otel"},"flags":1,"traceId":"1c52067371dfddaa6ed58c42d43d0a2f","spanId":"f33aaf87fc3ca8ab"}],
  ...
}

If the application log is not exported via OTLP, trace context can be injected into the log messages by using the OTel SDK function Context::getCurrent().

Monolog example capturing the trace context with a processor:

use OpenTelemetry\API\Trace\Span;
use OpenTelemetry\Context\Context;

$logger->pushProcessor(function ($record) {
  $spanContext = Span::fromContext(Context::getCurrent())->getContext();
  $record['message'] .= ' trace_id='.$spanContext->getTraceId() . ' span_id=' . $spanContext->getSpanId() . ' trace_flags=' . ($spanContext->getTraceFlags() ? '01' : '00');
  return $record;
});

PHP trace context in queries

Install OpenTelemetry SQL Commenter to propagate trace context to database queries:

composer require open-telemetry/opentelemetry-sqlcommenter

Supported DB libraries:

• open-telemetry/opentelemetry-auto-mysqli
• open-telemetry/opentelemetry-auto-pdo
• open-telemetry/opentelemetry-auto-postgresql

Enable context propagation:

OTEL_PHP_SQLCOMMENTER_CONTEXT_PROPAGATORS=tracecontext

Enable SQL comment attributes:

OTEL_PHP_SQLCOMMENTER_ATTRIBUTE=true

Components supported by version 9.0.0-alpha.1

Starting with version 9.0.0-alpha.1, the library is pure-PHP thus can be installed on most systems.

The alpha library supports PHP 8.1+, which is the same PHP version supported by opentelemetry-php. Follow the OpenTelemetry PHP repo and documentation for changes to recommended PHP versions, including EOL updates.

9.0.0-alpha.1 also supports all OTel PHP instrumentation libraries (for example, open-telemetry/opentelemetry-auto-slim, open-telemetry/opentelemetry-auto-laravel, and others). Choose the instrumentation library in Packagist.org to install based on your implementation needs.

Upgrade to the OTel-based APM PHP library

Starting with version 9.0.0-alpha.1, the library is built on top of OTel, while 8.x versions or earlier are based on proprietary code.

The PHP OTel project actively drops support for EOL and unmaintained versions of the runtime and libraries. In order to upgrade, make sure your application is running on a current version of PHP.

Upgrade involves uninstalling of the previous APM PHP library before installing the new one.

In SolarWinds APM PHP library version 9 and later, the solarwinds_apm_* tracing API is no longer supported. Instead, use the standard PHP OTel API. See recommendations below.

Prerequisites

• Backup of your current application and its dependencies.
• Review the releases.
• Familiarize yourself with the troubleshooting steps below for potential issues during the upgrade process.
• Check the compatibility of your PHP version with the new library version.
• Review any custom instrumentation or integrations you have implemented.

API changes from 8.x to 9.x

Starting with version 9.0.0-alpha.1, the proprietary solarwinds_apm_* tracing API is no longer supported and standard PHP OTel API should be used instead. The table below lists the recommended API when upgrading to version 9.

Version 8.x	Version 9.x
solarwinds_apm_get_context	Use Context::getCurrent().
solarwinds_apm_set_context	Not supported.
solarwinds_apm_is_ready	Not supported. 9.x will be always ready before instrumentation.
solarwinds_apm_start_trace	Use OpenTelemetry Trace API.
solarwinds_apm_end_trace	Use OpenTelemetry Trace API.
solarwinds_apm_set_transaction_name	Use TransactionName::set API from Solarwinds\ApmPhp\API.
solarwinds_apm_is_tracing	Not supported.
solarwinds_apm_trace_started	Not supported.
solarwinds_apm_log	Use SpanBuilderInterface::startSpan().
solarwinds_apm_log_entry	Use SpanBuilderInterface::startSpan().
solarwinds_apm_log_exit	Use SpanInterface::end().
solarwinds_apm_log_error	Use SpanInterface::setStatus(). See the opentelemetry-php example.
solarwinds_apm_log_exception	Use SpanInterface::recordException(). See the opentelemetry-php example.
solarwinds_apm_metric_summary	Use OpenTelemetry Metrics API.
solarwinds_apm_metric_increment	Use OpenTelemetry Metrics API.
solarwinds_apm_get_log_trace_id	Use Context::getCurrent().

Transaction Settings changes from 8.x to 9.x

Beginning with version 9, the proprietary transaction settings format is no longer supported. Please refer to the updated CONFIGURATION.md for the new transaction settings format and update your configuration accordingly.

Upgrade Steps

1. Uninstall 8.x Version: Before installing version 9.x, migrate proprietary solarwinds_apm_* tracing API calls and fully uninstall version 8.x to avoid conflicts.

2. Install 9.x+ Version: Follow the installation and Add zero-code instrumentation instructions in the README.md to install version 9.x or later.

3. Verify 9.x+ Installation: Ensure that the 9.x+ version is correctly installed and the OpenTelemetry extension is active:

php --ri opentelemetry

Verify the installation by following the Example Application in the README.md to verify that traces are being generated and sent to SolarWinds Observability.

Troubleshoot the PHP library version 9.0.0-alpha.1

General Troubleshooting Steps

• Error Logs: Check PHP's error_log for errors or warnings. Control the log destination with OTEL_PHP_LOG_DESTINATION.

• OpenTelemetry C Extension: Verify the opentelemetry C extension is loaded and active:

  php --ri opentelemetry

• Minimal Reproducible Example: Create a minimal PHP script to isolate the problem by sending a simple trace or metric.

• Support: If issues persist, reach out to SolarWinds support.

Dependency Management

• Composer: Ensure all required OpenTelemetry PHP dependencies are listed in your composer.json. Check installed packages:

  composer show --installed

• Version Compatibility: Confirm package versions are compatible with your PHP version and each other.

Environment Variable Configuration

• Timing: Set OpenTelemetry environment variables before including the Composer autoloader (for example, before vendor/autoload.php). Setting them too late can prevent proper initialization.

• Verification: Use printenv to confirm all OpenTelemetry-related environment variables are set and accessible to your PHP application.

• Common Environment Variables:

  • OTEL_PHP_AUTOLOAD_ENABLED

  • OTEL_SERVICE_NAME

  • OTEL_TRACES_SAMPLER

  • OTEL_PROPAGATORS

  • OTEL_EXPERIMENTAL_RESPONSE_PROPAGATORS

  • OTEL_EXPORTER_OTLP_ENDPOINT

  • OTEL_EXPORTER_OTLP_HEADERS

  • SW_APM_SERVICE_KEY

PHP-Specific Considerations

• open_basedir: If using PHP's open_basedir, ensure it allows access to required OpenTelemetry files and directories.

• Fibers: If using Fibers, set OTEL_PHP_FIBERS_ENABLED=true and consider preloading bindings, especially for non-CLI SAPIs.

• Stack Extension: If you encounter issues with argument handling in pre-hooks, enable opentelemetry.allow_stack_extension in php.ini.

Sampling Considerations

• solarwinds/apm_ext: To troubleshoot sampling issues, it is often easier to temporarily disable the solarwinds/apm_ext C extension. You can do this by commenting out the extension in your php.ini file:

  ;extension=apm_ext

SolarWinds Observability Issues

Verifying Telemetry Generation

• Console Exporter: Change your exporter to console to confirm traces, metrics, or logs are being generated and output to the console. This helps isolate issues between instrumentation and SolarWinds Observability.

  export OTEL_TRACES_EXPORTER=console
  export OTEL_METRICS_EXPORTER=console
  export OTEL_LOGS_EXPORTER=console

• Detailed Logging: Enable debug logs for more insight into instrumentation and errors:

  export OTEL_LOG_LEVEL=debug

Troubleshooting SolarWinds Observability Export Issues

• Error Logs: If data appears in the console but not in SolarWinds Observability, check error logs to verify data is exported correctly.

• Configuration Verification: Ensure your OTEL_EXPORTER_OTLP_HEADERS and OTEL_EXPORTER_OTLP_ENDPOINT are set correctly.