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
- func (s Span) Attach(event string, attributes M)
- func (s Span) Context() context.Context
- func (s Span) End()
- func (s Span) Log(format string, args ...interface{})
- func (s Span) Native() trace.Span
- func (s Span) Record(err error)
- func (s Span) Rename(name string)
- func (s Span) Tag(key string, value interface{})
- type SpanSyncer
- type Tester
- type Tracer
- func (t *Tracer) Attach(event string, attributes M)
- func (t *Tracer) End()
- func (t *Tracer) Log(format string, args ...interface{})
- func (t *Tracer) Pop()
- func (t *Tracer) Push(name string)
- func (t *Tracer) Record(err error)
- func (t *Tracer) Rename(name string)
- func (t *Tracer) Root() Span
- func (t *Tracer) SmartPush()
- func (t *Tracer) Tag(key string, value interface{})
- func (t *Tracer) 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 found in 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 tracing, 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 revert the previously configured client.
func SetupTracing ¶
func SetupTracing(syncer export.SpanSyncer) func()
SetupTracing will setup tracing using the provided span syncer. The returned function may be called to revert the previously configured provider.
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 globally configured tracer. It will continue any span found in the provided context or start a new span with the specified name 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 NewSpan ¶ added in v0.2.0
NewSpan will create and return a new span from the provided context and native span. The context should already carry the native span.
func SmartTrace ¶ added in v0.2.0
SmartTrace calls Trace with the callers short name.
func Trace ¶
Trace is used to trace a function call. It will start a new span based on the history in the provided context. It will return a new span and context that contains the created spans native span.
Example ¶
// install teardown := Debug(Config{ TraceResolution: 100 * time.Millisecond, NoTraceAttributes: true, }) defer teardown() // get context ctx := context.Background() // trace ctx1, span1 := Trace(ctx, "One") time.Sleep(100 * time.Millisecond) ctx2, span2 := Trace(ctx1, "Two") span2.Log("hello world") time.Sleep(100 * time.Millisecond) _, span3 := Trace(ctx2, "Three") span3.Tag("foo", "bar") time.Sleep(100 * time.Millisecond) span3.End() span2.End() ctx4, span4 := Trace(ctx1, "Four") span4.Record(F("fatal")) time.Sleep(100 * time.Millisecond) _, span5 := Trace(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 Tracer ¶ added in v0.2.0
type Tracer struct {
// contains filtered or unexported fields
}
Tracer manages 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 tracers stack to trace execution.
Code that uses Trace or native opentelemetry APIs will automatically discover the stack and branch of its tail if no previous branch has been detected.
func CreateTracer ¶ added in v0.2.0
CreateTracer returns a new tracer that will use the span found in the provided context to start a new one with the provided name. The returned context is the provided context wrapped with the new native span and tracer.
func GetTracer ¶ added in v0.2.0
GetTracer will return the tracer from the context or nil if absent.
func NewTracer ¶ added in v0.2.0
NewTracer returns a new tracer that will use the native span found in the context as its root. The returned context is the provided context wrapped with the tracer.
func (*Tracer) End ¶ added in v0.2.0
func (t *Tracer) End()
End will end all stacked spans and the root span.
func (*Tracer) Pop ¶ added in v0.2.0
func (t *Tracer) Pop()
Pop ends and removes the last pushed span. This call is usually deferred right after a push.
func (*Tracer) SmartPush ¶ added in v0.2.0
func (t *Tracer) SmartPush()
SmartPush will call Push() with callers short name.
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.