github.com/v2fly/tools@v0.100.0/internal/event/event.go (about)

     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  	"github.com/v2fly/tools/internal/event/core"
    11  	"github.com/v2fly/tools/internal/event/keys"
    12  	"github.com/v2fly/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  }