OpenTelemetry.php

<?php

/**
 * OpenTelemetry plugin for Matomo.
 *
 * Copyright (C) Digitalist Open Cloud <cloud@digitalist.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

namespace Piwik\Plugins\OpenTelemetry;

use Piwik\Plugin;
use Piwik\Container\StaticContainer;
use OpenTelemetry\API\Globals;
use OpenTelemetry\API\Trace\SpanKind;
use OpenTelemetry\API\Trace\StatusCode;
use OpenTelemetry\Context\Context;
use OpenTelemetry\API\Baggage\Baggage;
use OpenTelemetry\API\Metrics\MeterInterface;
use Piwik\Plugins\OpenTelemetry\SystemSettings;
use Monolog\Logger;
use Piwik\Plugins\OpenTelemetry\Handler\OpenTelemetryHandler;
use Piwik\Log\LoggerInterface;

/***
 * Main class to create traces.
 */
class OpenTelemetry extends Plugin
{
    private static $activeSpan = null;
    private static $httpSpan = null;
    private static $httpTracer = null;
    private static $httpScope = null;
    private static $apiTracer = null;
    private static $meter = null;
    private static $apiDurationHistogram = null;
    private static $apiStartTime = null;
    private static $memoryHistogram = null;
    private static $archiveStartTime = null;
    private static $archiveDurationHistogram = null;
    private static $archiveRunsCounter = null;

    /**
     * Metrics for API requests.
     */
    private static function meter(): MeterInterface
    {
        if (!self::$meter) {
            self::$meter = Globals::meterProvider()->getMeter('matomo.api');
        }
        return self::$meter;
    }

    /**
     * Metrics for peak memory usage for request.
     */
    private static function memoryHistogram()
    {
        if (!self::$memoryHistogram) {
            self::$memoryHistogram = Globals::meterProvider()
                ->getMeter('matomo.php')
                ->createHistogram(
                    'matomo.php.memory.peak',
                    'By',
                    'Peak PHP memory usage per request'
                );
        }

        return self::$memoryHistogram;
    }

    private static function archiveMetrics()
    {
        if (!self::$archiveDurationHistogram) {
            $meter = \OpenTelemetry\API\Globals::meterProvider()
                ->getMeter('matomo.archive');

            self::$archiveDurationHistogram = $meter->createHistogram(
                'matomo.archive.duration',
                'ms',
                'Duration of Matomo core archive runs'
            );

            self::$archiveRunsCounter = $meter->createCounter(
                'matomo.archive.runs',
                '1',
                'Number of archive runs'
            );
        }
    }

    /**
     * The events we want to use for OpenTelemetry.
     * Also add needed JS files and variables for client tracing.
     */
    public function registerEvents(): array
    {
        return [
            'Http.sendHttpRequest' => 'onRequestStart',
            'Http.sendHttpRequest.end' => 'onRequestEnd',
            'API.Request.dispatch' => 'onApiStart',
            'API.Request.dispatch.end' => 'onApiEnd',
            'AssetManager.getJavaScriptFiles' => 'getJSFiles',
            'Template.jsGlobalVariables' => 'addJsVariables',
            'Platform.initialized' => 'attachOtelHandler',
            'CronArchive.init.start' => 'onArchiveStart',
            'CronArchive.end' => 'onArchiveEnd',

        ];
    }

    /**
     * Attach logger, to catch logs from Monolog.
     */
    public function attachOtelHandler(): void
    {
        $logger = StaticContainer::get('Psr\Log\LoggerInterface');

        if ($logger instanceof Logger) {
            $logger->pushHandler(
                new OpenTelemetryHandler(Logger::DEBUG)
            );
            //$logger->pushHandler(new NullHandler(Logger::DEBUG));
        }
    }

    /**
     * Normal HTTP requests in Matomo UI.
     */
    private static function httpTracer()
    {
        if (!self::$httpTracer) {
            self::$httpTracer = Globals::tracerProvider()->getTracer('matomo.http');
        }
        return self::$httpTracer;
    }

    /**
     * API requests, these happens often in Matomo UI.
     */
    private static function apiTracer()
    {
        if (!self::$apiTracer) {
            self::$apiTracer = Globals::tracerProvider()->getTracer('matomo.api');
        }
        return self::$apiTracer;
    }

    public function onArchiveStart(): void
    {
        // if (!self::$metricsEnabled) {
        //     return;
        // }

        self::$archiveStartTime = microtime(true);
    }

    public function onArchiveEnd(): void
    {
        // if (!self::$metricsEnabled || self::$archiveStartTime === null) {
        //     return;
        // }

        self::archiveMetrics();

        $durationMs = (microtime(true) - self::$archiveStartTime) * 1000;

        self::$archiveDurationHistogram->record($durationMs, [
            'process.runtime.name' => PHP_SAPI,
        ]);

        self::$archiveRunsCounter->add(1);

        self::$archiveStartTime = null;
    }

    /**
     * When request starts.
     */
    public function onRequestStart(): void
    {
        $propagator = Globals::propagator();
        $headers = [];

        foreach ($_SERVER as $key => $value) {
            if (str_starts_with($key, 'HTTP_')) {
                $headerName = strtolower(str_replace('_', '-', substr($key, 5)));
                $headers[$headerName] = $value;
            }
        }
        $parentContext = $propagator->extract($headers);

        Context::storage()->attach($parentContext);

        $tracer = self::httpTracer();

        self::$httpSpan = $tracer
            ->spanBuilder(
                ($_SERVER['REQUEST_METHOD'] ?? 'unknown') . ' ' . ($_SERVER['REQUEST_URI'] ?? '/')
            )
            ->setSpanKind(SpanKind::KIND_SERVER)
            ->setParent($parentContext)
            ->setAttribute('http.url', $_SERVER['REQUEST_URI'] ?? 'unknown')
            ->setAttribute('http.method', $_SERVER['REQUEST_METHOD'] ?? 'UNKNOWN')
            ->setStartTimestamp((int) (microtime(true) * 1e9))
            ->startSpan();
            // @todo: Not really working yet, set site id from baggage (js in this case), if we have it.
            $baggage = Baggage::getCurrent();
            $siteId = $baggage->getValue('matomo.site_id');
        if ($siteId !== null) {
            self::$httpSpan->setAttribute('matomo.site_id', $siteId);
        }

        self::$httpScope = self::$httpSpan->activate();
    }

