Document how to work with fork process web server models(Gunicorn, uWSGI etc...)

docs/examples/fork-process-model/README.rst

@@ -0,0 +1,49 @@
+Working With Fork Process Models
+================================
+
+The `BatchExportSpanProcessor` is not fork-safe and doesn't work well with application servers
+(Gunicorn, uWSGI) which are based on pre-fork web server model. The `BatchExportSpanProcessor`
+spawns thread to run in the background to export spans to telemetry backend. During the fork, child
+process inherits the lock which is held by parent process and deadlock occurs. We can use fork hooks to
+get around this limitation of span processor.
+
+Please see the http://bugs.python.org/issue6721 for the problems about Python locks in (multi)threaded
+context with fork.
+
+Gunicorn post_fork hook
+-----------------------
+
+.. code-block:: python
+
+    from opentelemetry import trace
+    from opentelemetry.exporter.jaeger import JaegerSpanExporter
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+
+    def post_fork(server, worker):
+        server.log.info("Worker spawned (pid: %s)", worker.pid)
+        trace.set_tracer_provider(TracerProvider())
+        trace.get_tracer_provider().add_span_processor(
+            BatchExportSpanProcessor(JaegerSpanExporter(service_name='my-service'))
+        )
+
+
+uWSGI postfork decorator
+------------------------
+
+.. code-block:: python
+
+    from opentelemetry import trace
+    from opentelemetry.exporter.jaeger import JaegerSpanExporter
+    from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+
+    @postfork
+    def set_span_processor():
+        trace.get_tracer_provider().add_span_processor(
+            BatchExportSpanProcessor(JaegerSpanExporter(service_name='my-service'))
+        )
+
+
+The source code for the examples with Flask app are available :scm_web:`here <docs/examples/fork-process-model/>`.

docs/examples/fork-process-model/flask-gunicorn/README.rst

@@ -0,0 +1,11 @@
+Installation
+------------
+.. code-block:: sh
+
+    pip install -rrequirements.txt
+
+Run application
+---------------
+.. code-block:: sh
+
+    gunicorn flask-app -c gunicorn.config.py

docs/examples/fork-process-model/flask-gunicorn/app.py

@@ -0,0 +1,44 @@
+import flask
+from flask import request
+
+from opentelemetry import trace
+from opentelemetry.instrumentation.flask import FlaskInstrumentor
+
+application = flask.Flask(__name__)
+
+FlaskInstrumentor().instrument_app(application)
+
+
+def fib_slow(n):
+    if n <= 1:
+        return n
+    return fib_slow(n - 1) + fib_fast(n - 2)
+
+
+def fib_fast(n):
+    nth_fib = [0] * (n + 2)
+    nth_fib[1] = 1
+    for i in range(2, n + 1):
+        nth_fib[i] = nth_fib[i - 1] + nth_fib[i - 2]
+    return nth_fib[n]
+
+
+@application.route("/fibonacci")
+def fibonacci():
+    tracer = trace.get_tracer(__name__)
+    n = int(request.args.get("n", 1))
+    with tracer.start_as_current_span("root"):
+        with tracer.start_as_current_span("fib_slow") as slow_span:
+            ans = fib_slow(n)
+            slow_span.set_attribute("n", n)
+            slow_span.set_attribute("nth_fibonacci", ans)
+        with tracer.start_as_current_span("fib_fast") as fast_span:
+            ans = fib_fast(n)
+            fast_span.set_attribute("n", n)
+            fast_span.set_attribute("nth_fibonacci", ans)
+
+    return "Hello"
+
+
+if __name__ == "__main__":
+    application.run()

docs/examples/fork-process-model/flask-gunicorn/gunicorn.config.py

@@ -0,0 +1,29 @@
+from opentelemetry import trace
+from opentelemetry.exporter.jaeger import JaegerSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+bind = "127.0.0.1:8000"
+
+# Sample Worker processes
+workers = 4
+worker_class = "sync"
+worker_connections = 1000
+timeout = 30
+keepalive = 2
+
+# Sample logging
+errorlog = "-"
+loglevel = "info"
+accesslog = "-"
+access_log_format = (
+    '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'
+)
+
+
+def post_fork(server, worker):
+    server.log.info("Worker spawned (pid: %s)", worker.pid)
+    trace.set_tracer_provider(TracerProvider())
+    trace.get_tracer_provider().add_span_processor(
+        BatchExportSpanProcessor(JaegerSpanExporter(service_name="my-service"))
+    )

