| 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 | |
| 5 | package event |
| 6 | |
| 7 | import ( |
| 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. |
| 17 | type 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. |
| 22 | func 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. |
| 28 | func 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. |
| 37 | func 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. |
| 44 | func 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. |
| 54 | func 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. |
| 60 | func 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. |
| 69 | func 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. |
| 74 | func 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. |
| 83 | func 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. |
| 90 | func 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. |
| 103 | func 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. |
| 110 | func 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. |
| 116 | func 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. |
| 125 | func IsDetach(ev core.Event) bool { |
| 126 | return ev.Label(0).Key() == keys.Detach |
| 127 | } |
| 128 |
Members