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