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.
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.
- 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 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 This property in milliseconds measures the operation time for this specific event.
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.
PHP 7.0 and later
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.
Please follow the three minute guide for supported installation instructions.
This example was also covered above, in the three minute guide
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");
}
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);
}
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);
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 |