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