    /**
     * HTTP request end.
     */
    public function onRequestEnd(): void
    {
        $peakMemory = memory_get_peak_usage(true);
        self::memoryHistogram()->record($peakMemory, [
            'process.runtime.name' => php_sapi_name(),
        ]);
        if (self::$httpSpan) {
            self::$httpSpan->setStatus(
                StatusCode::STATUS_OK
            );
            self::$httpSpan->setAttribute(
                'php.memory.peak',
                memory_get_peak_usage(true)
            );
            self::$httpSpan->end((int) (microtime(true) * 1e9));
            self::$httpSpan = null;
        }
    }

    /**
     * API start event.
     */
    public function onApiStart(): void
    {
        $tracer = self::apiTracer();

        self::$apiStartTime = microtime(true);
        if (!self::$apiDurationHistogram) {
            self::$apiDurationHistogram = self::meter()
                ->createHistogram(
                    'matomo.api.request.duration',
                    'ms',
                    'Duration of Matomo API requests'
                );
        }

        self::$activeSpan = $tracer
            ->spanBuilder('API ' . ($_GET['method'] ?? 'unknown'))
            ->setSpanKind(SpanKind::KIND_SERVER)
            ->setAttribute('matomo.api.method', $_GET['method'] ?? 'unknown')
            ->setAttribute('http.method', $_SERVER['REQUEST_METHOD'] ?? 'unknown')
            ->setStartTimestamp((int) (microtime(true) * 1e9))
            ->startSpan();

        self::$activeSpan->activate();
    }

    /**
     * API end event.
     */
    public function onApiEnd(): void
    {
        if (self::$activeSpan) {
            $durationMs = null;
            $peakMemory = memory_get_peak_usage(true);

            self::memoryHistogram()->record($peakMemory, [
                'process.runtime.name' => php_sapi_name(),
            ]);

            if (self::$apiStartTime !== null) {
                $durationMs = (microtime(true) - self::$apiStartTime) * 1000;
            }

            $attributes = [
                'matomo.api.method' => $_GET['method'] ?? 'unknown',
                'http.method' => $_SERVER['REQUEST_METHOD'] ?? 'unknown',
                'http.status_code' => http_response_code() ?: 200,
                'php.memory.peak' => memory_get_peak_usage(true),
            ];
            if ($durationMs !== null && self::$apiDurationHistogram) {
                self::$apiDurationHistogram->record(
                    $durationMs,
                    $attributes
                );
            }
            self::$activeSpan->setAttribute('http.status_code', $attributes['http.status_code']);
            self::$activeSpan->setStatus(StatusCode::STATUS_OK);
            self::$activeSpan->end();

            self::$activeSpan = null;
            self::$apiStartTime = null;
        }
    }

    /**
     * Attach needed javascript files.
     */
    public function getJSFiles(&$files)
    {
        $files[] = 'plugins/OpenTelemetry/js/start.js';
        $files[] = 'plugins/OpenTelemetry/js/otel.min.js';
    }

    /**
     * Get needed JavaScript variables from Matomo.
     */
    public function addJsVariables(&$out)
    {
        $settings = new SystemSettings();

        $enabled = (bool) $settings->enabled->getValue();
        $enableDocumentLoadMonitoring = (bool) $settings->enableDocumentLoadMonitoring->getValue();
        $enableUserInteractionMonitoring = (bool) $settings->enableUserInteractionMonitoring->getValue();
        $enableXMLHttpRequestMonitoring = (bool) $settings->enableXMLHttpRequestMonitoring->getValue();
        $enableWebVitals  = (bool) $settings->enableWebVitals->getValue();
        $enableUxMonitoring = (bool) $settings->enableUxMonitoring->getValue();

        $serviceName = $settings->serviceName->getValue();
        $otelEndpoint = $settings->otelEndpoint->getValue();
        $resourceAttributes = $settings->resourceAttributes->getValue();

        $out .= "piwik.openTelemetryEnabled = " . json_encode($enabled) . ";\n";
        $out .= "piwik.openTelemetryServiceName = " . json_encode($serviceName) . ";\n";
        $out .= "piwik.openTelemetryEndpoint = " . json_encode($otelEndpoint) . ";\n";
        $out .= "piwik.openTelemetryDocumentLoadMonitoring = " . json_encode($enableDocumentLoadMonitoring) . ";\n";
        $out .= "piwik.openTelemetryUserInteractionMonitoring = " . json_encode($enableUserInteractionMonitoring) . ";\n";
        $out .= "piwik.openTelemetryXMLHttpRequestMonitoring= " . json_encode($enableXMLHttpRequestMonitoring) . ";\n";
        $out .= "piwik.openTelemetryWebVitals = " . json_encode($enableWebVitals) . ";\n";
        $out .= "piwik.openTelemetryUxMonitoring = " . json_encode($enableUxMonitoring) . ";\n";
        $out .= "piwik.openTelemetryResourceAttributes = " . json_encode($resourceAttributes) . ";\n";
    }
}