config.go (10020B)
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 func (o stackTraceOption) applySpan(c SpanConfig) SpanConfig { 272 c.stackTrace = bool(o) 273 return c 274 } 275 func (o stackTraceOption) applySpanEnd(c SpanConfig) SpanConfig { return o.applySpan(c) } 276 277 // WithStackTrace sets the flag to capture the error with stack trace (e.g. true, false). 278 func WithStackTrace(b bool) SpanEndEventOption { 279 return stackTraceOption(b) 280 } 281 282 // WithLinks adds links to a Span. The links are added to the existing Span 283 // links, i.e. this does not overwrite. Links with invalid span context are ignored. 284 func WithLinks(links ...Link) SpanStartOption { 285 return spanOptionFunc(func(cfg SpanConfig) SpanConfig { 286 cfg.links = append(cfg.links, links...) 287 return cfg 288 }) 289 } 290 291 // WithNewRoot specifies that the Span should be treated as a root Span. Any 292 // existing parent span context will be ignored when defining the Span's trace 293 // identifiers. 294 func WithNewRoot() SpanStartOption { 295 return spanOptionFunc(func(cfg SpanConfig) SpanConfig { 296 cfg.newRoot = true 297 return cfg 298 }) 299 } 300 301 // WithSpanKind sets the SpanKind of a Span. 302 func WithSpanKind(kind SpanKind) SpanStartOption { 303 return spanOptionFunc(func(cfg SpanConfig) SpanConfig { 304 cfg.spanKind = kind 305 return cfg 306 }) 307 } 308 309 // WithInstrumentationVersion sets the instrumentation version. 310 func WithInstrumentationVersion(version string) TracerOption { 311 return tracerOptionFunc(func(cfg TracerConfig) TracerConfig { 312 cfg.instrumentationVersion = version 313 return cfg 314 }) 315 } 316 317 // WithInstrumentationAttributes sets the instrumentation attributes. 318 // 319 // The passed attributes will be de-duplicated. 320 func WithInstrumentationAttributes(attr ...attribute.KeyValue) TracerOption { 321 return tracerOptionFunc(func(config TracerConfig) TracerConfig { 322 config.attrs = attribute.NewSet(attr...) 323 return config 324 }) 325 } 326 327 // WithSchemaURL sets the schema URL for the Tracer. 328 func WithSchemaURL(schemaURL string) TracerOption { 329 return tracerOptionFunc(func(cfg TracerConfig) TracerConfig { 330 cfg.schemaURL = schemaURL 331 return cfg 332 }) 333 }