Merge pull request #643 from rollbar/changed/telemetry-event-type-and…

…-level-to-enums Changed telemetry event type and level to enums.
rollbar · Dec 20, 2024 · 5d78046 · 5d78046
2 parents 7a1799f + 078f101
commit 5d78046
Show file tree

Hide file tree

Showing 11 changed files with 146 additions and 130 deletions.
diff --git a/composer.json b/composer.json
@@ -31,7 +31,7 @@
   },
 
   "require": {
-    "php": ">=8.0.0 <9.0",
+    "php": ">=8.1.0 <9.0",
     "ext-curl": "*",
     "psr/log": "^1 || ^2 || ^3",
     "monolog/monolog": "^2 || ^3"

diff --git a/src/Payload/TelemetryEvent.php b/src/Payload/TelemetryEvent.php
@@ -3,7 +3,8 @@
 namespace Rollbar\Payload;
 
 use Rollbar\SerializerInterface;
-use Rollbar\Telemetry\DataType;
+use Rollbar\Telemetry\EventLevel;
+use Rollbar\Telemetry\EventType;
 use Rollbar\UtilitiesTrait;
 
 /**
@@ -25,22 +26,21 @@ class TelemetryEvent implements SerializerInterface
      *
      * Some types should be accompanied by specific data in the body.
      *
-     * - If $type is {@see DataType::LOG}, the body should contain "message" key.
-     * - If $type is {@see DataType::NETWORK}, the body should contain "method", "url", and "status_code" keys.
-     * - If $type is {@see DataType::NAVIGATION}, the body should contain "from" and "to" keys.
-     * - If $type is {@see DataType::ERROR}, the body should contain "message" key.
+     * - If $type is {@see EventType::Log}, the body should contain "message" key.
+     * - If $type is {@see EventType::Network}, the body should contain "method", "url", and "status_code" keys.
+     * - If $type is {@see EventType::Navigation}, the body should contain "from" and "to" keys.
+     * - If $type is {@see EventType::Error}, the body should contain "message" key.
      *
-     * @param string              $type      The type of telemetry data. One of: {@see DataType}.
-     * @param string              $level     The severity level of the telemetry data. One of: "critical", "error",
-     *                                       "warning", "info", or "debug".
+     * @param EventType           $type      The type of telemetry data.
+     * @param EventLevel          $level     The severity level of the telemetry data.
      * @param array|TelemetryBody $body      Additional data for the telemetry event. If an array is provided, it will
      *                                       be converted to a {@see TelemetryBody} object.
      * @param float|null          $timestamp When this occurred, as a unix timestamp in milliseconds. If not provided,
      *                                       Rollbar will use the current time.
      */
     public function __construct(
-        public string $type,
-        public string $level,
+        public EventType $type,
+        public EventLevel $level,
         array|TelemetryBody $body,
         public ?float $timestamp = null,
     ) {
@@ -55,8 +55,8 @@ public function serialize(): array
         $result = array_filter([
             'uuid' => $this->uuid,
             'source' => $this->source,
-            'level' => $this->level,
-            'type' => $this->type,
+            'level' => $this->level->value,
+            'type' => $this->type->value,
             'body' => $this->body->serialize(),
             'timestamp_ms' => $this->timestamp,
         ]);

diff --git a/src/Rollbar.php b/src/Rollbar.php
@@ -10,6 +10,8 @@
 use Rollbar\Handlers\ExceptionHandler;
 use Rollbar\Payload\TelemetryBody;
 use Rollbar\Payload\TelemetryEvent;
+use Rollbar\Telemetry\EventLevel;
+use Rollbar\Telemetry\EventType;
 use Rollbar\Telemetry\Telemeter;
 use Stringable;
 use Throwable;
@@ -403,10 +405,8 @@ public static function emergency(string|Stringable $message, array $context = ar
     /**
      * Captures a telemetry event that may be sent with future payloads.
      *
-     * @param string              $type      The type of telemetry data. One of: "log", "network", "dom", "navigation",
-     *                                       "error", or "manual".
-     * @param string              $level     The severity level of the telemetry data. One of: "critical", "error",
-     *                                       "warning", "info", or "debug".
+     * @param EventType           $type      The type of telemetry data
+     * @param EventLevel          $level     The severity level of the telemetry data.
      * @param array|TelemetryBody $metadata  Additional data about the telemetry event.
      * @param string|null         $uuid      The Rollbar UUID to associate with this telemetry event.
      * @param int|null            $timestamp When this occurred, as a unix timestamp in milliseconds. If not provided,
@@ -418,8 +418,8 @@ public static function emergency(string|Stringable $message, array $context = ar
      * @since 4.1.0
      */
     public static function captureTelemetryEvent(
-        string $type,
-        string $level,
+        EventType $type,
+        EventLevel $level,
         array|TelemetryBody $metadata,
         ?string $uuid = null,
         ?int $timestamp = null,

diff --git a/src/RollbarLogger.php b/src/RollbarLogger.php
@@ -7,6 +7,8 @@
 use Psr\Log\LoggerInterface;
 use Rollbar\Payload\TelemetryBody;
 use Rollbar\Payload\TelemetryEvent;
+use Rollbar\Telemetry\EventLevel;
+use Rollbar\Telemetry\EventType;
 use Rollbar\Telemetry\Telemeter;
 use Stringable;
 use Throwable;
@@ -305,10 +307,8 @@ public function report(
     /**
      * Captures a telemetry event that may be sent with future payloads.
      *
-     * @param string              $type      The type of telemetry data. One of: "log", "network", "dom", "navigation",
-     *                                       "error", or "manual".
-     * @param string              $level     The severity level of the telemetry data. One of: "critical", "error",
-     *                                       "warning", "info", or "debug".
+     * @param EventType           $type      The type of telemetry data.
+     * @param EventLevel          $level     The severity level of the telemetry data.
      * @param array|TelemetryBody $metadata  Additional data about the telemetry event.
      * @param string|null         $uuid      The Rollbar UUID to associate with this telemetry event.
      * @param int|null            $timestamp When this occurred, as a unix timestamp in milliseconds. If not provided,
@@ -320,8 +320,8 @@ public function report(
      * @since 4.1.0
      */
     public function captureTelemetryEvent(
-        string $type,
-        string $level,
+        EventType $type,
+        EventLevel $level,
         array|TelemetryBody $metadata,
         ?string $uuid = null,
         ?int $timestamp = null,

diff --git a/src/Telemetry/EventLevel.php b/src/Telemetry/EventLevel.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace Rollbar\Telemetry;
+
+/**
+ * The level of the telemetry event.
+ *
+ * @since 4.1.0
+ */
+enum EventLevel: string
+{
+    case Debug = 'debug';
+
+    case Info = 'info';
+
+    case Warning = 'warning';
+
+    case Error = 'error';
+
+    case Critical = 'critical';
+}
diff --git a/src/Telemetry/DataType.php → src/Telemetry/EventType.php b/src/Telemetry/DataType.php → src/Telemetry/EventType.php
@@ -5,25 +5,23 @@
 /**
  * The type of the telemetry event.
  *
- * This should be replaced by an enum when we only support PHP >= 8.1.
- *
  * @since 4.1.0
  */
-class DataType
+enum EventType: string
 {
-    const LOG = 'log';
+    case Log = 'log';
 
-    const NETWORK = 'network';
+    case Network = 'network';
 
     /**
      * This is intended for use with browsers, and is only included here for API completeness. Generally, this should
      * not be used in a PHP context.
      */
-    const DOM = 'dom';
+    case DOM = 'dom';
 
-    const NAVIGATION = 'navigation';
+    case Navigation = 'navigation';
 
-    const ERROR = 'error';
+    case Error = 'error';
 
-    const MANUAL = 'manual';
+    case Manual = 'manual';
 }
diff --git a/src/Telemetry/Telemeter.php b/src/Telemetry/Telemeter.php
@@ -53,31 +53,31 @@ public function __construct(
      * Returns the Rollbar telemetry type that corresponds to the given PSR-3 log level.
      *
      * @param string $level The PSR-3 log level.
-     * @return string
+     * @return EventType
      */
-    private static function getTypeFromLevel(string $level): string
+    private static function getTypeFromLevel(string $level): EventType
     {
         return match ($level) {
-            Level::EMERGENCY, Level::ALERT, Level::CRITICAL, Level::ERROR, Level::WARNING => DataType::ERROR,
-            Level::NOTICE, Level::INFO => DataType::LOG,
-            default => DataType::MANUAL,
+            Level::EMERGENCY, Level::ALERT, Level::CRITICAL, Level::ERROR, Level::WARNING => EventType::Error,
+            Level::NOTICE, Level::INFO => EventType::Log,
+            default => EventType::Manual,
         };
     }
 
     /**
      * Returns the Rollbar telemetry level that corresponds to the given PSR-3 log level.
      *
      * @param string $level The PSR-3 log level.
-     * @return string
+     * @return EventLevel
      */
-    private static function getLevelFromLevel(string $level): string
+    private static function getLevelFromPsrLevel(string $level): EventLevel
     {
         return match ($level) {
-            Level::EMERGENCY, Level::ALERT, Level::CRITICAL => 'critical',
-            Level::ERROR => 'error',
-            Level::WARNING => 'warning',
-            Level::DEBUG => 'debug',
-            default => 'info',
+            Level::EMERGENCY, Level::ALERT, Level::CRITICAL => EventLevel::Critical,
+            Level::ERROR => EventLevel::Error,
+            Level::WARNING => EventLevel::Warning,
+            Level::DEBUG => EventLevel::Debug,
+            default => EventLevel::Info,
         };
     }
 
@@ -161,10 +161,8 @@ public function push(TelemetryEvent $event): void
     /**
      * Captures a telemetry event and adds it to the queue.
      *
-     * @param string              $type      The type of telemetry data. One of: "log", "network", "dom", "navigation",
-     *                                       "error", or "manual".
-     * @param string              $level     The severity level of the telemetry data. One of: "critical", "error",
-     *                                       "warning", "info", or "debug".
+     * @param EventType           $type      The type of telemetry data.
+     * @param EventLevel          $level     The severity level of the telemetry data.
      * @param array|TelemetryBody $metadata  Additional data about the telemetry event.
      * @param string|null         $uuid      The Rollbar UUID to associate with this telemetry event.
      * @param int|null            $timestamp When this occurred, as a unix timestamp in milliseconds. If not provided,
@@ -173,8 +171,8 @@ public function push(TelemetryEvent $event): void
      * @return TelemetryEvent|null
      */
     public function capture(
-        string $type,
-        string $level,
+        EventType           $type,
+        EventLevel          $level,
         array|TelemetryBody $metadata,
         ?string $uuid = null,
         ?int $timestamp = null,
@@ -200,9 +198,7 @@ public function capture(
      *                                                       as the message. If an array is given, it will be used as
      *                                                       the metadata body. If an ErrorWrapper is given, it will be
      *                                                       parsed for the message and stack trace.
-     * @param string                              $level     The severity level of the telemetry data. One of:
-     *                                                       "critical", "error", "warning", "info", or "debug".
-     *                                                       Defaults to "error".
+     * @param EventLevel                          $level     The severity level of the telemetry data.
      * @param string|null                         $uuid      The Rollbar UUID to associate with this telemetry event.
      * @param int|null                            $timestamp When this occurred, as a unix timestamp in milliseconds. If
      *                                                       not provided, the current time will be used.
@@ -212,38 +208,37 @@ public function capture(
      */
     public function captureError(
         array|string|ErrorWrapper|Throwable $error,
-        string $level = 'error',
+        EventLevel $level = EventLevel::Error,
         ?string $uuid = null,
         ?int $timestamp = null,
     ): ?TelemetryEvent {
         if (is_string($error)) {
-            return $this->capture('error', $level, new TelemetryBody(message: $error), $uuid, $timestamp);
+            return $this->capture(EventType::Error, $level, new TelemetryBody(message: $error), $uuid, $timestamp);
         }
         if ($error instanceof ErrorWrapper) {
             $metadata = new TelemetryBody(
                 message: $error->getMessage(),
                 subtype: 'error',
                 stack: $this->stringifyBacktrace($error->getBacktrace()),
             );
-            return $this->capture('error', $level, $metadata, $uuid, $timestamp);
+            return $this->capture(EventType::Error, $level, $metadata, $uuid, $timestamp);
         }
         if ($error instanceof Throwable) {
             $metadata = new TelemetryBody(
                 message: $error->getMessage(),
                 subtype: 'exception',
                 stack: $this->stringifyBacktrace($error->getTrace())
             );
-            return $this->capture('error', $level, $metadata, $uuid, $timestamp);
+            return $this->capture(EventType::Error, $level, $metadata, $uuid, $timestamp);
         }
-        return $this->capture('error', $level, $error, $uuid, $timestamp);
+        return $this->capture(EventType::Error, $level, $error, $uuid, $timestamp);
     }
 
     /**
      * Captures a log message as a telemetry event and adds it to the queue.
      *
      * @param string      $message   The log message to capture.
-     * @param string      $level     The severity level of the telemetry data. One of: "critical", "error", "warning",
-     *                               "info", or "debug". Defaults to "info".
+     * @param EventLevel  $level     The severity level of the telemetry data.
      * @param string|null $uuid      The Rollbar UUID to associate with this telemetry event.
      * @param int|null    $timestamp When this occurred, as a unix timestamp in milliseconds. If not provided, the
      *                               current time will be used.
@@ -252,11 +247,11 @@ public function captureError(
      */
     public function captureLog(
         string $message,
-        string $level = 'info',
+        EventLevel $level = EventLevel::Info,
         ?string $uuid = null,
         ?int $timestamp = null,
     ): ?TelemetryEvent {
-        return $this->capture('log', $level, new TelemetryBody(message: $message), $uuid, $timestamp);
+        return $this->capture(EventType::Log, $level, new TelemetryBody(message: $message), $uuid, $timestamp);
     }
 
     /**
@@ -265,8 +260,7 @@ public function captureLog(
      * @param string      $method      The HTTP method. E.g. GET, POST, etc.
      * @param string      $url         The URL of the request.
      * @param string      $status_code The HTTP status code.
-     * @param string      $level       The severity level of the telemetry data. One of: "critical", "error", "warning",
-     *                                 "info", or "debug". Defaults to "info".
+     * @param EventLevel  $level       The severity level of the telemetry data.
      * @param string|null $uuid        The Rollbar UUID to associate with this telemetry event.
      * @param int|null    $timestamp   When this occurred, as a unix timestamp in milliseconds. If not provided, the
      *                                 current time will be used.
@@ -277,12 +271,12 @@ public function captureNetwork(
         string $method,
         string $url,
         string $status_code,
-        string $level = 'info',
+        EventLevel $level = EventLevel::Info,
         ?string $uuid = null,
         ?int $timestamp = null,
     ): ?TelemetryEvent {
         return $this->capture(
-            type: 'log',
+            type: EventType::Log,
             level: $level,
             metadata: new TelemetryBody(
                 method: $method,
@@ -299,8 +293,7 @@ public function captureNetwork(
      *
      * @param string      $from      The URL of the previous page.
      * @param string      $to        The URL of the next page.
-     * @param string      $level     The severity level of the telemetry data. One of: "critical", "error", "warning",
-     *                               "info", or "debug". Defaults to "info".
+     * @param EventLevel  $level     The severity level of the telemetry data.
      * @param string|null $uuid      The Rollbar UUID to associate with this telemetry event.
      * @param int|null    $timestamp When this occurred, as a unix timestamp in milliseconds. If not provided, the
      *                               current time will be used.
@@ -310,11 +303,11 @@ public function captureNetwork(
     public function captureNavigation(
         string $from,
         string $to,
-        string $level = 'info',
+        EventLevel $level = EventLevel::Info,
         ?string $uuid = null,
         ?int $timestamp = null,
     ): ?TelemetryEvent {
-        return $this->capture('log', $level, new TelemetryBody(from: $from, to: $to), $uuid, $timestamp);
+        return $this->capture(EventType::Log, $level, new TelemetryBody(from: $from, to: $to), $uuid, $timestamp);
     }
 
     /**
@@ -348,7 +341,7 @@ public function captureRollbarItem(
         }
         // Make sure to respect the PSR exception context. See https://www.php-fig.org/psr/psr-3/#13-context.
         if (($context['exception'] ?? null) instanceof Throwable) {
-            $event = $this->captureError($context['exception'], self::getLevelFromLevel($level), $uuid);
+            $event = $this->captureError($context['exception'], self::getLevelFromPsrLevel($level), $uuid);
             if (null === $event) {
                 return null;
             }
@@ -361,12 +354,12 @@ public function captureRollbarItem(
         }
         // If the rollbar item is an exception, we should capture it as an error event.
         if ($message instanceof Throwable) {
-            return $this->captureError($message, self::getLevelFromLevel($level), $uuid);
+            return $this->captureError($message, self::getLevelFromPsrLevel($level), $uuid);
         }
         // Otherwise, we will capture it based on the level.
         return $this->capture(
             type: self::getTypeFromLevel($level),
-            level: self::getLevelFromLevel($level),
+            level: self::getLevelFromPsrLevel($level),
             metadata: new TelemetryBody(message: $this->getRollbarItemMessage($message)),
             uuid: $uuid,
         );