Documentation ¶
Index ¶
- Variables
- func Abort(err error)
- func AbortIf(err error)
- func Capture(err error)
- func Debug(config Config) func()
- func F(format string, args ...interface{}) error
- func FilterSentryIntegrations(drop ...string) func(i []sentry.Integration) []sentry.Integration
- func Forward(name string, reader io.Reader)
- func GetSpan(ctx context.Context) trace.Span
- func Intercept() func()
- func IsSafe(err error) bool
- func NumberCleaner(segments []string) []string
- func Reporter(tags SM) func(error)
- func Resume(fn func(error))
- func RootHandler(cleaners ...func([]string) []string) func(http.Handler) http.Handler
- func Run(ctx context.Context, fn func(ctx *Context) error) (err error)
- func SF(format string, args ...interface{}) error
- func SW(err error) error
- func SetupReporting(transport sentry.Transport) func()
- func SetupTracing(syncer export.SpanSyncer) func()
- func Sink(name string) io.WriteCloser
- func SortNodes(nodes []*VNode)
- func StartSpan(ctx context.Context, name string) (context.Context, trace.Span)
- func Test(fn func(tester *Tester))
- func W(err error) error
- func WF(err error, format string, args ...interface{}) error
- func WalkTrace(node *VNode, fn func(node *VNode) bool) bool
- type BaseErr
- type BufferSink
- type Caller
- type Config
- type Context
- type Debugger
- type Err
- type M
- type SM
- type SafeErr
- type SentryTransport
- type Span
- type SpanSyncer
- type Tester
- type Trace
- func (t *Trace) Attach(event string, attributes M)
- func (t *Trace) End()
- func (t *Trace) Log(format string, args ...interface{})
- func (t *Trace) Pop()
- func (t *Trace) Push(name string)
- func (t *Trace) Record(err error)
- func (t *Trace) Rename(name string)
- func (t *Trace) Root() Span
- func (t *Trace) Tag(key string, value interface{})
- func (t *Trace) Tail() Span
- type VEvent
- type VException
- type VFrame
- type VNode
- type VReport
- type VSpan
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var SinkFactory = func(name string) io.WriteCloser { reader, writer := io.Pipe() go Forward(name, reader) return writer }
SinkFactory is the factory used by Sink() to create sinks.
var Stdout io.Writer = os.Stdout
Stdout is the original stdout.
Functions ¶
func AbortIf ¶ added in v0.1.1
func AbortIf(err error)
AbortIf will only abort with the supplied error if present.
func Capture ¶
func Capture(err error)
Capture will capture the error.
Example ¶
// install teardown := Debug(Config{ NoEventContext: true, NoEventLineNumbers: true, }) defer teardown() // capture error Capture(F("some error")) // flush time.Sleep(10 * time.Millisecond)
Output: ===== EVENT ===== Level: error Exceptions: - some error (*xo.Err) > ExampleCapture (github.com/256dpi/xo): github.com/256dpi/xo/examples_test.go > main (main): _testmain.go
func Debug ¶
func Debug(config Config) func()
Debug will install logging, reporting and tracing components for debugging purposes. The returned function may be called to teardown all installed components.
func F ¶
F will format an error. This function can be used instead of errors.New() and fmt.Errorf().
func FilterSentryIntegrations ¶
func FilterSentryIntegrations(drop ...string) func(i []sentry.Integration) []sentry.Integration
FilterSentryIntegrations will return a sentry integrations filter that will drop the named integrations.
func GetSpan ¶
GetSpan will return the first native span from the provided context. It will return nil if no span has been found.
func Intercept ¶
func Intercept() func()
Intercept will replace os.Stdout with a logging sink named "STDOUT". It will also redirect the output of the log package to a logging sink named "LOG". The returned function can be called to restore the original state.
func IsSafe ¶
IsSafe can be used to check if an error has been wrapped using SW. It will also detect further wrapped safe errors.
func NumberCleaner ¶
NumberCleaner will replace number URL segments with a "#".
func Resume ¶ added in v0.1.1
func Resume(fn func(error))
Resume will try to recover an earlier call to Abort or AbortIf and call fn if an error has been recovered. It will not recover direct calls to the built-in panic function.
Note: If the built-in panic function has been called with nil, a call to Resume will discard that panic and continue execution.
func RootHandler ¶
RootHandler is the middleware used to create the root trace span for incoming HTTP requests.
func Run ¶
Run will run the provided function and automatically handle tracking, error handling and panic recovering.
Example ¶
// get context ctx := context.Background() // divide positive res, err := Div(ctx, 10, 2) fmt.Printf("div: %d, %v\n", res, err) // divide negative res, err = Div(ctx, 10, -2) fmt.Printf("div: %d, %v\n", res, err) // divide zero res, err = Div(ctx, 10, 0) fmt.Printf("div: %d, %v\n", res, err)
Output: div: 5, <nil> div: 0, xo.Div: negative division div: 0, xo.Div: PANIC: runtime error: integer divide by zero
func SW ¶
SW wraps an error and marks it as safe. Wrapped errors are safe to be presented to the client if appropriate.
func SetupReporting ¶
func SetupReporting(transport sentry.Transport) func()
SetupReporting will setup error reporting using sentry. The returned function may be called to teardown the component.
func SetupTracing ¶
func SetupTracing(syncer export.SpanSyncer) func()
SetupTracing will setup tracing using the provided span syncer. The returned function may be called to teardown the component.
func Sink ¶
func Sink(name string) io.WriteCloser
Sink will return a new named logging sink.
Example ¶
// intercept reset := Intercept() defer reset() // builtin fmt fmt.Println("foo", "bar") fmt.Printf("%d %d\n", 7, 42) time.Sleep(10 * time.Millisecond) // builtin logger log.SetFlags(0) log.Println("foo", "bar") log.Printf("%d %d", 7, 42) time.Sleep(10 * time.Millisecond) // custom logger sink := Sink("FOO") logger := log.New(sink, "", 0) logger.Println("foo", "bar") logger.Printf("%d %d", 7, 42) time.Sleep(10 * time.Millisecond)
Output: ===== STDOUT ===== foo bar 7 42 ===== LOG ===== foo bar 7 42 ===== FOO ===== foo bar 7 42
func StartSpan ¶
StartSpan will start a native span using the configured tracer. It will continue any span found in the context or start a new one if absent.
func Test ¶
func Test(fn func(tester *Tester))
Test will temporarily intercept and collect logging, tracing and reporting data for testing purposes.
func W ¶
W will wrap an error. The error is not wrapped if the parent error already captured the caller.
Types ¶
type BaseErr ¶ added in v0.1.1
type BaseErr struct {
// contains filtered or unexported fields
}
BaseErr represents the base of an error chain. It cannot directly be used as an error value. Instead, the caller uses Wrap() to get a new wrapped error or Self() to get the identity error.
type BufferSink ¶
BufferSink wraps a bytes buffer.
func (*BufferSink) Close ¶
func (s *BufferSink) Close() error
Close implements the io.Closer interface.
type Caller ¶
Caller describes a caller.
func (Caller) Format ¶
Format will format the caller.
%s short name %q "short name" %v full name %+v stack trace
func (Caller) Includes ¶
Includes returns whether the receiver fully includes the provided caller. Ignore can be set to ignore n bottom frames. Two adjacent callers will have the same stack except for the last frame which represents the call site.
type Config ¶
type Config struct { // Whether to omit interception. // // Default: false. NoIntercept bool // The output for traces. // // Default: Sink("TRACE"). TraceOutput io.Writer // The trace resolution. // // Default: 1ns. TraceResolution time.Duration // The trace width. // // Default: 80. TraceWidth int // Whether to omit trace attributes. NoTraceAttributes bool // The output for events. // // Default: Sink("EVENT"). EventOutput io.Writer // Whether to omit event context data. NoEventContext bool // Whether to omit file paths from event stack traces. NoEventPaths bool // Whether to omit line numbers from event stack traces. NoEventLineNumbers bool }
Config is used to configure xo.
type Context ¶
Context is used by Run to track execution.
type Debugger ¶
type Debugger struct {
// contains filtered or unexported fields
}
Debugger is a virtual logging, tracing and reporting provider for debugging purposes.
func NewDebugger ¶
NewDebugger will create and return a new debugger.
func (*Debugger) SentryTransport ¶
func (d *Debugger) SentryTransport() sentry.Transport
SentryTransport will return a sentry transport that print received events.
func (*Debugger) SpanSyncer ¶
func (d *Debugger) SpanSyncer() trace.SpanSyncer
SpanSyncer will return a span syncer that prints received spans.
type Err ¶
Err is the error returned by F(), W() and WF().
func (*Err) Format ¶
Format will format the error.
%s message %q "message" %v caller: message %+v err message caller
func (*Err) StackTrace ¶
StackTrace will return the stack trace (for sentry compatibility).
type SentryTransport ¶
type SentryTransport func(*sentry.Event)
SentryTransport is a functional sentry transport.
func (SentryTransport) Configure ¶
func (t SentryTransport) Configure(sentry.ClientOptions)
Configure implements the sentry.Transport interface.
func (SentryTransport) Flush ¶
func (t SentryTransport) Flush(time.Duration) bool
Flush implements the sentry.Transport interface.
func (SentryTransport) SendEvent ¶
func (t SentryTransport) SendEvent(event *sentry.Event)
SendEvent implements the sentry.Transport interface.
type Span ¶
type Span struct {
// contains filtered or unexported fields
}
Span is the underlying span used for tracing.
func Track ¶
Track is used to mark and annotate a function call. It will automatically wrap the context with a child from the span history found in the provided context. If no span history was found it will start a new span.
If the function finds a trace in the context and its root span matches the span from the context it will create a child from the traces tail. If not it considers the span history to have diverged from the trace.
Example ¶
// install teardown := Debug(Config{ TraceResolution: 100 * time.Millisecond, NoTraceAttributes: true, }) defer teardown() // get context ctx := context.Background() // track ctx1, span1 := Track(ctx, "One") time.Sleep(100 * time.Millisecond) ctx2, span2 := Track(ctx1, "Two") span2.Log("hello world") time.Sleep(100 * time.Millisecond) _, span3 := Track(ctx2, "Three") span3.Tag("foo", "bar") time.Sleep(100 * time.Millisecond) span3.End() span2.End() ctx4, span4 := Track(ctx1, "Four") span4.Record(F("fatal")) time.Sleep(100 * time.Millisecond) _, span5 := Track(ctx4, "Five") span5.Tag("baz", 42) time.Sleep(100 * time.Millisecond) span5.End() span4.End() span1.End() // flush time.Sleep(10 * time.Millisecond)
Output: ===== TRACE ===== One ├──────────────────────────────────────────────────────────────────────────────┤ 500ms Two ├──────────────────────────────┤ 200ms :log • 100ms Three ├──────────────┤ 100ms Four ├──────────────────────────────┤ 200ms :error • 300ms Five ├──────────────┤ 100ms
type SpanSyncer ¶
SpanSyncer is a functional span exporter.
func (SpanSyncer) ExportSpan ¶
func (s SpanSyncer) ExportSpan(_ context.Context, span *trace.SpanData)
ExportSpan implements the trace.SpanSyncer interface.
type Tester ¶
type Tester struct { // Whether events should be cleaned. // // Default: true. CleanEvents bool // The collected spans. Spans []VSpan // The collected reports. Reports []VReport // The collected sinks. Sinks map[string]*BufferSink }
Tester is a virtual logging, tracing and reporting provider for testing purposes.
func (*Tester) ReducedReports ¶
ReducedReports will return a copy of the report list with reduced information. This representation can be used in tests for easy direct comparison.
func (*Tester) ReducedSpans ¶
ReducedSpans will return a copy of the span list with reduced information. This representation can be used in tests for easy direct comparison.
func (*Tester) SentryTransport ¶
func (t *Tester) SentryTransport() sentry.Transport
SentryTransport will return a sentry transport that collects events.
func (*Tester) SinkFactory ¶
func (t *Tester) SinkFactory() func(name string) io.WriteCloser
SinkFactory will return a sink factory that returns buffer sinks.
func (*Tester) SpanSyncer ¶
func (t *Tester) SpanSyncer() trace.SpanSyncer
SpanSyncer will return a span syncer that collects spans.
type Trace ¶
type Trace struct {
// contains filtered or unexported fields
}
Trace implements a span stack that can be used with fat contexts. Rather than branching of the context for every function call, a span is pushed onto the stack to track execution.
Code that uses Track will automatically discover the stack and branch of its tail if no previous branch has been detected. Other opentracing compatible code would not be able to find the stack and would use the root span instead. This can be prevented by ensuring a branch using the Branch function.
func CreateTrace ¶
CreateTrace returns a new trace that will use the span found in the provided context as its root or start a new one. The returned context is the provided context wrapped with the new span and trace.
func (*Trace) Pop ¶
func (t *Trace) Pop()
Pop ends and removes the last pushed span. This call is usually deferred right after a push.
type VException ¶
VException is a virtual report exception.
type VNode ¶
VNode is a virtual trace node.
func BuildTraces ¶
BuildTraces will assemble traces from a list of spans.
type VReport ¶
type VReport struct { ID string Level string Time time.Time Context M Tags SM Exceptions []VException }
VReport is a virtual report.
func ConvertReport ¶
func ConvertReport(event *sentry.Event) VReport
ConvertReport will convert a raw event to virtual report.