Added support for the Telemetry feature.

[danielmorell]

Description of the change

This is adds support for the Telemetry feature.

Design decisions and overview of the change.

1. Rollbar Items: Occurrences and log items that are captured by the SDK's error monitoring or manually reported may be included in the telemetry data of subsequently reported items.
2. Telemetry is enabled by default.
3. The only telemetry events captured by the core SDK are the errors/logs reported or captured by the SDK prior to the current report. This means that if a non-fatal error occurs it will be included in the telemetry data a subsequent error as long as they both share the same process. Our packages for frameworks like Laravel or Symfony may choose to have some default telemetry events that are tailored for those frameworks, but there are none included in the core SDK by default.
   Note: some of our other programing language SDKs capture things like log messages and other items in the telemetry data as part of an auto instrumentation setup. Trying to do this in PHP would require messing with things that could break logging for end user applications. Since most projects will have some sort of logging built in this could easily be wired to the telemeter to capture debug logs etc.
4. A custom filter can be created to reduce noise in the telemetry data if logs are being included.
5. To help reduce the size of large payloads being sent to the Rollbar backend an optional TelemetryStrategy truncation strategy has been included. This is not enabled by default but can be added if large telemetry sets are reducing the quality of the stack frame data.
6. The Telemeter instance is statically attached to the Rollbar class so that the telemetry data is preserved on reconfiguration of the SDK.
7. The telemetry data can be manually cleared if needed.
8. Setting the telemetry configuration to null or false or calling Rollbar::destroy() will remove the telemeter and all the events in the queue.

There are probably more details that are important. Feel free to ask questions in the comments.

New configs

The telemetry key is now supported in the configs array. It can have any of the following values:

1. null or false will disable capturing and reporting of telemetry events.
2. true or [] will result in telemetry being enabled with the default settings.
3. An array of further configs can be provided.

   Rollbar::init([
       // other configs
       'telemetry' => [
           'maxTelemetryEvents' => 100,
           'filter' => null,
           'includeItemsInTelemetry' => true,
           'includeIgnoredItemsInTelemetry' => false,
       ],
   ]);

'maxTelemetryEvents' int Should be the most events that will be retained or reported at any given time. If more events are captured they will be removed in a FIFO order. This defaults to 100.

'filter' null|string This is a custom filter FQCN for a telemetry filter class that implements the Rollbar\Telemetry\TelemetryFilterInterface interface. See the extensive comments on TelemetryFilterInterface for implementation details. This defaults to null.

'includeItemsInTelemetry' bool Set to true to include errors, logs, and other items captured/reported to the SDK in the telemetry data of subsequent reports. If false they will not be included. This defaults to true.

'includeIgnoredItemsInTelemetry' bool Set to true to include items that have been ignored by the SDK in the telemetry data. This defaults to false.

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Maintenance
• New release

Related issues

• Fix Telemetry support #349

Checklists

Development

• Lint rules pass locally
• The code changed/added as part of this pull request has been covered with tests
• All tests related to the changed code pass in development

Code review

• This pull request has a descriptive title and information useful to a reviewer. There may be a screenshot or screencast attached
• "Ready for review" label attached to the PR and reviewers assigned
• Issue from task tracker has a link to this pull request
• Changes have been reviewed by at least one other engineer

[waltjones]

@danielmorell Looks good. In other SDKs there are typically wrappers for the standard logging, network access, etc. so those are enabled without the user needing to implement them. This PR is still relevant, as those wrappers can call the captureX methods provided here.

[armetiz]

Is 4.1 will be released?

Regards

[danielmorell]

We should have 4.1 out by the end of the month.

[manticorp]

This is extremely useful, especially when getting fatal errors that don't have stack traces which can be very hard to decode!

Would it be possible to add the link to PHP docs here?

https://docs.rollbar.com/docs/telemetry

There are docs here it seems:

https://docs.rollbar.com/docs/php-telemetry

For those who end up here looking for how to use this outside of the automatic telemetry events, this is the full captureTelemetryEvent signature as of 4.1.4 as a usage example:

<?php

use MyApp;
use Rollbar\Rollbar;
use Rollbar\Telemetry\EventType;
use Rollbar\Telemetry\EventLevel;
use Rollbar\Payload\TelemetryBody;

$start = microtime(true) * 1000;
$result = MyApp::someProcess($userInputString);
$end = microtime(true) * 1000;

/**
 * Creates the telemetry body.
 *
 * The `element` property is not included in the constructor because it intended for browser DOM events.
 *
 * @param string      $message            This should be included for errors and log events.
 * @param string      $method             This should be included for network events. The HTTP method. E.g. GET,
 *                                        POST, etc.
 * @param string      $url                This should be included for network events. The URL of the request.
 * @param string      $status_code        This should be included for network events. The HTTP status code.
 * @param string      $subtype            This can be used to further classify the event. Internally, we use this to
 *                                        distinguish between errors and exceptions for error events.
 * @param string|null $stack              The stack trace of the error or exception. This should be included for
 *                                        error events.
 * @param string      $from               This should be included for navigation events. The URL of the previous
 *                                        page.
 * @param string      $to                 This should be included for navigation events. The URL of the next page.
 * @param int|null    $start_timestamp_ms The start time of the event in milliseconds since the Unix epoch.
 * @param int|null    $end_timestamp_ms   The end time of the event in milliseconds since the Unix epoch.
 * @param mixed       ...$extra           Any extra data to include in the telemetry body.
 */
Rollbar::captureTelemetryEvent(
    type: EventType::Log,
    level: EventLevel::Info,
    uuid: guid(),
    timestamp: $start,
    metadata: new TelemetryBody(
      message = 'MyApp::someProcess called with ' . ((string) $userInputString),
      method = '',
      url = '',
      status_code = '',
      subtype = '',
      stack = null,
      from = '',
      to = '',
      start_timestamp_ms = $start,
      end_timestamp_ms = $end,
      extra = ['result' => $result]
    ),
);

We use PHP as a worker outside of web requests so being able to include telemetry is a massive gain!