Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history 
Updated for release.
  • Loading branch information
@RMSD
RMSD authored Mar 28, 2017
1 parent f6473a8 commit bae7dd9
Showing 1 changed file with 72 additions and 82 deletions.
154 changes: 72 additions & 82 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,53 +22,9 @@ import trakerr

## Getting Started

Please follow the [installation procedure](#installation--usage) and you're set to add Trakerr to your project. All of these examples are included in testmain.py.
Please follow the [installation procedure](#installation--usage) and you're set to add Trakerr to your project. All of these examples are included in test_sample_app.py.

### Option 1: Add Custom Data
You can send custom data as part of your error event if you need to. This circumvents the python handler. Add these imports:

```python
from trakerr import TrakerrClient
from trakerr_client.models import CustomData, CustomStringData
```

You'll then need to initialize custom properties once you create the event. Note that you can use the second call commented out to instead create an app event without a stacktrace.

```Python
def main(argv=None):
if argv is None:
argv = sys.argv

client = TrakerrClient("API Key here", "App Version number")

try:
raise IndexError("Bad Math")
except:
appevent = client.create_new_app_event_error("ERROR", "Index Error", "Math")

#You can use this call to create an app event
#appevent = client.create_new_app_event("ERROR", "Index Error", "Math")
#without a stacktrace, in case you do don't have a stacktrace or you're not sending a crash.

#Populate any field with your own data, or send your own custom data
appevent.context_app_os = "Windows 8"
appevent.custom_properties = CustomData("Custom Data holder!")

#Can support multiple string data
appevent.custom_properties.string_data = CustomStringData("Custom String Data 1", "Custom String Data 2")
appevent.custom_properties.string_data.custom_data3 = "More Custom Data!"

#populate the user and session to the error event
appevent.event_user = "john@traker.io"
appevent.event_session = "6"

#send it to trakerr
client.send_event_async(appevent)

return 0
```

### Option 2: Automatic initialization
### Option 1: Automatic initialization of the python logger
Along with your imports, add:

```python
Expand All @@ -92,7 +48,7 @@ def main(argv=None):
return 0
```

### Option 3: Manual initialization of the handler
### Option 2: Manual initialization of the handler, attach it to a python logger
You can initialize the handler directly and attach it to your own logger, if you want direct control over it. This is useful if you want your own custom logger. An example with the base logger follows.

You'll need to add these imports:
Expand All @@ -118,58 +74,92 @@ def main(argv=None):
return 0
```

## An in-depth look at initalizing Trakerr
Most of the examples above involve are initialized simply, since the error is populated with default values. If we take a look at the constructor, we see that there is actually plenty of fields we can fill in ourselves if we don't find the default value useful. Let's take a look at the `getlogger` Method, and the `TrakerrHandler` `__init__` since that's what `getLogger` fills in:

### Sending an error(or non-error) quickly without using the logger
You can quickly send a simple event with partial custom data from the log function of the `TrakerrClient`. Add these imports:

```python
def getLogger(self, api_key, app_version, name, context_env_name = platform.python_implementation(),
context_env_version = platform.python_version(), context_env_hostname = platform.node(),
context_appos = platform.system() + " " + platform.release(),
context_appos_version = platform.version(), datacenter = None, datacenter_region = None,
client = None, url = TrakerrUtils.SERVER_URL, level = logging.ERROR):
from trakerr import TrakerrClient
```

you can then send call log simply to send a quick error to Trakerr. Note the values that the argument dictionary takes are in the log docstring.

```python
client.log({"user":"jill@trakerr.io", "session":"25", "errname":"user logon issue",
"errmessage":"User refreshed the page."}, "info", "logon script", False)
```

Most of the call will be explained later since most of the arguments are passed down, but the `name` field is unique to `getLogger`. Name is simply the name `TrakerrHandler` object it stores internally for identification. It is required and should be unique, but Trakerr itself does not suggest a convention on naming `Handler` objects.
You can call this from an `except` if you wish to send an error with a stacktrace.

The constructor for `TrakerrHandler` takes the rest of the arguments itself. The handler object acts as an intermediary between the error and Trakerr's send layers; providing the error data from the handler on emit with external facing tools. Constructor wise, it will in turn pass most it's argument to the `TrakerrClient` class, to populate the send event with the data we passed the handler to hold onto. We exposed the arguments early so as to not have to dig through the initalized `TrakerrClient` later to change them. Here's TrakerrHandler's init function.
### Option 4: Add Custom Data
You can send custom data as part of your error event if you need to. This circumvents the python handler. Add these imports:

```python
def __init__(self, api_key, app_version, context_env_name = None,
context_env_version = None, context_env_hostname = None,
context_appos = None, context_appos_version = None,
datacenter = None, datacenter_region = None,
client = None, url = TrakerrUtils.SERVER_URL, level = logging.ERROR):
from trakerr import TrakerrClient
from trakerr_client.models import CustomData, CustomStringData
```

`client` lets an already initialized `TrakerrClient` object be passed in if you needed to initialize it seperately. Unless you have a need for it, leaving it none will simply create a new one instead, which should suit most cases.
You'll then need to initialize custom properties once you create the event. Note that you can use the second call commented out to instead create an app event without a stacktrace.

```Python
def main(argv=None):
if argv is None:
argv = sys.argv

client = TrakerrClient("API Key here", "App Version number")

try:
raise IndexError("Bad Math")
except:
appevent = client.create_new_app_event_error("ERROR", "Index Error", "Math")

#You can use this call to create an app event
#appevent = client.create_new_app_event("ERROR", "Index Error", "Math")
#without a stacktrace, in case you do don't have a stacktrace or you're not sending a crash.

#Populate any field with your own data, or send your own custom data
appevent.context_app_os = "Windows 8"
appevent.custom_properties = CustomData("Custom Data holder!")

#Can support multiple string data
appevent.custom_properties.string_data = CustomStringData("Custom String Data 1", "Custom String Data 2")
appevent.custom_properties.string_data.custom_data3 = "More Custom Data!"

#populate the user and session to the error event
appevent.event_user = "john@traker.io"
appevent.event_session = "6"

#send it to trakerr
client.send_event_async(appevent)

return 0
```

`level` is something python's handler uses internally to decide when it should capture a record of a stack trace. For more information on that take a look at Python's [logging](https://docs.python.org/2/library/logging.html#logging-levels) library. The default setting is that it will emit a record on a stacktrace or above.
## An in-depth look at TrakerrClient's properties
TrakerrClient's constructor initalizes the default values to all of TrakerrClient's properties.

```python
def __init__(self, api_key, context_app_version, context_env_name = platform.python_implementation(),
context_env_version = platform.python_version(), context_env_hostname = platform.node(),
context_appos = platform.system() + " " + platform.release(),
context_appos_version = platform.version(),
context_datacenter = None, context_datacenter_region = None, url_path = TrakerrUtils.SERVER_URL,):
def __init__(self, api_key, context_app_version = "1.0", context_deployment_stage = "development"):
```

Finally we have the `TrakerrClient` init above. All of the data in this constructor will be sent to the server as string data (other than the `url_path` which has the url for the rest page). Refer to the reference table below for details.
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.


Name | Type | Description | Notes
------------ | ------------- | ------------- | -------------
**api_key** | **str** | API key generated to identfy the application |
**context_app_version** | **str** | (optional) application version information | [optional if passed `None`]
**context_env_name** | **str** | (optional) one of 'development','staging','production' or a custom string | [optional if passed `None`] Default Value: "develoment"
**context_env_version** | **str** | (optional) version of environment | [optional if passed `None`] Default Value: Interpreter type(ie. cpython, ironpy) and python version (ie. 2.7.8)
**context_env_hostname** | **str** | (optional) hostname or ID of environment | [optional if passed `None`] Default value: Name of the node the program is currently run on.
**context_app_os** | **str** | (optional) OS the application is running on | [optional if passed `None`] Default value: OS name (ie. Windows, MacOS) + Release (ie. 7, 8, 10, X)
**context_app_os_version** | **str** | (optional) OS version the application is running on | [optional if passed `None`] Default value: OS provided version number
**context_data_center** | **str** | (optional) Data center the application is running on or connected to | [optional if passed `None`]
**context_data_center_region** | **str** | (optional) Data center region | [optional if passed `None`]
**context_app_browser** | **str** | (optional) browser name if running in a browser (eg. Chrome) | [optional] For web frameworks(To be exposed and implemented)
**context_app_browser_version** | **str** | (optional) browser version if running in a browser | [optional] For web frameworks (To be exposed and implemented)
**url_path** | **str** | message containing details of the event or error |
------------ | ------------- | ------------- | -------------
**apiKey** | **string** | API key generated for the application |
**contextAppVersion** | **string** | Application version information. | Default value: "1.0"
**contextDevelopmentStage** | **string** | One of development, staging, production; or a custom string. | Default Value: "develoment"
**contextEnvLanguage** | **string** | Constant string representing the language the application is in. | Default value: "python"
**contextEnvName** | **string** | Name of the interpreter the program is run on. | Default Value: `platform.python_implementation()`
**contextEnvVersion** | **string** | Version of python this program is running on. | Default Value: `platform.python_version()`
**contextEnvHostname** | **string** | Hostname or ID of environment. | Default value: `platform.node()`
**contextAppOS** | **string** | OS the application is running on. | Default value: `platform.system() + platform.release()`
**contextAppOSVersion** | **string** | OS Version the application is running on. | Default value: `platform.version()`
**contextAppOSBrowser** | **string** | An optional string browser name the application is running on. | Defaults to `None`
**contextAppOSBrowserVersion** | **string** | An optional string browser version the application is running on. | Defaults to `None`
**contextDataCenter** | **string** | Data center the application is running on or connected to. | Defaults to `None`
**contextDataCenterRegion** | **string** | Data center region. | Defaults to `None`


The server accepts the final two arguments before url_path, but they are currently in development on this api level, so if you are using django or another web framework; please use the REST API. They are not currently available in the `TrakerrClient` constructor.
Expand Down

0 comments on commit bae7dd9

Please sign in to comment.