Categorygithub.com/periskop-dev/periskop-go
modulepackage
0.0.0-20220512172842-c5603b259677
Repository: https://github.com/periskop-dev/periskop-go.git
Documentation: pkg.go.dev

# README

periskop-go

Build Status

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

# Packages

Package errors provides errors that have stack-traces.

# Functions

NewCustomErrorInstance allows to create a custom error instance without specifying a Go error.
NewErrorCollector creates a new ErrorCollector.
NewErrorExporter creates a new ErrorExporter.
No description provided by the author
NewHandler receives a Periskop Error Exporter and returns a handler with the exported errors in json format.

# Constants

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Structs

ErrorCollector collects all the aggregated errors.
ErrorExporter exposes collected errors.
No description provided by the author
ErrorReport represents a report of a single error.
No description provided by the author
HTTPContext holds info of the HTTP context when an error is produced.

# Type aliases

Severity is the definition of different severities.