Add coding examples for context (open-telemetry#1165)

ahlaw · web-flow · commit 51ed4576c611 · 2020-10-21T23:14:01.000-07:00
diff --git a/docs/examples/basic_context/README.rst b/docs/examples/basic_context/README.rst
@@ -0,0 +1,39 @@
+Basic Context
+=============
+
+These examples show how context is propagated through Spans in OpenTelemetry.
+
+There are three different examples:
+
+* implicit_context: Shows how starting a span implicitly creates context.
+
+* child_context: Shows how context is propagated through child spans.
+
+* async_context: Shows how context can be shared in another coroutine.
+
+The source files of these examples are available :scm_web:`here <docs/examples/basic_context/>`.
+
+Installation
+------------
+
+.. code-block:: sh
+
+    pip install opentelemetry-api
+    pip install opentelemetry-sdk
+
+Run the Example
+---------------
+
+.. code-block:: sh
+
+    python <example_name>.py
+
+The output will be shown in the console.
+
+Useful links
+------------
+
+- OpenTelemetry_
+- :doc:`../../api/trace`
+
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
diff --git a/docs/examples/basic_context/async_context.py b/docs/examples/basic_context/async_context.py
@@ -0,0 +1,38 @@
+# 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.
+
+import asyncio
+
+from opentelemetry import baggage, trace
+from opentelemetry.sdk.trace import TracerProvider
+
+trace.set_tracer_provider(TracerProvider())
+tracer = trace.get_tracer(__name__)
+
+loop = asyncio.get_event_loop()
+
+
+async def async_span(span):
+    with tracer.use_span(span):
+        ctx = baggage.set_baggage("foo", "bar")
+    return ctx
+
+
+async def main():
+    span = tracer.start_span(name="span")
+    ctx = await async_span(span)
+    print(baggage.get_all(context=ctx))
+
+
+loop.run_until_complete(main())
diff --git a/docs/examples/basic_context/child_context.py b/docs/examples/basic_context/child_context.py
@@ -0,0 +1,29 @@
+# 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 opentelemetry import baggage, trace
+
+tracer = trace.get_tracer(__name__)
+
+global_ctx = baggage.set_baggage("context", "global")
+with tracer.start_as_current_span(name="root span") as root_span:
+    parent_ctx = baggage.set_baggage("context", "parent")
+    with tracer.start_as_current_span(
+        name="child span", context=parent_ctx
+    ) as child_span:
+        child_ctx = baggage.set_baggage("context", "child")
+
+print(baggage.get_baggage("context", global_ctx))
+print(baggage.get_baggage("context", parent_ctx))
+print(baggage.get_baggage("context", child_ctx))
diff --git a/docs/examples/basic_context/implicit_context.py b/docs/examples/basic_context/implicit_context.py
@@ -0,0 +1,25 @@
+# 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 opentelemetry import baggage, trace
+from opentelemetry.sdk.trace import TracerProvider
+
+trace.set_tracer_provider(TracerProvider())
+tracer = trace.get_tracer(__name__)
+
+with tracer.start_span(name="root span") as root_span:
+    ctx = baggage.set_baggage("foo", "bar")
+
+print("Global context baggage: {}".format(baggage.get_all()))
+print("Span context baggage: {}".format(baggage.get_all(context=ctx)))
diff --git a/docs/faq-and-cookbook.rst b/docs/faq-and-cookbook.rst
@@ -25,3 +25,21 @@ Getting and modifying a span
 
     current_span = trace.get_current_span()
     current_span.set_attribute("hometown", "seattle")
+
+Capturing baggage at different contexts
+---------------------------------------
+
+.. code-block:: python
+
+    from opentelemetry import trace
+
+    tracer = trace.get_tracer(__name__)
+    with tracer.start_as_current_span(name="root span") as root_span:
+        parent_ctx = baggage.set_baggage("context", "parent")
+        with tracer.start_as_current_span(
+            name="child span", context=parent_ctx
+        ) as child_span:
+            child_ctx = baggage.set_baggage("context", "child")
+
+    print(baggage.get_baggage("context", parent_ctx))
+    print(baggage.get_baggage("context", child_ctx))
