Repository: open-telemetry/opentelemetry-python

Issue:
Document usage of programmatic instrumentation
Besides manual and automatic instrumentation, we also offer _programmatic_ instrumentation for some instrumentation libraries. In programmatic instrumentation, a third-party-library-specific instance of a subclass of `BaseInstrumentor` is instantiated and some method of this object is called by the user. [Here](https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-flask/tests/test_programmatic.py#L95) is an example for the Flask instrumentation library. The name "programmatic" is taken from that test file name.

Document this kind of instrumentation also.


Discussion:

Resolving patch:
diff --git a/docs/examples/auto-instrumentation/server_uninstrumented.py b/docs/examples/auto-instrumentation/server_automatic.py
similarity index 100%
rename from docs/examples/auto-instrumentation/server_uninstrumented.py
rename to docs/examples/auto-instrumentation/server_automatic.py
diff --git a/docs/examples/auto-instrumentation/server_instrumented.py b/docs/examples/auto-instrumentation/server_manual.py
similarity index 83%
rename from docs/examples/auto-instrumentation/server_instrumented.py
rename to docs/examples/auto-instrumentation/server_manual.py
--- a/docs/examples/auto-instrumentation/server_instrumented.py
+++ b/docs/examples/auto-instrumentation/server_manual.py
@@ -14,7 +14,6 @@
 
 from flask import Flask, request
 
-from opentelemetry import trace
 from opentelemetry.instrumentation.wsgi import collect_request_attributes
 from opentelemetry.propagate import extract
 from opentelemetry.sdk.trace import TracerProvider
@@ -22,13 +21,18 @@
     BatchSpanProcessor,
     ConsoleSpanExporter,
 )
+from opentelemetry.trace import (
+    SpanKind,
+    get_tracer_provider,
+    set_tracer_provider,
+)
 
 app = Flask(__name__)
 
-trace.set_tracer_provider(TracerProvider())
-tracer = trace.get_tracer_provider().get_tracer(__name__)
+set_tracer_provider(TracerProvider())
+tracer = get_tracer_provider().get_tracer(__name__)
 
-trace.get_tracer_provider().add_span_processor(
+get_tracer_provider().add_span_processor(
     BatchSpanProcessor(ConsoleSpanExporter())
 )
 
@@ -38,7 +42,7 @@ def server_request():
     with tracer.start_as_current_span(
         "server_request",
         context=extract(request.headers),
-        kind=trace.SpanKind.SERVER,
+        kind=SpanKind.SERVER,
         attributes=collect_request_attributes(request.environ),
     ):
         print(request.args.get("param"))
diff --git a/docs/examples/auto-instrumentation/server_programmatic.py b/docs/examples/auto-instrumentation/server_programmatic.py
new file mode 100644
--- /dev/null
+++ b/docs/examples/auto-instrumentation/server_programmatic.py
@@ -0,0 +1,45 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from flask import Flask, request
+
+from opentelemetry.instrumentation.flask import FlaskInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ConsoleSpanExporter,
+)
+from opentelemetry.trace import get_tracer_provider, set_tracer_provider
+
+set_tracer_provider(TracerProvider())
+get_tracer_provider().add_span_processor(
+    BatchSpanProcessor(ConsoleSpanExporter())
+)
+
+instrumentor = FlaskInstrumentor()
+
+app = Flask(__name__)
+
+instrumentor.instrument_app(app)
+# instrumentor.instrument_app(app, excluded_urls="/server_request")
+
+
+@app.route("/server_request")
+def server_request():
+    print(request.args.get("param"))
+    return "served"
+
+
+if __name__ == "__main__":
+    app.run(port=8082)


Test patch: