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