Last9 OpenTelemetry Plugin for WordPress

A comprehensive OpenTelemetry instrumentation plugin for WordPress. Capture distributed traces, errors, and browser telemetry using the open OpenTelemetry standard.

Features

• Distributed Tracing - Automatic instrumentation for WordPress requests

  • Database query tracing (MySQL)
  • HTTP client request tracing
  • REST API tracing
  • WordPress hook tracing (optional)
  • Plugin/theme loading phase tracing
  • Transient cache operation tracing

• Error & Exception Tracking

  • PHP errors and warnings
  • Uncaught exceptions with full stack traces
  • Fatal error capture
  • WordPress wp_die integration

• Browser Telemetry

  • JavaScript error capture
  • Web Vitals (TTFB, FCP, LCP, CLS, INP)
  • User interaction tracking
  • Page view tracking

• User Context

  • Automatic user identification
  • Login/logout event tracking
  • Failed login attempt tracking

Quick Start

# Clone the repository
git clone https://github.com/last9/last9-wordpress-plugin.git
cd last9-wordpress-plugin

# Start the development environment
docker compose up -d

Open http://localhost:8080, complete WordPress setup, then activate the plugin.

Configuration

Option 1: WordPress Admin UI

Navigate to Settings > Last9 OTel and enter your OTLP endpoint and credentials.

Option 2: wp-config.php (Recommended for Production)

// Required
define('LAST9_OTEL_ENDPOINT', 'Your Last9 OpenTelemetry Endpoint');
define('LAST9_OTEL_AUTH_HEADER', 'Basic YOUR_BASE64_CREDENTIALS');

// Optional - Service identification
define('LAST9_OTEL_SERVICE_NAME', 'my-wordpress-site'); // change this 
define('LAST9_OTEL_ENVIRONMENT', 'production'); // change this

// Optional - Feature toggles
define('LAST9_OTEL_ENABLE_TRACING', true);
define('LAST9_OTEL_ENABLE_ERROR_TRACKING', true);
define('LAST9_OTEL_ENABLE_BROWSER', false);
define('LAST9_OTEL_ENABLE_DB_TRACING', true);
define('LAST9_OTEL_ENABLE_HTTP_TRACING', true);

// Optional - Sampling for high-traffic sites
define('LAST9_OTEL_TRACE_SAMPLE_RATE', 1.0);  // 0.0 to 1.0

Note: Constants in wp-config.php take priority over admin UI settings.

Requirements

• PHP 8.0 or higher
• WordPress 5.8 or higher
• Composer (for dependency installation)

Architecture

last9-wordpress-plugin/
├── docker-compose.yaml          # Development environment
├── Dockerfile                   # WordPress + PHP setup
├── otel-collector-config.yaml   # Local collector for testing
└── last9-otel/                  # WordPress plugin
    ├── last9-otel.php           # Main plugin file
    ├── composer.json            # PHP dependencies
    ├── includes/
    │   ├── class-last9-otel-tracer.php        # Distributed tracing
    │   ├── class-last9-otel-error-handler.php # Error/exception capture
    │   ├── class-last9-otel-browser.php       # Browser SDK integration
    │   ├── class-last9-otel-settings.php      # Configuration management
    │   ├── class-last9-otel-admin.php         # Admin UI
    │   ├── class-last9-otel-plugins.php       # Plugin loading tracing
    │   ├── class-last9-otel-transients.php    # Cache operation tracing
    │   └── class-last9-otel-user-context.php  # User context enrichment
    └── assets/js/
        └── last9-otel-init.js   # Browser SDK initialization

Testing Without Last9

The included Docker setup runs a local OpenTelemetry Collector that logs traces to console:

# Start services
docker compose up -d

# View traces in collector logs
docker compose logs -f otel-collector

Configure the plugin with:

• Endpoint: http://otel-collector:4318
• Authorization: (leave empty)

Hooks & Filters

Customize plugin behavior with WordPress hooks:

// Add custom resource attributes
add_filter('last9_otel_resource_attributes', function($attributes) {
    $attributes['deployment.region'] = 'us-east-1';
    return $attributes;
});

// Add custom user attributes
add_filter('last9_otel_user_attributes', function($attributes, $user) {
    $attributes['user.plan'] = get_user_meta($user->ID, 'subscription_plan', true);
    return $attributes;
}, 10, 2);

// Ignore specific errors
add_filter('last9_otel_ignore_error', function($ignore, $message, $file) {
    if (strpos($file, 'deprecated-plugin') !== false) {
        return true;
    }
    return $ignore;
}, 10, 3);

Manual Instrumentation

Create custom spans in your code:

$tracer = last9_otel()->get_tracer();

if ($tracer) {
    $span = $tracer->start_span('my-custom-operation', [
        'custom.attribute' => 'value',
    ]);

    try {
        // Your code here
    } finally {
        $span->end();
    }
}

Performance Considerations

For high-traffic sites:

1. Reduce sample rate: Set LAST9_OTEL_TRACE_SAMPLE_RATE to 0.1 - 0.5
2. Disable verbose tracing: Keep LAST9_OTEL_ENABLE_HOOK_TRACING disabled
3. Use PHP extension: Install the OpenTelemetry PHP extension for better performance

Installation Options

Option 1: Download Release ZIP (Easiest)

1. Go to Releases
2. Download the latest last9-otel-x.x.x.zip
3. In WordPress Admin: Plugins > Add New > Upload Plugin
4. Upload the ZIP and activate

Option 2: Clone and Build

cd wp-content/plugins/
git clone https://github.com/last9/last9-wordpress-plugin.git
cd last9-wordpress-plugin/last9-otel
composer install --no-dev --optimize-autoloader

Then activate "Last9 OpenTelemetry Integration" in WordPress Admin.

Contributing

Contributions are welcome! Please read our contributing guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: composer test (if available)
5. Commit with clear messages
6. Push and create a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/last9-wordpress-plugin.git
cd last9-wordpress-plugin

# Start development environment
docker compose up -d

# Install PHP dependencies (for IDE support)
cd last9-otel && composer install

Support

• Documentation: docs.last9.io
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on OpenTelemetry PHP SDK