Skip to content

Latest commit

 

History

History
167 lines (123 loc) · 8.55 KB

README.md

File metadata and controls

167 lines (123 loc) · 8.55 KB
Raw

Trakerr - PHP API client

Build Status

Get your application events and errors to Trakerr via the Trakerr API.

You can send both errors and non-errors (plain log statements, for example) to Trakerr with this API.

Overview

The 3-minute integration guide is primarily oriented around sending errors or warnings and does not let you specify additional parameters. Option-4 in the detailed integration guide describes how you could send a non-exception (or any log statement) along with any additional parameters.

The SDK takes performance impact seriously and all communication between the SDK <=> Trakerr avoids blocking the calling function. The SDK also applies asynchronous patterns where applicable.

A Trakerr Event can consist of various parameters as described here in TrakerrApi.AppEvent. Some of these parameters are populated by default and others are optional and can be supplied by you.

Since some of these parameters are common across all event's, the API has the option of setting these on the TrakerrClient instance (described towards the bottom) and offers a factory API for creating AppEvent's.

Key AppEvent Properties

Log Level, Event Type and Classification

  • Log Level This enum specifies the logging level to be used for this event ('debug','info','warning','error' or 'fatal')
  • Event Type This defines the type of event or logger name. This is automatically set for errors.
  • Classification This is a user settable property that controls how the events are grouped. Defaults to 'Issue'. Set this to a different value to group this event in a different group.

Event User, Event Session and Correlation ID

  • Event User This is the user that is associated with this event. This can be any user data or could be encrypted if privacy is required.
  • Event Session This is any session specific information associated with this event.
  • Cross App Correlation ID This is an additional ID that can be used for cross-application correlation of the same event.

Operation Time

  • Operation Time This property in milliseconds measures the operation time for this specific event.

Custom properties and segments

In addition to the above, you can use custom properties and segments to send custom event, performance data. These can then be visualized in Trakerr's dashboards.

Requirements

PHP 7.0 and later

3-minute Integration Guide

Install the bindings via Composer, add the following to composer.json:

{
  "repositories": [
    {
      "type": "git",
      "url": "https://github.com/trakerr-io/trakerr-php.git"
    }
  ],
  "require": {
    "trakerr/trakerr-php": "*@dev"
  }
}

Then run composer install. This should make it easy to keep the API up to date.

If you are not using composer download all the files and include autoload.php:

require_once(__DIR__ . '/../autoload.php');

Finally, in your code call:

$trakerrClient = new \trakerr\TrakerrClient("<api-key>", "App version here", "Deployment stage here");
$trakerrClient->registerErrorHandlers();

That should activate a global error handler for you to use. This will capture any Errors and Fatals that occur.

Detailed Integration Guide

Installation

Please follow the three minute guide for supported installation instructions.

Option-1: Register global event handler

This example was also covered above, in the three minute guide

Option-2: Sent event programmatically

Send an event to trackerr within a try catch to handle an event while sending it to trakerr. Simply call send error from catch statement, and pass in an error and the loglevel and classification.

$trakerrClient = new \trakerr\TrakerrClient("<api-key>", "App version here", "Deployment stage here");
    // Option-2: catch and send error to Trakerr programmatically
try {
    throw new Exception("test exception");
} catch (Exception $e) {
    $trakerrClient->sendError($e, "fatal");
}

Option-3: Send event programmatically but with custom properties

You can send custom properties from an event which is being handled. Create a new AppEvent through the APIand populate the instance with the custom data that you want. Be sure to send the event to trakerr after you are done!

    // Option-3: catch and send error to Trakerr with some custom data programmatically
    use trakerr\client\model\CustomData;
    use trakerr\client\model\CustomStringData;

    try {
        throw new Exception("Too much math");
    } catch (Exception $e) {
        $appEvent2 = $trakerrClient->createAppEventFromException($e, "Error");

        // set some custom data
        $customProperties = new CustomData();
        $customStringData = new CustomStringData();
        $customStringData->setCustomData1("Some custom data");
        $customProperties->setStringData($customStringData);
        $appEvent2->setCustomProperties($customProperties);

        $trakerrClient->sendEvent($appEvent2);
    }

Option-4: Create an event (eg. non-exception) and send it to Trakerr

Trakerr accepts non errors and application events. We suggest that you send the user and session, along with setting the event name, message, at the least before sending it to Trakerr.

     // Option-4: send any event programmatically
    $appEvent = $trakerrClient->createAppEvent("warning", "type warn", "TestType", "Test message from php");

    $trakerrClient->sendEvent($appEvent);

About TrakerrClient's properties

The TrakerrClient class above can be constructed to take aditional data, rather than using the configured defaults. The constructor signature is:

public function __construct($apiKey, $contextAppVersion = "1.0",
$contextDeploymentStage = "development")

The TrakerrClient class however has a lot of exposed properties. The benefit to setting these immediately after after you create the TrakerrClient is that AppEvent will default it's values against the TrakerClient that created it. This way if there is a value that all your AppEvents uses, and the constructor default value currently doesn't suit you; it may be easier to change it in TrakerrClient as it will become the default value for all AppEvents created after. A lot of these are populated by default value by the constructor, but you can populate them with whatever string data you want. The following table provides an in depth look at each of those.

If you're populating an app event directly, you'll want to take a look at the AppEvent properties as they contain properties unique to each AppEvent which do not have defaults you may set in the client.

Name Type Description Notes
apiKey string API Key for your application.
contextAppVersion string Provide the application version. Default Value: 1.0
contextDevelopmentStage string One of development, staging, production; or a custom string. Default Value: development
contextEnvLanguage string Constant string representing the language the application is in. Default value: php.
contextEnvName string Name of the CLR the program is running on Defaults value: php
contextEnvVersion string Provide an environment version. Defaults Value: PHP_VERSION_ID.
contextEnvHostname string Provide the current hostname. Defaults Value: gethostname().
contextAppOS string Provide an operating system name. Defaults Value: php_uname("s").
contextAppOSVersion string Provide an operating system version. Default Value: php_uname("v").
contextAppOSBrowser string An optional string browser name the application is running on. Defaults to NULL
contextAppOSBrowserVersion string An optional string browser version the application is running on. Defaults to NULL
contextDataCenter string Data center the application is running on or connected to. Defaults to NULL
contextDataCenterRegion string Data center region. Defaults to NULL
context_tags string[] Any tags that describe the the module that this handler is for. Defaults to NULL

Documentation For Models