config.go

Documentation: go.opentelemetry.io/otel/trace

     1  // Copyright The OpenTelemetry Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package trace // import "go.opentelemetry.io/otel/trace"
    16  
    17  import (
    18  	"time"
    19  
    20  	"go.opentelemetry.io/otel/attribute"
    21  )
    22  
    23  // TracerConfig is a group of options for a Tracer.
    24  type TracerConfig struct {
    25  	instrumentationVersion string
    26  	// Schema URL of the telemetry emitted by the Tracer.
    27  	schemaURL string
    28  	attrs     attribute.Set
    29  }
    30  
    31  // InstrumentationVersion returns the version of the library providing instrumentation.
    32  func (t *TracerConfig) InstrumentationVersion() string {
    33  	return t.instrumentationVersion
    34  }
    35  
    36  // InstrumentationAttributes returns the attributes associated with the library
    37  // providing instrumentation.
    38  func (t *TracerConfig) InstrumentationAttributes() attribute.Set {
    39  	return t.attrs
    40  }
    41  
    42  // SchemaURL returns the Schema URL of the telemetry emitted by the Tracer.
    43  func (t *TracerConfig) SchemaURL() string {
    44  	return t.schemaURL
    45  }
    46  
    47  // NewTracerConfig applies all the options to a returned TracerConfig.
    48  func NewTracerConfig(options ...TracerOption) TracerConfig {
    49  	var config TracerConfig
    50  	for _, option := range options {
    51  		config = option.apply(config)
    52  	}
    53  	return config
    54  }
    55  
    56  // TracerOption applies an option to a TracerConfig.
    57  type TracerOption interface {
    58  	apply(TracerConfig) TracerConfig
    59  }
    60  
    61  type tracerOptionFunc func(TracerConfig) TracerConfig
    62  
    63  func (fn tracerOptionFunc) apply(cfg TracerConfig) TracerConfig {
    64  	return fn(cfg)
    65  }
    66  
    67  // SpanConfig is a group of options for a Span.
    68  type SpanConfig struct {
    69  	attributes []attribute.KeyValue
    70  	timestamp  time.Time
    71  	links      []Link
    72  	newRoot    bool
    73  	spanKind   SpanKind
    74  	stackTrace bool
    75  }
    76  
    77  // Attributes describe the associated qualities of a Span.
    78  func (cfg *SpanConfig) Attributes() []attribute.KeyValue {
    79  	return cfg.attributes
    80  }
    81  
    82  // Timestamp is a time in a Span life-cycle.
    83  func (cfg *SpanConfig) Timestamp() time.Time {
    84  	return cfg.timestamp
    85  }
    86  
    87  // StackTrace checks whether stack trace capturing is enabled.
    88  func (cfg *SpanConfig) StackTrace() bool {
    89  	return cfg.stackTrace
    90  }
    91  
    92  // Links are the associations a Span has with other Spans.
    93  func (cfg *SpanConfig) Links() []Link {
    94  	return cfg.links
    95  }
    96  
    97  // NewRoot identifies a Span as the root Span for a new trace. This is
    98  // commonly used when an existing trace crosses trust boundaries and the
    99  // remote parent span context should be ignored for security.
   100  func (cfg *SpanConfig) NewRoot() bool {
   101  	return cfg.newRoot
   102  }
   103  
   104  // SpanKind is the role a Span has in a trace.
   105  func (cfg *SpanConfig) SpanKind() SpanKind {
   106  	return cfg.spanKind
   107  }
   108  
   109  // NewSpanStartConfig applies all the options to a returned SpanConfig.
   110  // No validation is performed on the returned SpanConfig (e.g. no uniqueness
   111  // checking or bounding of data), it is left to the SDK to perform this
   112  // action.
   113  func NewSpanStartConfig(options ...SpanStartOption) SpanConfig {
   114  	var c SpanConfig
   115  	for _, option := range options {
   116  		c = option.applySpanStart(c)
   117  	}
   118  	return c
   119  }
   120  
   121  // NewSpanEndConfig applies all the options to a returned SpanConfig.
   122  // No validation is performed on the returned SpanConfig (e.g. no uniqueness
   123  // checking or bounding of data), it is left to the SDK to perform this
   124  // action.
   125  func NewSpanEndConfig(options ...SpanEndOption) SpanConfig {
   126  	var c SpanConfig
   127  	for _, option := range options {
   128  		c = option.applySpanEnd(c)
   129  	}
   130  	return c
   131  }
   132  
   133  // SpanStartOption applies an option to a SpanConfig. These options are applicable
   134  // only when the span is created.
   135  type SpanStartOption interface {
   136  	applySpanStart(SpanConfig) SpanConfig
   137  }
   138  
   139  type spanOptionFunc func(SpanConfig) SpanConfig
   140  
   141  func (fn spanOptionFunc) applySpanStart(cfg SpanConfig) SpanConfig {
   142  	return fn(cfg)
   143  }
   144  
   145  // SpanEndOption applies an option to a SpanConfig. These options are
   146  // applicable only when the span is ended.
   147  type SpanEndOption interface {
   148  	applySpanEnd(SpanConfig) SpanConfig
   149  }
   150  
   151  // EventConfig is a group of options for an Event.
   152  type EventConfig struct {
   153  	attributes []attribute.KeyValue
   154  	timestamp  time.Time
   155  	stackTrace bool
   156  }
   157  
   158  // Attributes describe the associated qualities of an Event.
   159  func (cfg *EventConfig) Attributes() []attribute.KeyValue {
   160  	return cfg.attributes
   161  }
   162  
   163  // Timestamp is a time in an Event life-cycle.
   164  func (cfg *EventConfig) Timestamp() time.Time {
   165  	return cfg.timestamp
   166  }
   167  
   168  // StackTrace checks whether stack trace capturing is enabled.
   169  func (cfg *EventConfig) StackTrace() bool {
   170  	return cfg.stackTrace
   171  }
   172  
   173  // NewEventConfig applies all the EventOptions to a returned EventConfig. If no
   174  // timestamp option is passed, the returned EventConfig will have a Timestamp
   175  // set to the call time, otherwise no validation is performed on the returned
   176  // EventConfig.
   177  func NewEventConfig(options ...EventOption) EventConfig {
   178  	var c EventConfig
   179  	for _, option := range options {
   180  		c = option.applyEvent(c)
   181  	}
   182  	if c.timestamp.IsZero() {
   183  		c.timestamp = time.Now()
   184  	}
   185  	return c
   186  }
   187  
   188  // EventOption applies span event options to an EventConfig.
   189  type EventOption interface {
   190  	applyEvent(EventConfig) EventConfig
   191  }
   192  
   193  // SpanOption are options that can be used at both the beginning and end of a span.
   194  type SpanOption interface {
   195  	SpanStartOption
   196  	SpanEndOption
   197  }
   198  
   199  // SpanStartEventOption are options that can be used at the start of a span, or with an event.
   200  type SpanStartEventOption interface {
   201  	SpanStartOption
   202  	EventOption
   203  }
   204  
   205  // SpanEndEventOption are options that can be used at the end of a span, or with an event.
   206  type SpanEndEventOption interface {
   207  	SpanEndOption
   208  	EventOption
   209  }
   210  
   211  type attributeOption []attribute.KeyValue
   212  
   213  func (o attributeOption) applySpan(c SpanConfig) SpanConfig {
   214  	c.attributes = append(c.attributes, []attribute.KeyValue(o)...)
   215  	return c
   216  }
   217  func (o attributeOption) applySpanStart(c SpanConfig) SpanConfig { return o.applySpan(c) }
   218  func (o attributeOption) applyEvent(c EventConfig) EventConfig {
   219  	c.attributes = append(c.attributes, []attribute.KeyValue(o)...)
   220  	return c
   221  }
   222  
   223  var _ SpanStartEventOption = attributeOption{}
   224  
   225  // WithAttributes adds the attributes related to a span life-cycle event.
   226  // These attributes are used to describe the work a Span represents when this
   227  // option is provided to a Span's start or end events. Otherwise, these
   228  // attributes provide additional information about the event being recorded
   229  // (e.g. error, state change, processing progress, system event).
   230  //
   231  // If multiple of these options are passed the attributes of each successive
   232  // option will extend the attributes instead of overwriting. There is no
   233  // guarantee of uniqueness in the resulting attributes.
   234  func WithAttributes(attributes ...attribute.KeyValue) SpanStartEventOption {
   235  	return attributeOption(attributes)
   236  }
   237  
   238  // SpanEventOption are options that can be used with an event or a span.
   239  type SpanEventOption interface {
   240  	SpanOption
   241  	EventOption
   242  }
   243  
   244  type timestampOption time.Time
   245  
   246  func (o timestampOption) applySpan(c SpanConfig) SpanConfig {
   247  	c.timestamp = time.Time(o)
   248  	return c
   249  }
   250  func (o timestampOption) applySpanStart(c SpanConfig) SpanConfig { return o.applySpan(c) }
   251  func (o timestampOption) applySpanEnd(c SpanConfig) SpanConfig   { return o.applySpan(c) }
   252  func (o timestampOption) applyEvent(c EventConfig) EventConfig {
   253  	c.timestamp = time.Time(o)
   254  	return c
   255  }
   256  
   257  var _ SpanEventOption = timestampOption{}
   258  
   259  // WithTimestamp sets the time of a Span or Event life-cycle moment (e.g.
   260  // started, stopped, errored).
   261  func WithTimestamp(t time.Time) SpanEventOption {
   262  	return timestampOption(t)
   263  }
   264  
   265  type stackTraceOption bool
   266  
   267  func (o stackTraceOption) applyEvent(c EventConfig) EventConfig {
   268  	c.stackTrace = bool(o)
   269  	return c
   270  }
   271  
   272  func (o stackTraceOption) applySpan(c SpanConfig) SpanConfig {
   273  	c.stackTrace = bool(o)
   274  	return c
   275  }
   276  func (o stackTraceOption) applySpanEnd(c SpanConfig) SpanConfig { return o.applySpan(c) }
   277  
   278  // WithStackTrace sets the flag to capture the error with stack trace (e.g. true, false).
   279  func WithStackTrace(b bool) SpanEndEventOption {
   280  	return stackTraceOption(b)
   281  }
   282  
   283  // WithLinks adds links to a Span. The links are added to the existing Span
   284  // links, i.e. this does not overwrite. Links with invalid span context are ignored.
   285  func WithLinks(links ...Link) SpanStartOption {
   286  	return spanOptionFunc(func(cfg SpanConfig) SpanConfig {
   287  		cfg.links = append(cfg.links, links...)
   288  		return cfg
   289  	})
   290  }
   291  
   292  // WithNewRoot specifies that the Span should be treated as a root Span. Any
   293  // existing parent span context will be ignored when defining the Span's trace
   294  // identifiers.
   295  func WithNewRoot() SpanStartOption {
   296  	return spanOptionFunc(func(cfg SpanConfig) SpanConfig {
   297  		cfg.newRoot = true
   298  		return cfg
   299  	})
   300  }
   301  
   302  // WithSpanKind sets the SpanKind of a Span.
   303  func WithSpanKind(kind SpanKind) SpanStartOption {
   304  	return spanOptionFunc(func(cfg SpanConfig) SpanConfig {
   305  		cfg.spanKind = kind
   306  		return cfg
   307  	})
   308  }
   309  
   310  // WithInstrumentationVersion sets the instrumentation version.
   311  func WithInstrumentationVersion(version string) TracerOption {
   312  	return tracerOptionFunc(func(cfg TracerConfig) TracerConfig {
   313  		cfg.instrumentationVersion = version
   314  		return cfg
   315  	})
   316  }
   317  
   318  // WithInstrumentationAttributes sets the instrumentation attributes.
   319  //
   320  // The passed attributes will be de-duplicated.
   321  func WithInstrumentationAttributes(attr ...attribute.KeyValue) TracerOption {
   322  	return tracerOptionFunc(func(config TracerConfig) TracerConfig {
   323  		config.attrs = attribute.NewSet(attr...)
   324  		return config
   325  	})
   326  }
   327  
   328  // WithSchemaURL sets the schema URL for the Tracer.
   329  func WithSchemaURL(schemaURL string) TracerOption {
   330  	return tracerOptionFunc(func(cfg TracerConfig) TracerConfig {
   331  		cfg.schemaURL = schemaURL
   332  		return cfg
   333  	})
   334  }
   335
View as plain text