README
¶
THIS IS A WORK IN PROGRESS - API SURFACE MAY CHANGE
Exceptionless Go Client
This is a simple client wrapper to make working with Exceptionless in the Go environment easier. The client is not a complete wrapper around the Exceptionless API, so you are encouraged to review the full Swagger documentation here.
Getting Started
To install the client, run go get https://github.com/Exceptionless/Exceptionless.Go.
Import it into your project like this:
import (
"github.com/Exceptionless/Exceptionless.Go"
)
Once you've imported it in your project, you'll need to configure the client. The current configuration options are as follows:
- ApiKey - string - required
- ServerURL - string - optional
ApiKey is self-explanatory. Get your key at https://exceptionless.com.
If you are self-hosting Exceptionless, provide the server URL for your self-hosted installation for the ServerURL property.
Configuring Client
To set up your client, in the main.go file of your project, import Exceptionless as described above.
There are two main ways to configure the Exceptionless client. You can set properties in the configuration struct one-by-one like this:
exceptionless.ExceptionlessClient.ApiKey = "YOUR API KEY"
Or you can build up your own copy of the configuration struct and pass in your config settings all at once like this:
config := exceptionless.Exceptionless{
ApiKey: "YOUR API KEY",
ServerURL: "OPTIONAL SELF HOSTED URL",
}
exceptionless.Configure(config)
This will save your client information in-memory and will make it available throughout your app through a globally exposed variable called ExceptionlessClient. You can access that variable like this: exceptionless.ExceptionlessClient.
Sending Events
This client has two convenience functions: SubmitError and SubmitLog. These functions take minimal arguments and are far less flexible than building events yourself, but they are the easiest to use. We'll cover them first and then we will talk about how to build a custom event.
SubmitError
The SubmitError function does exactly what it says. It will build a simple error event and submit it to Exceptionless. SubmitError takes a Go error type and returns a string value response. An example of how to call this function is in the main_test.go file as well as below:
func MyGoFunction() {
e := errors.New(fmt.Sprintf("This is an error"))
resp := exceptionless.SubmitError(e)
fmt.Println(resp)
}
SubmitLog
This function is a simple wrapper that allows you to submit log events with specified log levels. This function takes a message string and a level string. There is an example of this in main_test.go or below:
func MyGoFunction() {
message := "Info log!"
level := "info"
resp := exceptionless.SubmitLog(message, level)
fmt.Println(resp)
}
Building Custom Events
This Go client allows you to build fully customized events. There are a number of helper functions to build these events. We'll walk through them all here.
The first thing you will always need to do when building a custom event is get the base event that you will tack on additional info to. To do this, you would simple call the following function:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
The GetBaseEvent function requires three parameters: eventType (string), message (string), and date (date).
AddSource
This function will add a source location for the event. Think of this as an area of your application where the event happened. Here's an example of how to make use of this function:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddSource(event, "line 66 main.go")
AddSource takes in your exist event as well as a string variable for the source of the event.
AddTags
This function will add a string array of tags to your event. These tags can be used for filtering within the Exceptionless app. Here is an example:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddTags(event, []string{"one", "two", "three"})
As you can see, the AddTags function takes the existing event and a string array as arguments.
AddGeo
This function will add the geographical location of your user with a latitude and logitude. Here is an example:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddGeo(event, "44.14561, -172.32262")
The AddGeo function takes in your existing event and a string value with comma delimited lat and long values as arguments.
AddValue
This function will add an arbitrary integer value to your events. It can represent anything you'd like. Here's an example:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddValue(event, 21)
As you can see, the AddValue function takes in your existing event and an integer value as arguments.
AddReferenceID
This function will add a UUID reference that you can use later to identify specific events. This identifier must be unique across your events.
Note: When using the SubmitEvent and SubmitLog helpers, a referenceID will automatically be generated and applied to your events.
Here is an example of how to use this function:
var event Event
referenceID := uuid.Must(uuid.NewV4())
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddReferenceID(event, referenceID)
As you can see, the addReferenceId function takes in your existing event and a referenceID (in the form of the UUID type) as arguments.
AddCount
This function adds a count integer to help you easily count just about anything you want. The count will be added to your event. Here is an example of how to use this function:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddCount(event, 99)
As you can see, the AddCount function takes in your existing event and an integer as arguments.
AddLogLevel
This function is designed for log type events. It will add a log level to your event. This is useful for filtering. Here is an example of how to use this function:
var event Event
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("log", "test log", date)
event = exceptionless.AddLogLevel(event, "info")
As you can see, the AddLogLevel function takes in your existing event and a string value representing the log level as arguments.
AddData
Exceptionless can take any dictionary mapping of values that you want to provide. This helper function will apply your custom mapping for you. Here is an example of how to use this function:
var event Event
event = exceptionless.GetBaseEvent("log", "test log", date)
data := map[string]interface{}{}
data["custom_key"] = "custom string value"
exceptionless.AddData(event, data)
The data property takes a string map of arbitrary values. That said, there are some well-known keys that Exceptionless will treat as first-class citizens. Read more about those here.
SubmitEvent
This is the function you call when your event has been built and is ready to be submitted to Exceptionless. Here is an example of how to use it:
json, err := json.Marshal(event)
if err != nil {
fmt.Println(err)
}
resp := exceptionless.SubmitEvent(string(json))
Full Example
Here is a more complete example of building and submitting a custom event:
var event Event
referenceID := uuid.Must(uuid.NewV4())
date := time.Now().Format(time.RFC3339)
event = exceptionless.GetBaseEvent("error", "testing", date)
event = exceptionless.AddSource(event, "line 206 app.js")
event = exceptionless.AddTags(event, []string{"one", "two", "three"})
event = exceptionless.AddGeo(event, "44.14561, -172.32262")
event = exceptionless.AddValue(event, 21)
event = exceptionless.AddReferenceID(event, referenceID)
event = exceptionless.AddCount(event, 99)
data := map[string]interface{}{}
data["custom_key"] = "custom string value"
event = exceptionless.AddData(event, data)
json, err := json.Marshal(event)
if err != nil {
fmt.Println(err)
}
resp := exceptionless.SubmitEvent(string(json))
if resp == "" {
fmt.Println("Test failed")
}
Data Model
A full example of possibile options in an an Exceptionless event is below. Keep in mind that Exceptionless is a flexible API and within the data object, you can pass in just about any key/value pairs you want. The below model is just a reference:
{
"type": "error",
"source": "Website",
"reference_id": "123",
"message": "some event message",
"geo": "latitude}, longitude",
"date":"2030-01-01T12:00:00.0000000-05:00",
"data": {
"@ref": {
"id": "parent event reference id",
"name": "parent event reference name"
},
"@user": {
"identity": "email or something",
"name": "John Doe",
"data": "Anything we want"
},
"@user_description": {
"email_address": "email",
"description": "super cool user",
"data": "Anything we want"
},
"@stack": {
"signature_data": {
"ManualStackingKey": "manual key we set"
},
"title": "stack title"
},
},
"value": "some number",
"tags": ["string", "string", "string"]
}
Documentation
¶
Index ¶
- Variables
- func Get(endpoint string, authorization string) map[string]interface{}
- func GetBaseURL() string
- func GetConfig() map[string]interface{}
- func Post(endpoint string, postBody string, authorization string) string
- func SubmitError(err error) string
- func SubmitEvent(eventBody string) string
- func SubmitLog(message string, level string) string
- type Event
- func AddCount(event Event, count uint) Event
- func AddData(event Event, data map[string]interface{}) Event
- func AddGeo(event Event, geo string) Event
- func AddLogLevel(event Event, level string) Event
- func AddReferenceID(event Event, referenceID uuid.UUID) Event
- func AddSource(event Event, source string) Event
- func AddTags(event Event, tags []string) Event
- func AddValue(event Event, value uint) Event
- func GetBaseEvent(eventType string, message string, date string) Event
- type Exceptionless
Constants ¶
This section is empty.
Variables ¶
var ExceptionlessClient = Exceptionless{}
ExceptionlessClient returns the configured client
Functions ¶
func GetBaseURL ¶
func GetBaseURL() string
func GetConfig ¶
func GetConfig() map[string]interface{}
GetConfig returns the project configuration
func SubmitError ¶
SubmitError is a convenience wrapper to quickly build and submit an error
func SubmitEvent ¶
Types ¶
type Event ¶
type Event struct {
EventType string `json:"type"`
Source string `json:"source,omitempty"`
Date string `json:"date,omitempty"`
Tags []string `json:"tags,omitempty"`
Message string `json:"message,omitempty"`
Geo string `json:"geo,omitempty"`
Value uint `json:"value,omitempty"`
Data map[string]interface{} `json:"data,omitempty"`
ReferenceID uuid.UUID `json:"reference_id,omitempty"`
Count uint `json:"count,omitempty"`
}
Event is the main model for events
func AddLogLevel ¶
func AddReferenceID ¶
AddReferenceID adds an indentifier to later refer to this event
type Exceptionless ¶
type Exceptionless struct {
ApiKey string
ServerURL string
UpdateSettingsWhenIdleInterval int32
IncludePrivateInformation bool
}
Exceptionless type defines the client configuration structure
func Configure ¶
func Configure(config Exceptionless) Exceptionless
Configure is the function that creates an Exceptionless ExceptionlessClient
Source Files