# README
periskop-go
Periskop requires collecting and aggregating exceptions on the client side, as well as exposing them via an HTTP endpoint using a well defined format.
This library provides low level collection and rendering capabilities
Usage
go get github.com/periskop-dev/periskop-go
Example
package main
import (
"encoding/json"
"net/http"
"github.com/periskop-dev/periskop-go"
)
func faultyJSONParser() error {
var dat map[string]interface{}
// will return "unexpected end of JSON input"
return json.Unmarshal([]byte(`{"id":`), &dat)
}
func main() {
c := periskop.NewErrorCollector()
// Without context
c.ReportError(faultyJSONParser())
// Optionally pass Severity of an error (supported by all report methods)
c.ReportWithSeverity(faultyJSONParser(), periskop.SeverityInfo)
// With HTTP context
body := "some body"
c.ReportWithHTTPContext(faultyJSONParser(), &periskop.HTTPContext{
RequestMethod: "GET",
RequestURL: "http://example.com",
RequestHeaders: map[string]string{"Cache-Control": "no-cache"},
RequestBody: &body, // optional request body, nil if not present
})
// With http.Request
req, err := http.NewRequest("GET", "http://example.com", nil)
c.ReportWithHTTPRequest(err, req)
// With a full error report
c.Report(periskop.ErrorReport{
Err: err,
Severity: SeverityWarning,
HTTPCtx: &periskop.HTTPContext{
RequestMethod: "GET",
RequestURL: "http://example.com",
RequestHeaders: map[string]string{"Cache-Control": "no-cache"},
RequestBody: &body,
},
ErrKey: "json-parsing", // Overrides the errors aggregation key (see more info below)
})
// With a full error report, but with http.Request instead of HTTP context
c.Report(periskop.ErrorReport{
Err: err,
Severity: SeverityWarning,
HTTPRequest: req,
ErrKey: "json-parsing",
})
// Call the exporter and HTTP handler to expose the
// errors in /-/exceptions endpoints
e := periskop.NewErrorExporter(&c)
h := periskop.NewHandler(e)
http.Handle("/-/exceptions", h)
http.ListenAndServe(":8080", nil)
}
Custom aggregation for reported errors
By default errors are aggregated by their stack trace and error message. This might cause that errors that are the same (but with different message) are treated as different in Periskop:
*url.Error@efdca928 -> Get "http://example": dial tcp 10.10.10.1:10100: i/o timeout
*url.Error@824c748e -> Get "http://example": dial tcp 10.10.10.2:10100: i/o timeout
To avoid that, you can manually group errors specifying the error key that you want to use:
func main() {
c := periskop.NewErrorCollector()
req, err := http.NewRequest("GET", "http://example.com", nil)
c.Report(periskop.ErrorReport{
Err: err,
HTTPRequest: req,
ErrKey: "example-request-error",
})
}
Using push gateway
You can also use pushgateway in case you want to push your metrics instead of using pull method. Use only in case you really need it (e.g a batch job) as it would degrade the performance of your application. In the following example, we assume that we deployed an instance of periskop-pushgateway on http://localhost:6767
:
package main
import (
"encoding/json"
"github.com/periskop-dev/periskop-go"
)
func faultyJSONParser() error {
var dat map[string]interface{}
// will return "unexpected end of JSON input"
return json.Unmarshal([]byte(`{"id":`), &dat)
}
func reportAndPush(c *periskop.ErrorCollector, e *periskop.ErrorExporter, err error) error {
c.ReportError(err)
return e.PushToGateway("http://localhost:6767")
}
func main() {
c := periskop.NewErrorCollector()
e := periskop.NewErrorExporter(&c)
reportAndPush(&c, &e, faultyJSONParser())
}
Contributing
Please see CONTRIBUTING.md