blob: c2222f153a39119f8c712677a747d25172db179b [file] [log] [blame]
Girish Gowdra631ef3d2020-06-15 10:45:52 -07001// Copyright (c) 2017-2018 Uber Technologies, Inc.
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
15package config
16
17import (
18 "errors"
19 "fmt"
20 "io"
21 "strings"
22 "time"
23
24 "github.com/opentracing/opentracing-go"
khenaidoo106c61a2021-08-11 18:05:46 -040025 "github.com/uber/jaeger-client-go/utils"
Girish Gowdra631ef3d2020-06-15 10:45:52 -070026
27 "github.com/uber/jaeger-client-go"
28 "github.com/uber/jaeger-client-go/internal/baggage/remote"
29 throttler "github.com/uber/jaeger-client-go/internal/throttler/remote"
30 "github.com/uber/jaeger-client-go/rpcmetrics"
31 "github.com/uber/jaeger-client-go/transport"
32 "github.com/uber/jaeger-lib/metrics"
33)
34
35const defaultSamplingProbability = 0.001
36
37// Configuration configures and creates Jaeger Tracer
38type Configuration struct {
39 // ServiceName specifies the service name to use on the tracer.
khenaidoo106c61a2021-08-11 18:05:46 -040040 // Can be provided by FromEnv() via the environment variable named JAEGER_SERVICE_NAME
Girish Gowdra631ef3d2020-06-15 10:45:52 -070041 ServiceName string `yaml:"serviceName"`
42
khenaidoo106c61a2021-08-11 18:05:46 -040043 // Disabled makes the config return opentracing.NoopTracer.
44 // Value can be provided by FromEnv() via the environment variable named JAEGER_DISABLED.
Girish Gowdra631ef3d2020-06-15 10:45:52 -070045 Disabled bool `yaml:"disabled"`
46
khenaidoo106c61a2021-08-11 18:05:46 -040047 // RPCMetrics enables generations of RPC metrics (requires metrics factory to be provided).
48 // Value can be provided by FromEnv() via the environment variable named JAEGER_RPC_METRICS
Girish Gowdra631ef3d2020-06-15 10:45:52 -070049 RPCMetrics bool `yaml:"rpc_metrics"`
50
khenaidoo106c61a2021-08-11 18:05:46 -040051 // Gen128Bit instructs the tracer to generate 128-bit wide trace IDs, compatible with W3C Trace Context.
52 // Value can be provided by FromEnv() via the environment variable named JAEGER_TRACEID_128BIT.
53 Gen128Bit bool `yaml:"traceid_128bit"`
54
55 // Tags can be provided by FromEnv() via the environment variable named JAEGER_TAGS
Girish Gowdra631ef3d2020-06-15 10:45:52 -070056 Tags []opentracing.Tag `yaml:"tags"`
57
58 Sampler *SamplerConfig `yaml:"sampler"`
59 Reporter *ReporterConfig `yaml:"reporter"`
60 Headers *jaeger.HeadersConfig `yaml:"headers"`
61 BaggageRestrictions *BaggageRestrictionsConfig `yaml:"baggage_restrictions"`
62 Throttler *ThrottlerConfig `yaml:"throttler"`
63}
64
65// SamplerConfig allows initializing a non-default sampler. All fields are optional.
66type SamplerConfig struct {
khenaidoo106c61a2021-08-11 18:05:46 -040067 // Type specifies the type of the sampler: const, probabilistic, rateLimiting, or remote.
68 // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_TYPE
Girish Gowdra631ef3d2020-06-15 10:45:52 -070069 Type string `yaml:"type"`
70
71 // Param is a value passed to the sampler.
72 // Valid values for Param field are:
73 // - for "const" sampler, 0 or 1 for always false/true respectively
74 // - for "probabilistic" sampler, a probability between 0 and 1
75 // - for "rateLimiting" sampler, the number of spans per second
76 // - for "remote" sampler, param is the same as for "probabilistic"
77 // and indicates the initial sampling rate before the actual one
78 // is received from the mothership.
khenaidoo106c61a2021-08-11 18:05:46 -040079 // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_PARAM
Girish Gowdra631ef3d2020-06-15 10:45:52 -070080 Param float64 `yaml:"param"`
81
khenaidoo106c61a2021-08-11 18:05:46 -040082 // SamplingServerURL is the URL of sampling manager that can provide
83 // sampling strategy to this service.
84 // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLING_ENDPOINT
Girish Gowdra631ef3d2020-06-15 10:45:52 -070085 SamplingServerURL string `yaml:"samplingServerURL"`
86
87 // SamplingRefreshInterval controls how often the remotely controlled sampler will poll
khenaidoo106c61a2021-08-11 18:05:46 -040088 // sampling manager for the appropriate sampling strategy.
89 // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_REFRESH_INTERVAL
Girish Gowdra631ef3d2020-06-15 10:45:52 -070090 SamplingRefreshInterval time.Duration `yaml:"samplingRefreshInterval"`
91
92 // MaxOperations is the maximum number of operations that the PerOperationSampler
93 // will keep track of. If an operation is not tracked, a default probabilistic
94 // sampler will be used rather than the per operation specific sampler.
khenaidoo106c61a2021-08-11 18:05:46 -040095 // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_MAX_OPERATIONS.
Girish Gowdra631ef3d2020-06-15 10:45:52 -070096 MaxOperations int `yaml:"maxOperations"`
97
98 // Opt-in feature for applications that require late binding of span name via explicit
99 // call to SetOperationName when using PerOperationSampler. When this feature is enabled,
100 // the sampler will return retryable=true from OnCreateSpan(), thus leaving the sampling
101 // decision as non-final (and the span as writeable). This may lead to degraded performance
102 // in applications that always provide the correct span name on trace creation.
103 //
104 // For backwards compatibility this option is off by default.
105 OperationNameLateBinding bool `yaml:"operationNameLateBinding"`
106
107 // Options can be used to programmatically pass additional options to the Remote sampler.
108 Options []jaeger.SamplerOption
109}
110
111// ReporterConfig configures the reporter. All fields are optional.
112type ReporterConfig struct {
113 // QueueSize controls how many spans the reporter can keep in memory before it starts dropping
114 // new spans. The queue is continuously drained by a background go-routine, as fast as spans
115 // can be sent out of process.
khenaidoo106c61a2021-08-11 18:05:46 -0400116 // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_MAX_QUEUE_SIZE
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700117 QueueSize int `yaml:"queueSize"`
118
119 // BufferFlushInterval controls how often the buffer is force-flushed, even if it's not full.
120 // It is generally not useful, as it only matters for very low traffic services.
khenaidoo106c61a2021-08-11 18:05:46 -0400121 // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_FLUSH_INTERVAL
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700122 BufferFlushInterval time.Duration
123
124 // LogSpans, when true, enables LoggingReporter that runs in parallel with the main reporter
125 // and logs all submitted spans. Main Configuration.Logger must be initialized in the code
126 // for this option to have any effect.
khenaidoo106c61a2021-08-11 18:05:46 -0400127 // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_LOG_SPANS
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700128 LogSpans bool `yaml:"logSpans"`
129
khenaidoo106c61a2021-08-11 18:05:46 -0400130 // LocalAgentHostPort instructs reporter to send spans to jaeger-agent at this address.
131 // Can be provided by FromEnv() via the environment variable named JAEGER_AGENT_HOST / JAEGER_AGENT_PORT
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700132 LocalAgentHostPort string `yaml:"localAgentHostPort"`
133
khenaidoo106c61a2021-08-11 18:05:46 -0400134 // DisableAttemptReconnecting when true, disables udp connection helper that periodically re-resolves
135 // the agent's hostname and reconnects if there was a change. This option only
136 // applies if LocalAgentHostPort is specified.
137 // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_ATTEMPT_RECONNECTING_DISABLED
138 DisableAttemptReconnecting bool `yaml:"disableAttemptReconnecting"`
139
140 // AttemptReconnectInterval controls how often the agent client re-resolves the provided hostname
141 // in order to detect address changes. This option only applies if DisableAttemptReconnecting is false.
142 // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_ATTEMPT_RECONNECT_INTERVAL
143 AttemptReconnectInterval time.Duration
144
145 // CollectorEndpoint instructs reporter to send spans to jaeger-collector at this URL.
146 // Can be provided by FromEnv() via the environment variable named JAEGER_ENDPOINT
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700147 CollectorEndpoint string `yaml:"collectorEndpoint"`
148
149 // User instructs reporter to include a user for basic http authentication when sending spans to jaeger-collector.
khenaidoo106c61a2021-08-11 18:05:46 -0400150 // Can be provided by FromEnv() via the environment variable named JAEGER_USER
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700151 User string `yaml:"user"`
152
153 // Password instructs reporter to include a password for basic http authentication when sending spans to
khenaidoo106c61a2021-08-11 18:05:46 -0400154 // jaeger-collector.
155 // Can be provided by FromEnv() via the environment variable named JAEGER_PASSWORD
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700156 Password string `yaml:"password"`
157
158 // HTTPHeaders instructs the reporter to add these headers to the http request when reporting spans.
159 // This field takes effect only when using HTTPTransport by setting the CollectorEndpoint.
160 HTTPHeaders map[string]string `yaml:"http_headers"`
161}
162
163// BaggageRestrictionsConfig configures the baggage restrictions manager which can be used to whitelist
164// certain baggage keys. All fields are optional.
165type BaggageRestrictionsConfig struct {
166 // DenyBaggageOnInitializationFailure controls the startup failure mode of the baggage restriction
167 // manager. If true, the manager will not allow any baggage to be written until baggage restrictions have
168 // been retrieved from jaeger-agent. If false, the manager wil allow any baggage to be written until baggage
169 // restrictions have been retrieved from jaeger-agent.
170 DenyBaggageOnInitializationFailure bool `yaml:"denyBaggageOnInitializationFailure"`
171
172 // HostPort is the hostPort of jaeger-agent's baggage restrictions server
173 HostPort string `yaml:"hostPort"`
174
175 // RefreshInterval controls how often the baggage restriction manager will poll
176 // jaeger-agent for the most recent baggage restrictions.
177 RefreshInterval time.Duration `yaml:"refreshInterval"`
178}
179
180// ThrottlerConfig configures the throttler which can be used to throttle the
181// rate at which the client may send debug requests.
182type ThrottlerConfig struct {
183 // HostPort of jaeger-agent's credit server.
184 HostPort string `yaml:"hostPort"`
185
186 // RefreshInterval controls how often the throttler will poll jaeger-agent
187 // for more throttling credits.
188 RefreshInterval time.Duration `yaml:"refreshInterval"`
189
190 // SynchronousInitialization determines whether or not the throttler should
191 // synchronously fetch credits from the agent when an operation is seen for
192 // the first time. This should be set to true if the client will be used by
193 // a short lived service that needs to ensure that credits are fetched
194 // upfront such that sampling or throttling occurs.
195 SynchronousInitialization bool `yaml:"synchronousInitialization"`
196}
197
198type nullCloser struct{}
199
200func (*nullCloser) Close() error { return nil }
201
202// New creates a new Jaeger Tracer, and a closer func that can be used to flush buffers
203// before shutdown.
204//
205// Deprecated: use NewTracer() function
206func (c Configuration) New(
207 serviceName string,
208 options ...Option,
209) (opentracing.Tracer, io.Closer, error) {
210 if serviceName != "" {
211 c.ServiceName = serviceName
212 }
213
214 return c.NewTracer(options...)
215}
216
217// NewTracer returns a new tracer based on the current configuration, using the given options,
218// and a closer func that can be used to flush buffers before shutdown.
219func (c Configuration) NewTracer(options ...Option) (opentracing.Tracer, io.Closer, error) {
220 if c.Disabled {
221 return &opentracing.NoopTracer{}, &nullCloser{}, nil
222 }
223
224 if c.ServiceName == "" {
225 return nil, nil, errors.New("no service name provided")
226 }
227
228 opts := applyOptions(options...)
229 tracerMetrics := jaeger.NewMetrics(opts.metrics, nil)
230 if c.RPCMetrics {
231 Observer(
232 rpcmetrics.NewObserver(
233 opts.metrics.Namespace(metrics.NSOptions{Name: "jaeger-rpc", Tags: map[string]string{"component": "jaeger"}}),
234 rpcmetrics.DefaultNameNormalizer,
235 ),
236 )(&opts) // adds to c.observers
237 }
238 if c.Sampler == nil {
239 c.Sampler = &SamplerConfig{
240 Type: jaeger.SamplerTypeRemote,
241 Param: defaultSamplingProbability,
242 }
243 }
244 if c.Reporter == nil {
245 c.Reporter = &ReporterConfig{}
246 }
247
248 sampler := opts.sampler
249 if sampler == nil {
250 s, err := c.Sampler.NewSampler(c.ServiceName, tracerMetrics)
251 if err != nil {
252 return nil, nil, err
253 }
254 sampler = s
255 }
256
257 reporter := opts.reporter
258 if reporter == nil {
259 r, err := c.Reporter.NewReporter(c.ServiceName, tracerMetrics, opts.logger)
260 if err != nil {
261 return nil, nil, err
262 }
263 reporter = r
264 }
265
266 tracerOptions := []jaeger.TracerOption{
267 jaeger.TracerOptions.Metrics(tracerMetrics),
268 jaeger.TracerOptions.Logger(opts.logger),
269 jaeger.TracerOptions.CustomHeaderKeys(c.Headers),
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700270 jaeger.TracerOptions.PoolSpans(opts.poolSpans),
271 jaeger.TracerOptions.ZipkinSharedRPCSpan(opts.zipkinSharedRPCSpan),
272 jaeger.TracerOptions.MaxTagValueLength(opts.maxTagValueLength),
273 jaeger.TracerOptions.NoDebugFlagOnForcedSampling(opts.noDebugFlagOnForcedSampling),
274 }
275
khenaidoo106c61a2021-08-11 18:05:46 -0400276 if c.Gen128Bit || opts.gen128Bit {
277 tracerOptions = append(tracerOptions, jaeger.TracerOptions.Gen128Bit(true))
278 }
279
280 if opts.randomNumber != nil {
281 tracerOptions = append(tracerOptions, jaeger.TracerOptions.RandomNumber(opts.randomNumber))
282 }
283
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700284 for _, tag := range opts.tags {
285 tracerOptions = append(tracerOptions, jaeger.TracerOptions.Tag(tag.Key, tag.Value))
286 }
287
288 for _, tag := range c.Tags {
289 tracerOptions = append(tracerOptions, jaeger.TracerOptions.Tag(tag.Key, tag.Value))
290 }
291
292 for _, obs := range opts.observers {
293 tracerOptions = append(tracerOptions, jaeger.TracerOptions.Observer(obs))
294 }
295
296 for _, cobs := range opts.contribObservers {
297 tracerOptions = append(tracerOptions, jaeger.TracerOptions.ContribObserver(cobs))
298 }
299
300 for format, injector := range opts.injectors {
301 tracerOptions = append(tracerOptions, jaeger.TracerOptions.Injector(format, injector))
302 }
303
304 for format, extractor := range opts.extractors {
305 tracerOptions = append(tracerOptions, jaeger.TracerOptions.Extractor(format, extractor))
306 }
307
308 if c.BaggageRestrictions != nil {
309 mgr := remote.NewRestrictionManager(
310 c.ServiceName,
311 remote.Options.Metrics(tracerMetrics),
312 remote.Options.Logger(opts.logger),
313 remote.Options.HostPort(c.BaggageRestrictions.HostPort),
314 remote.Options.RefreshInterval(c.BaggageRestrictions.RefreshInterval),
315 remote.Options.DenyBaggageOnInitializationFailure(
316 c.BaggageRestrictions.DenyBaggageOnInitializationFailure,
317 ),
318 )
319 tracerOptions = append(tracerOptions, jaeger.TracerOptions.BaggageRestrictionManager(mgr))
320 }
321
322 if c.Throttler != nil {
323 debugThrottler := throttler.NewThrottler(
324 c.ServiceName,
325 throttler.Options.Metrics(tracerMetrics),
326 throttler.Options.Logger(opts.logger),
327 throttler.Options.HostPort(c.Throttler.HostPort),
328 throttler.Options.RefreshInterval(c.Throttler.RefreshInterval),
329 throttler.Options.SynchronousInitialization(
330 c.Throttler.SynchronousInitialization,
331 ),
332 )
333
334 tracerOptions = append(tracerOptions, jaeger.TracerOptions.DebugThrottler(debugThrottler))
335 }
336
337 tracer, closer := jaeger.NewTracer(
338 c.ServiceName,
339 sampler,
340 reporter,
341 tracerOptions...,
342 )
343
344 return tracer, closer, nil
345}
346
347// InitGlobalTracer creates a new Jaeger Tracer, and sets it as global OpenTracing Tracer.
348// It returns a closer func that can be used to flush buffers before shutdown.
349func (c Configuration) InitGlobalTracer(
350 serviceName string,
351 options ...Option,
352) (io.Closer, error) {
353 if c.Disabled {
354 return &nullCloser{}, nil
355 }
356 tracer, closer, err := c.New(serviceName, options...)
357 if err != nil {
358 return nil, err
359 }
360 opentracing.SetGlobalTracer(tracer)
361 return closer, nil
362}
363
364// NewSampler creates a new sampler based on the configuration
365func (sc *SamplerConfig) NewSampler(
366 serviceName string,
367 metrics *jaeger.Metrics,
368) (jaeger.Sampler, error) {
369 samplerType := strings.ToLower(sc.Type)
370 if samplerType == jaeger.SamplerTypeConst {
371 return jaeger.NewConstSampler(sc.Param != 0), nil
372 }
373 if samplerType == jaeger.SamplerTypeProbabilistic {
374 if sc.Param >= 0 && sc.Param <= 1.0 {
375 return jaeger.NewProbabilisticSampler(sc.Param)
376 }
377 return nil, fmt.Errorf(
378 "invalid Param for probabilistic sampler; expecting value between 0 and 1, received %v",
379 sc.Param,
380 )
381 }
382 if samplerType == jaeger.SamplerTypeRateLimiting {
383 return jaeger.NewRateLimitingSampler(sc.Param), nil
384 }
385 if samplerType == jaeger.SamplerTypeRemote || sc.Type == "" {
386 sc2 := *sc
387 sc2.Type = jaeger.SamplerTypeProbabilistic
388 initSampler, err := sc2.NewSampler(serviceName, nil)
389 if err != nil {
390 return nil, err
391 }
392 options := []jaeger.SamplerOption{
393 jaeger.SamplerOptions.Metrics(metrics),
394 jaeger.SamplerOptions.InitialSampler(initSampler),
395 jaeger.SamplerOptions.SamplingServerURL(sc.SamplingServerURL),
396 jaeger.SamplerOptions.MaxOperations(sc.MaxOperations),
397 jaeger.SamplerOptions.OperationNameLateBinding(sc.OperationNameLateBinding),
398 jaeger.SamplerOptions.SamplingRefreshInterval(sc.SamplingRefreshInterval),
399 }
400 options = append(options, sc.Options...)
401 return jaeger.NewRemotelyControlledSampler(serviceName, options...), nil
402 }
403 return nil, fmt.Errorf("unknown sampler type (%s)", sc.Type)
404}
405
406// NewReporter instantiates a new reporter that submits spans to the collector
407func (rc *ReporterConfig) NewReporter(
408 serviceName string,
409 metrics *jaeger.Metrics,
410 logger jaeger.Logger,
411) (jaeger.Reporter, error) {
khenaidoo106c61a2021-08-11 18:05:46 -0400412 sender, err := rc.newTransport(logger)
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700413 if err != nil {
414 return nil, err
415 }
416 reporter := jaeger.NewRemoteReporter(
417 sender,
418 jaeger.ReporterOptions.QueueSize(rc.QueueSize),
419 jaeger.ReporterOptions.BufferFlushInterval(rc.BufferFlushInterval),
420 jaeger.ReporterOptions.Logger(logger),
421 jaeger.ReporterOptions.Metrics(metrics))
422 if rc.LogSpans && logger != nil {
423 logger.Infof("Initializing logging reporter\n")
424 reporter = jaeger.NewCompositeReporter(jaeger.NewLoggingReporter(logger), reporter)
425 }
426 return reporter, err
427}
428
khenaidoo106c61a2021-08-11 18:05:46 -0400429func (rc *ReporterConfig) newTransport(logger jaeger.Logger) (jaeger.Transport, error) {
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700430 switch {
431 case rc.CollectorEndpoint != "":
khenaidoo106c61a2021-08-11 18:05:46 -0400432 httpOptions := []transport.HTTPOption{transport.HTTPHeaders(rc.HTTPHeaders)}
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700433 if rc.User != "" && rc.Password != "" {
434 httpOptions = append(httpOptions, transport.HTTPBasicAuth(rc.User, rc.Password))
435 }
436 return transport.NewHTTPTransport(rc.CollectorEndpoint, httpOptions...), nil
437 default:
khenaidoo106c61a2021-08-11 18:05:46 -0400438 return jaeger.NewUDPTransportWithParams(jaeger.UDPTransportParams{
439 AgentClientUDPParams: utils.AgentClientUDPParams{
440 HostPort: rc.LocalAgentHostPort,
441 Logger: logger,
442 DisableAttemptReconnecting: rc.DisableAttemptReconnecting,
443 AttemptReconnectInterval: rc.AttemptReconnectInterval,
444 },
445 })
Girish Gowdra631ef3d2020-06-15 10:45:52 -0700446 }
447}