docs/examples/fork-process-model/flask-gunicorn/requirements.txt

@@ -0,0 +1,20 @@
+click==7.1.2
+Flask==1.1.2
+googleapis-common-protos==1.52.0
+grpcio==1.35.0
+gunicorn==20.0.4
+itsdangerous==1.1.0
+Jinja2==2.11.3
+MarkupSafe==1.1.1
+opentelemetry-api==0.17b0
+opentelemetry-exporter-jaeger==0.17b0
+opentelemetry-instrumentation==0.17b0
+opentelemetry-instrumentation-flask==0.17b0
+opentelemetry-instrumentation-wsgi==0.17b0
+opentelemetry-sdk==0.17b0
+protobuf==3.14.0
+six==1.15.0
+thrift==0.13.0
+uWSGI==2.0.19.1
+Werkzeug==1.0.1
+wrapt==1.12.1

docs/examples/fork-process-model/flask-uwsgi/README.rst

@@ -0,0 +1,12 @@
+Installation
+------------
+.. code-block:: sh
+
+    pip install -rrequirements.txt
+
+Run application
+---------------
+
+.. code-block:: sh
+
+    uwsgi --http :8000 --wsgi-file app.py --callable application --master --enable-threads

docs/examples/fork-process-model/flask-uwsgi/app.py

@@ -0,0 +1,57 @@
+import flask
+from flask import request
+from uwsgidecorators import postfork
+
+from opentelemetry import trace
+from opentelemetry.exporter.jaeger import JaegerSpanExporter
+from opentelemetry.instrumentation.flask import FlaskInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchExportSpanProcessor
+
+trace.set_tracer_provider(TracerProvider())
+
+application = flask.Flask(__name__)
+
+FlaskInstrumentor().instrument_app(application)
+tracer = trace.get_tracer(__name__)
+
+
+@postfork
+def set_span_processor():
+    trace.get_tracer_provider().add_span_processor(
+        BatchExportSpanProcessor(JaegerSpanExporter(service_name="my-service"))
+    )
+
+
+def fib_slow(n):
+    if n <= 1:
+        return n
+    return fib_slow(n - 1) + fib_fast(n - 2)
+
+
+def fib_fast(n):
+    nth_fib = [0] * (n + 2)
+    nth_fib[1] = 1
+    for i in range(2, n + 1):
+        nth_fib[i] = nth_fib[i - 1] + nth_fib[i - 2]
+    return nth_fib[n]
+
+
+@application.route("/fibonacci")
+def fibonacci():
+    n = int(request.args.get("n", 1))
+    with tracer.start_as_current_span("root"):
+        with tracer.start_as_current_span("fib_slow") as slow_span:
+            ans = fib_slow(n)
+            slow_span.set_attribute("n", n)
+            slow_span.set_attribute("nth_fibonacci", ans)
+        with tracer.start_as_current_span("fib_fast") as fast_span:
+            ans = fib_fast(n)
+            fast_span.set_attribute("n", n)
+            fast_span.set_attribute("nth_fibonacci", ans)
+
+    return "Hello"
+
+
+if __name__ == "__main__":
+    application.run()

docs/examples/fork-process-model/flask-uwsgi/requirements.txt

@@ -0,0 +1,20 @@
+click==7.1.2
+Flask==1.1.2
+googleapis-common-protos==1.52.0
+grpcio==1.35.0
+gunicorn==20.0.4
+itsdangerous==1.1.0
+Jinja2==2.11.3
+MarkupSafe==1.1.1
+opentelemetry-api==0.17b0
+opentelemetry-exporter-jaeger==0.17b0
+opentelemetry-instrumentation==0.17b0
+opentelemetry-instrumentation-flask==0.17b0
+opentelemetry-instrumentation-wsgi==0.17b0
+opentelemetry-sdk==0.17b0
+protobuf==3.14.0
+six==1.15.0
+thrift==0.13.0
+uWSGI==2.0.19.1
+Werkzeug==1.0.1
+wrapt==1.12.1