docs: Update docs to rely more on environment variable configuration (#874)

ahayworth · fbogsany · web-flow · commit f0738faa0890 · 2021-07-13T20:55:04.000-04:00
This PR updates our documentation in a few ways: - Replaces some outdated configuration examples referencing a tracer factory - Cleans up a reference to a non-existent LMDB example - Sets the console span exporter for all current instrumentation examples - Updates docs to reflect how to configure things via the environment whenever possible or reasonable. Note that this means our examples may not flush to the console since the BatchSpanProcessor is selected by default. I think this is okay, honestly, but if it comes up we could figure out a way to select the SimpleSpanProcessor (as some examples were doing) via the environment. Fixes #872 Co-authored-by: Francis Bogsanyi <francis.bogsanyi@shopify.com>
diff --git a/api/README.md b/api/README.md
@@ -29,11 +29,11 @@ Then, use the OpenTelemetry interfaces to produces traces and other telemetry da
 ```ruby
 require 'opentelemetry'
 
-# Obtain the current default tracer factory
-factory = OpenTelemetry.tracer_factory
+# Obtain the current default tracer provider
+provider = OpenTelemetry.tracer_provider
 
 # Create a trace
-tracer = factory.tracer('my_app', '1.0')
+tracer = provider.tracer('my_app', '1.0')
 
 # Record spans
 tracer.in_span('my_task') do |task_span|
diff --git a/exporter/jaeger/README.md b/exporter/jaeger/README.md
@@ -31,18 +31,27 @@ Then, configure the SDK to use a Jaeger exporter as a span processor, and use th
 require 'opentelemetry/sdk'
 require 'opentelemetry/exporter/jaeger'
 
-# Configure the sdk with custom export
-OpenTelemetry::SDK.configure do |c|
-  c.add_span_processor(
-    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::Jaeger::AgentExporter.new(host: '127.0.0.1', port: 6831)
-      # Alternatively, for the collector exporter:
-      # exporter: OpenTelemetry::Exporter::Jaeger::CollectorExporter.new(endpoint: 'http://192.168.0.1:14268/api/traces')
-    )
-  )
-  c.service_name = 'jaeger-example'
-  c.service_version = '0.6.0'
-end
+# Configure the sdk with the Jaeger collector exporter
+ENV['OTEL_TRACES_EXPORTER'] = 'jaeger'
+
+ENV['OTEL_SERVICE_NAME'] = 'jaeger-example'
+ENV['OTEL_SERVICE_VERSION'] = '0.6.0'
+
+# The exporter will connect to localhost:6381 by default. To change:
+# ENV['OTEL_EXPORTER_JAEGER_AGENT_HOST'] = 'some.other.host'
+# ENV['OTEL_EXPORTER_JAEGER_AGENT_PORT'] = 12345
+
+# The SDK reads the environment for configuration, so no additional configuration is needed:
+OpenTelemetry::SDK.configure
+
+# If you need to use the Jaeger Agent exporter, you will need to configure many things manually:
+# OpenTelemetry::SDK.configure do |c|
+#   c.add_span_processor(
+#     OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+#       OpenTelemetry::Exporter::Jaeger::AgentExporter.new(host: '127.0.0.1', port: 6831)
+#     )
+#   )
+# end
 
 # To start a trace you need to get a Tracer from the TracerProvider
 tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')
diff --git a/exporter/otlp/README.md b/exporter/otlp/README.md
@@ -35,16 +35,15 @@ Then, configure the SDK to use the OTLP exporter as a span processor, and use th
 require 'opentelemetry/sdk'
 require 'opentelemetry/exporter/otlp'
 
-# Configure the sdk with custom export
-OpenTelemetry::SDK.configure do |c|
-  c.add_span_processor(
-    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::OTLP::Exporter.new(
-        compression: 'gzip'
-      )
-    )
-  )
-end
+# The OTLP exporter is the default, so no configuration is needed.
+# However, it could be manually selected via an environment variable if required:
+#
+# ENV['OTEL_TRACES_EXPORTER'] = 'otlp'
+#
+# You may also configure various settings via environment variables:
+# ENV['OTEL_EXPORTER_OTLP_COMPRESSION'] = 'gzip'
+
+OpenTelemetry::SDK.configure
 
 # To start a trace you need to get a Tracer from the TracerProvider
 tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')
@@ -67,7 +66,7 @@ For additional examples, see the [examples on github][examples-github].
 
 ## How can I configure the OTLP exporter?
 
-The collector exporter can be configured explicitly in code, as shown above, or via environment variables. The configuration parameters, environment variables, and defaults are shown below.
+The collector exporter can be configured explicitly in code, or via environment variables as shown above. The configuration parameters, environment variables, and defaults are shown below.
 
 | Parameter           | Environment variable                         | Default                             |
 | ------------------- | -------------------------------------------- | ----------------------------------- |
diff --git a/exporter/zipkin/README.md b/exporter/zipkin/README.md
@@ -31,16 +31,14 @@ Then, configure the SDK to use a zipkin exporter as a span processor, and use th
 require 'opentelemetry/sdk'
 require 'opentelemetry/exporter/zipkin'
 
-# Configure the sdk with custom export
-OpenTelemetry::SDK.configure do |c|
-  c.add_span_processor(
-    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
-      OpenTelemetry::Exporter::Zipkin::Exporter.new(endpoint: 'http://192.168.0.1:9411/api/v2/spans' )
-    )
-  )
-  c.service_name = 'zipkin-example'
-  c.service_version = '0.15.0'
-end
+# Select the zipkin exporter via environmental variables
+ENV['OTEL_TRACES_EXPORTER'] = 'zipkin'
+
+ENV['OTEL_SERVICE_NAME'] = 'zipkin-example'
+ENV['OTEL_SERVICE_VERSION'] = '0.15.0'
+
+# The zipkin expects an exporter running on localhost:9411 - you may override this if needed:
+# ENV['OTEL_EXPORTER_ZIPKIN_ENDPOINT'] = 'http://some.other.host:12345'
 
 # To start a trace you need to get a Tracer from the TracerProvider
 tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')
@@ -63,7 +61,7 @@ For additional examples, see the [examples on github][examples-github].
 
 ## How can I configure the Zipkin exporter?
 
-The collector exporter can be configured explicitly in code, as shown above, or via environment variables. The configuration parameters, environment variables, and defaults are shown below.
+The collector exporter can be configured explicitly in code, or via environment variables as shown above. The configuration parameters, environment variables, and defaults are shown below.
 
 | Parameter   | Environment variable                  | Default                    |
 | ----------- | --------------------------------------| -------------------------- |
diff --git a/instrumentation/bunny/example/bunny.rb b/instrumentation/bunny/example/bunny.rb
@@ -11,13 +11,9 @@
 
 require 'bunny'
 
-span_processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
-  OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
-)
-
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Bunny'
-  c.add_span_processor(span_processor)
 end
 
 # Start a communication session with RabbitMQ
diff --git a/instrumentation/concurrent_ruby/example/concurrent_ruby.rb b/instrumentation/concurrent_ruby/example/concurrent_ruby.rb
@@ -5,6 +5,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::ConcurrentRuby'
 end
diff --git a/instrumentation/dalli/example/dalli.rb b/instrumentation/dalli/example/dalli.rb
@@ -5,6 +5,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Dalli'
 end
diff --git a/instrumentation/delayed_job/example/delayed_job.rb b/instrumentation/delayed_job/example/delayed_job.rb
@@ -9,6 +9,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::DelayedJob'
 end
diff --git a/instrumentation/ethon/example/ethon.rb b/instrumentation/ethon/example/ethon.rb
@@ -5,6 +5,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Ethon'
 end
diff --git a/instrumentation/excon/example/excon.rb b/instrumentation/excon/example/excon.rb
@@ -5,6 +5,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Excon'
 end
diff --git a/instrumentation/faraday/example/faraday.rb b/instrumentation/faraday/example/faraday.rb
@@ -9,6 +9,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Faraday'
 end
diff --git a/instrumentation/graphql/example/graphql.rb b/instrumentation/graphql/example/graphql.rb
@@ -41,6 +41,7 @@ def initialize(id = 1, name = 'bar')
   query QueryType
 end
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use_all('OpenTelemetry::Instrumentation::GraphQL' => { schemas: [Schema] })
 end
diff --git a/instrumentation/http_client/example/trace_demonstration.rb b/instrumentation/http_client/example/trace_demonstration.rb
@@ -6,6 +6,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::HttpClient'
 end
diff --git a/instrumentation/koala/example/trace_demonstration.rb b/instrumentation/koala/example/trace_demonstration.rb
@@ -6,6 +6,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
   c.use 'OpenTelemetry::Instrumentation::Koala'
diff --git a/instrumentation/lmdb/README.md b/instrumentation/lmdb/README.md
@@ -30,10 +30,6 @@ OpenTelemetry::SDK.configure do |c|
 end
 ```
 
-## Examples
-
-Example usage can be seen in the `./example/trace_demonstration.rb` file [here](https://github.com/open-telemetry/opentelemetry-ruby/blob/main/instrumentation/lmdb/example/trace_demonstration.rb)
-
 ## How can I get involved?
 
 The `opentelemetry-instrumentation-lmdb` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
diff --git a/instrumentation/mysql2/example/mysql2.rb b/instrumentation/mysql2/example/mysql2.rb
@@ -5,6 +5,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Mysql2'
 end
diff --git a/instrumentation/net_http/example/net_http.rb b/instrumentation/net_http/example/net_http.rb
@@ -6,6 +6,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
 end
diff --git a/instrumentation/pg/example/pg.rb b/instrumentation/pg/example/pg.rb
@@ -5,9 +5,9 @@
 
 Bundler.require
 
-enable_sql_obfuscation = true
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
-  c.use 'OpenTelemetry::Instrumentation::PG', enable_sql_obfuscation: enable_sql_obfuscation
+  c.use 'OpenTelemetry::Instrumentation::PG', enable_sql_obfuscation: true
 end
 
 conn = PG::Connection.open(
diff --git a/instrumentation/rack/example/trace_demonstration.rb b/instrumentation/rack/example/trace_demonstration.rb
@@ -9,6 +9,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Rack'
 end
diff --git a/instrumentation/rack/example/trace_demonstration2.rb b/instrumentation/rack/example/trace_demonstration2.rb
@@ -15,6 +15,7 @@
 builder.run app
 
 # demonstrate integration using 'retain_middlware_names' and 'application':
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Rack',
         retain_middleware_names: true,
diff --git a/instrumentation/rails/example/trace_request_demonstration.ru b/instrumentation/rails/example/trace_request_demonstration.ru
@@ -28,15 +28,9 @@ class TraceRequestApp < Rails::Application
   Rails.logger  = config.logger
 end
 
-# Simple setup for demonstration purposes, simple span processor should not be
-# used in a production environment
-span_processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
-  OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
-)
-
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Rails'
-  c.add_span_processor(span_processor)
 end
 
 Rails.application.initialize!
diff --git a/instrumentation/restclient/example/restclient.rb b/instrumentation/restclient/example/restclient.rb
@@ -5,6 +5,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::RestClient'
 end
diff --git a/instrumentation/ruby_kafka/example/ruby_kafka.rb b/instrumentation/ruby_kafka/example/ruby_kafka.rb
@@ -12,13 +12,9 @@
 require 'kafka'
 require 'active_support'
 
-span_processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
-  OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
-)
-
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::RubyKafka'
-  c.add_span_processor(span_processor)
 end
 
 # Assumes kafka is available
diff --git a/instrumentation/sinatra/example/server.rb b/instrumentation/sinatra/example/server.rb
@@ -11,6 +11,7 @@
 
 Bundler.require
 
+ENV['OTEL_TRACES_EXPORTER'] = 'console'
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Sinatra'
 end
diff --git a/sdk/README.md b/sdk/README.md
@@ -29,10 +29,33 @@ Then, configure the SDK according to your desired handling of telemetry data, an
 ```ruby
 require 'opentelemetry/sdk'
 
-# Configure the sdk with default export and context propagation formats
-# see SDK#configure for customizing the setup
+# Configure the sdk with default export and context propagation formats.
 OpenTelemetry::SDK.configure
 
+# Many configuration options may be set via the environment. To use them,
+# set the appropriate variable before calling configure. For example:
+#
+# ENV['OTEL_TRACES_EXPORTER'] = 'console'
+# ENV['OTEL_PROPAGATORS'] = 'ottrace'
+# OpenTelemetry::SDK.configure
+#
+# You may also configure the SDK programmatically, for advanced usage or to
+# enable auto-instrumentation. For example:
+#
+# OpenTelemetry::SDK.configure do |c|
+#   c.service_name = something_calculated_dynamically
+#   c.add_span_processor(
+#     OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
+#       OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
+#     )
+#   )
+#
+#   c.use 'OpenTelemetry::Instrumentation::Net::HTTP'
+# end
+#
+# Note that the SimpleSpanExporter is not recommended for use in production.
+
+
 # To start a trace you need to get a Tracer from the TracerProvider
 tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')
 
