1// Copyright 2019 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5package event 6 7import ( 8 "context" 9 10 "golang.org/x/tools/internal/event/core" 11 "golang.org/x/tools/internal/event/keys" 12 "golang.org/x/tools/internal/event/label" 13) 14 15// Exporter is a function that handles events. 16// It may return a modified context and event. 17type Exporter func(context.Context, core.Event, label.Map) context.Context 18 19// SetExporter sets the global exporter function that handles all events. 20// The exporter is called synchronously from the event call site, so it should 21// return quickly so as not to hold up user code. 22func SetExporter(e Exporter) { 23 core.SetExporter(core.Exporter(e)) 24} 25 26// Log takes a message and a label list and combines them into a single event 27// before delivering them to the exporter. 28func Log(ctx context.Context, message string, labels ...label.Label) { 29 core.Export(ctx, core.MakeEvent([3]label.Label{ 30 keys.Msg.Of(message), 31 }, labels)) 32} 33 34// IsLog returns true if the event was built by the Log function. 35// It is intended to be used in exporters to identify the semantics of the 36// event when deciding what to do with it. 37func IsLog(ev core.Event) bool { 38 return ev.Label(0).Key() == keys.Msg 39} 40 41// Error takes a message and a label list and combines them into a single event 42// before delivering them to the exporter. It captures the error in the 43// delivered event. 44func Error(ctx context.Context, message string, err error, labels ...label.Label) { 45 core.Export(ctx, core.MakeEvent([3]label.Label{ 46 keys.Msg.Of(message), 47 keys.Err.Of(err), 48 }, labels)) 49} 50 51// IsError returns true if the event was built by the Error function. 52// It is intended to be used in exporters to identify the semantics of the 53// event when deciding what to do with it. 54func IsError(ev core.Event) bool { 55 return ev.Label(0).Key() == keys.Msg && 56 ev.Label(1).Key() == keys.Err 57} 58 59// Metric sends a label event to the exporter with the supplied labels. 60func Metric(ctx context.Context, labels ...label.Label) { 61 core.Export(ctx, core.MakeEvent([3]label.Label{ 62 keys.Metric.New(), 63 }, labels)) 64} 65 66// IsMetric returns true if the event was built by the Metric function. 67// It is intended to be used in exporters to identify the semantics of the 68// event when deciding what to do with it. 69func IsMetric(ev core.Event) bool { 70 return ev.Label(0).Key() == keys.Metric 71} 72 73// Label sends a label event to the exporter with the supplied labels. 74func Label(ctx context.Context, labels ...label.Label) context.Context { 75 return core.Export(ctx, core.MakeEvent([3]label.Label{ 76 keys.Label.New(), 77 }, labels)) 78} 79 80// IsLabel returns true if the event was built by the Label function. 81// It is intended to be used in exporters to identify the semantics of the 82// event when deciding what to do with it. 83func IsLabel(ev core.Event) bool { 84 return ev.Label(0).Key() == keys.Label 85} 86 87// Start sends a span start event with the supplied label list to the exporter. 88// It also returns a function that will end the span, which should normally be 89// deferred. 90func Start(ctx context.Context, name string, labels ...label.Label) (context.Context, func()) { 91 return core.ExportPair(ctx, 92 core.MakeEvent([3]label.Label{ 93 keys.Start.Of(name), 94 }, labels), 95 core.MakeEvent([3]label.Label{ 96 keys.End.New(), 97 }, nil)) 98} 99 100// IsStart returns true if the event was built by the Start function. 101// It is intended to be used in exporters to identify the semantics of the 102// event when deciding what to do with it. 103func IsStart(ev core.Event) bool { 104 return ev.Label(0).Key() == keys.Start 105} 106 107// IsEnd returns true if the event was built by the End function. 108// It is intended to be used in exporters to identify the semantics of the 109// event when deciding what to do with it. 110func IsEnd(ev core.Event) bool { 111 return ev.Label(0).Key() == keys.End 112} 113 114// Detach returns a context without an associated span. 115// This allows the creation of spans that are not children of the current span. 116func Detach(ctx context.Context) context.Context { 117 return core.Export(ctx, core.MakeEvent([3]label.Label{ 118 keys.Detach.New(), 119 }, nil)) 120} 121 122// IsDetach returns true if the event was built by the Detach function. 123// It is intended to be used in exporters to identify the semantics of the 124// event when deciding what to do with it. 125func IsDetach(ev core.Event) bool { 126 return ev.Label(0).Key() == keys.Detach 127} 128