diff --git a/README.md b/README.md index 2676ddd7..e7b13b1c 100644 --- a/README.md +++ b/README.md @@ -44,8 +44,11 @@ and [config/example_test.go](./config/example_test.go). ### Environment variables -The tracer can be initialized with values coming from environment variables. None of the env vars are required -and all of them can be overridden via direct setting of the property on the configuration object. +The tracer can be initialized with values coming from environment variables, if it is +[built from a config](https://pkg.go.dev/github.com/uber/jaeger-client-go/config?tab=doc#Configuration.NewTracer) +that was created via [FromEnv()](https://pkg.go.dev/github.com/uber/jaeger-client-go/config?tab=doc#FromEnv). +None of the env vars are required and all of them can be overridden via direct setting +of the property on the configuration object. Property| Description --- | --- diff --git a/config/config.go b/config/config.go index ec36c6bc..e6ffb987 100644 --- a/config/config.go +++ b/config/config.go @@ -36,16 +36,16 @@ const defaultSamplingProbability = 0.001 // Configuration configures and creates Jaeger Tracer type Configuration struct { // ServiceName specifies the service name to use on the tracer. - // Can be provided via environment variable named JAEGER_SERVICE_NAME + // Can be provided by FromEnv() via the environment variable named JAEGER_SERVICE_NAME ServiceName string `yaml:"serviceName"` - // Disabled can be provided via environment variable named JAEGER_DISABLED + // Disabled can be provided by FromEnv() via the environment variable named JAEGER_DISABLED Disabled bool `yaml:"disabled"` - // RPCMetrics can be provided via environment variable named JAEGER_RPC_METRICS + // RPCMetrics can be provided by FromEnv() via the environment variable named JAEGER_RPC_METRICS RPCMetrics bool `yaml:"rpc_metrics"` - // Tags can be provided via environment variable named JAEGER_TAGS + // Tags can be provided by FromEnv() via the environment variable named JAEGER_TAGS Tags []opentracing.Tag `yaml:"tags"` Sampler *SamplerConfig `yaml:"sampler"` @@ -57,8 +57,8 @@ type Configuration struct { // SamplerConfig allows initializing a non-default sampler. All fields are optional. type SamplerConfig struct { - // Type specifies the type of the sampler: const, probabilistic, rateLimiting, or remote - // Can be set by exporting an environment variable named JAEGER_SAMPLER_TYPE + // Type specifies the type of the sampler: const, probabilistic, rateLimiting, or remote. + // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_TYPE Type string `yaml:"type"` // Param is a value passed to the sampler. @@ -69,23 +69,23 @@ type SamplerConfig struct { // - for "remote" sampler, param is the same as for "probabilistic" // and indicates the initial sampling rate before the actual one // is received from the mothership. - // Can be set by exporting an environment variable named JAEGER_SAMPLER_PARAM + // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_PARAM Param float64 `yaml:"param"` // SamplingServerURL is the URL of sampling manager that can provide // sampling strategy to this service. - // Can be set by exporting an environment variable named JAEGER_SAMPLING_ENDPOINT + // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLING_ENDPOINT SamplingServerURL string `yaml:"samplingServerURL"` // SamplingRefreshInterval controls how often the remotely controlled sampler will poll // sampling manager for the appropriate sampling strategy. - // Can be set by exporting an environment variable named JAEGER_SAMPLER_REFRESH_INTERVAL + // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_REFRESH_INTERVAL SamplingRefreshInterval time.Duration `yaml:"samplingRefreshInterval"` // MaxOperations is the maximum number of operations that the PerOperationSampler // will keep track of. If an operation is not tracked, a default probabilistic // sampler will be used rather than the per operation specific sampler. - // Can be set by exporting an environment variable named JAEGER_SAMPLER_MAX_OPERATIONS. + // Can be provided by FromEnv() via the environment variable named JAEGER_SAMPLER_MAX_OPERATIONS. MaxOperations int `yaml:"maxOperations"` // Opt-in feature for applications that require late binding of span name via explicit @@ -106,34 +106,35 @@ type ReporterConfig struct { // QueueSize controls how many spans the reporter can keep in memory before it starts dropping // new spans. The queue is continuously drained by a background go-routine, as fast as spans // can be sent out of process. - // Can be set by exporting an environment variable named JAEGER_REPORTER_MAX_QUEUE_SIZE + // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_MAX_QUEUE_SIZE QueueSize int `yaml:"queueSize"` // BufferFlushInterval controls how often the buffer is force-flushed, even if it's not full. // It is generally not useful, as it only matters for very low traffic services. - // Can be set by exporting an environment variable named JAEGER_REPORTER_FLUSH_INTERVAL + // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_FLUSH_INTERVAL BufferFlushInterval time.Duration // LogSpans, when true, enables LoggingReporter that runs in parallel with the main reporter // and logs all submitted spans. Main Configuration.Logger must be initialized in the code // for this option to have any effect. - // Can be set by exporting an environment variable named JAEGER_REPORTER_LOG_SPANS + // Can be provided by FromEnv() via the environment variable named JAEGER_REPORTER_LOG_SPANS LogSpans bool `yaml:"logSpans"` - // LocalAgentHostPort instructs reporter to send spans to jaeger-agent at this address - // Can be set by exporting an environment variable named JAEGER_AGENT_HOST / JAEGER_AGENT_PORT + // LocalAgentHostPort instructs reporter to send spans to jaeger-agent at this address. + // Can be provided by FromEnv() via the environment variable named JAEGER_AGENT_HOST / JAEGER_AGENT_PORT LocalAgentHostPort string `yaml:"localAgentHostPort"` - // CollectorEndpoint instructs reporter to send spans to jaeger-collector at this URL - // Can be set by exporting an environment variable named JAEGER_ENDPOINT + // CollectorEndpoint instructs reporter to send spans to jaeger-collector at this URL. + // Can be provided by FromEnv() via the environment variable named JAEGER_ENDPOINT CollectorEndpoint string `yaml:"collectorEndpoint"` // User instructs reporter to include a user for basic http authentication when sending spans to jaeger-collector. - // Can be set by exporting an environment variable named JAEGER_USER + // Can be provided by FromEnv() via the environment variable named JAEGER_USER User string `yaml:"user"` // Password instructs reporter to include a password for basic http authentication when sending spans to - // jaeger-collector. Can be set by exporting an environment variable named JAEGER_PASSWORD + // jaeger-collector. + // Can be provided by FromEnv() via the environment variable named JAEGER_PASSWORD Password string `yaml:"password"` // HTTPHeaders instructs the reporter to add these headers to the http request when reporting spans. diff --git a/config/example_test.go b/config/example_test.go index a81853ad..70cba17c 100644 --- a/config/example_test.go +++ b/config/example_test.go @@ -26,6 +26,48 @@ import ( jaegerlog "github.com/uber/jaeger-client-go/log" ) +func ExampleFromEnv() { + cfg, err := jaegercfg.FromEnv() + if err != nil { + // parsing errors might happen here, such as when we get a string where we expect a number + log.Printf("Could not parse Jaeger env vars: %s", err.Error()) + return + } + + tracer, closer, err := cfg.NewTracer() + if err != nil { + log.Printf("Could not initialize jaeger tracer: %s", err.Error()) + return + } + defer closer.Close() + + opentracing.SetGlobalTracer(tracer) + // continue main() +} + +func ExampleFromEnv_override() { + os.Setenv("JAEGER_SERVICE_NAME", "not-effective") + + cfg, err := jaegercfg.FromEnv() + if err != nil { + // parsing errors might happen here, such as when we get a string where we expect a number + log.Printf("Could not parse Jaeger env vars: %s", err.Error()) + return + } + + cfg.ServiceName = "this-will-be-the-service-name" + + tracer, closer, err := cfg.NewTracer() + if err != nil { + log.Printf("Could not initialize jaeger tracer: %s", err.Error()) + return + } + defer closer.Close() + + opentracing.SetGlobalTracer(tracer) + // continue main() +} + func ExampleConfiguration_InitGlobalTracer_testing() { // Sample configuration for testing. Use constant sampling to sample every trace // and enable LogSpan to log every span via configured Logger. @@ -84,45 +126,3 @@ func ExampleConfiguration_InitGlobalTracer_production() { // continue main() } - -func ExampleFromEnv() { - cfg, err := jaegercfg.FromEnv() - if err != nil { - // parsing errors might happen here, such as when we get a string where we expect a number - log.Printf("Could not parse Jaeger env vars: %s", err.Error()) - return - } - - tracer, closer, err := cfg.NewTracer() - if err != nil { - log.Printf("Could not initialize jaeger tracer: %s", err.Error()) - return - } - defer closer.Close() - - opentracing.SetGlobalTracer(tracer) - // continue main() -} - -func ExampleFromEnv_override() { - os.Setenv("JAEGER_SERVICE_NAME", "not-effective") - - cfg, err := jaegercfg.FromEnv() - if err != nil { - // parsing errors might happen here, such as when we get a string where we expect a number - log.Printf("Could not parse Jaeger env vars: %s", err.Error()) - return - } - - cfg.ServiceName = "this-will-be-the-service-name" - - tracer, closer, err := cfg.NewTracer() - if err != nil { - log.Printf("Could not initialize jaeger tracer: %s", err.Error()) - return - } - defer closer.Close() - - opentracing.SetGlobalTracer(tracer) - // continue main() -}