Improve manual tracing lab (#5)

* improve trace lab instructions

* integrate some of the LF notes

* do_stuff returns response, so we don't need _

labs/automatic-instrumentation/library-instrumentation/initial/src/app.py

@@ -1,37 +1,38 @@
-# pyright: reportMissingTypeStubs=false, reportUnknownParameterType=false, reportMissingParameterType=false, reportUnknownArgumentType=false, reportUnknownMemberType=false, reportAttributeAccessIssue=false
-
-import time
-
-import requests
-from client import ChaosClient, FakerClient
-from flask import Flask, make_response
-
-# global variables
-app = Flask(__name__)
-
-@app.route("/users", methods=["GET"])
-def get_user():
-    user, status = db.get_user(123)
-    data = {}
-    if user is not None:
-        data = {"id": user.id, "name": user.name, "address": user.address}
-    response = make_response(data, status)
-    return response
-
-
-def do_stuff():
-    time.sleep(0.1)
-    url = "http://echo:6000/"
-    _response = requests.get(url)
-
-
-@app.route("/")
-def index():
-    do_stuff()
-    current_time = time.strftime("%a, %d %b %Y %H:%M:%S", time.gmtime())
-    return f"Hello, World! It's currently {current_time}"
-
-
-if __name__ == "__main__":
-    db = ChaosClient(client=FakerClient())
-    app.run(host="0.0.0.0", debug=True)
+# pyright: reportMissingTypeStubs=false, reportUnknownParameterType=false, reportMissingParameterType=false, reportUnknownArgumentType=false, reportUnknownMemberType=false, reportAttributeAccessIssue=false
+
+import time
+
+import requests
+from client import ChaosClient, FakerClient
+from flask import Flask, make_response
+
+# global variables
+app = Flask(__name__)
+
+@app.route("/users", methods=["GET"])
+def get_user():
+    user, status = db.get_user(123)
+    data = {}
+    if user is not None:
+        data = {"id": user.id, "name": user.name, "address": user.address}
+    response = make_response(data, status)
+    return response
+
+
+def do_stuff():
+    time.sleep(0.1)
+    url = "http://echo:6000/"
+    response = requests.get(url)
+    return response
+
+
+@app.route("/")
+def index():
+    do_stuff()
+    current_time = time.strftime("%a, %d %b %Y %H:%M:%S", time.gmtime())
+    return f"Hello, World! It's currently {current_time}"
+
+
+if __name__ == "__main__":
+    db = ChaosClient(client=FakerClient())
+    app.run(host="0.0.0.0", debug=True)

labs/automatic-instrumentation/library-instrumentation/solution/src/app.py

@@ -38,7 +38,8 @@ def get_user():
 def do_stuff():
     time.sleep(0.1)
     url = "http://echo:6000/"
-    _response = requests.get(url)
+    response = requests.get(url)
+    return response
 
 
 @app.route("/")

labs/collector/initial/src/app.py

@@ -83,6 +83,7 @@ def do_stuff():
     response = requests.get(url)
     print(response.json())
     logging.info(str(response.json()))
+    return response
 
 @tracer.start_as_current_span("index")
 @app.route("/")

labs/collector/solution/src/app.py

@@ -83,6 +83,7 @@ def do_stuff():
     response = requests.get(url)
     print(response.json())
     logging.info(str(response.json()))
+    return response
 
 @tracer.start_as_current_span("index")
 @app.route("/")

labs/manual-instrumentation-logs/initial/src/app.py

@@ -22,7 +22,8 @@ def get_user():
 def do_stuff():
     time.sleep(0.1)
     url = "http://echo:6000/"
-    _response = requests.get(url)
+    response = requests.get(url)
+    return response
 
 
 @app.route("/")

labs/manual-instrumentation-logs/solution/src/app.py

@@ -34,6 +34,7 @@ def do_stuff():
     url = "http://echo:6000/"
     response = requests.get(url)
     logging.info(response.json())
+    return response
 
 
 @app.route("/")

labs/manual-instrumentation-metrics/initial/src/app.py

@@ -22,7 +22,8 @@ def get_user():
 def do_stuff():
     time.sleep(0.1)
     url = "http://echo:6000/"
-    _response = requests.get(url)
+    response = requests.get(url)
+    return response
 
 
 @app.route("/")

labs/manual-instrumentation-metrics/solution/src/app.py

@@ -47,7 +47,8 @@ def get_user():
 def do_stuff():
     time.sleep(0.1)
     url = "http://echo:6000/"
-    _response = requests.get(url)
+    response = requests.get(url)
+    return response
 
 
 @app.route("/")

labs/manual-instrumentation-traces/initial/src/app.py

@@ -23,6 +23,7 @@ def do_stuff():
     time.sleep(0.1)
     url = "http://echo:6000/"
     response = requests.get(url)
+    return response
 
 
 @app.route("/")

labs/manual-instrumentation-traces/solution/src/app.py

@@ -1,6 +1,7 @@
 # pyright: reportMissingTypeStubs=false, reportUnknownParameterType=false, reportMissingParameterType=false, reportUnknownArgumentType=false
 
 import time
+import json
 
 import requests
 from client import ChaosClient, FakerClient
@@ -47,8 +48,14 @@ def do_stuff():
 
     time.sleep(.1)
     url = "http://echo:6000/"
-    _response = requests.get(url, headers=headers)
-
+    response = requests.get(url, headers=headers)
+
+    # debug
+    print("Headers included in outbound request:")
+    print(json.dumps(response.json()["request"]["headers"], indent=2))
+
+    return response
+
 @app.route('/')
 @tracer.start_as_current_span("index")
 def index():

tutorial/content/intro/how_we_got_here/index.md

@@ -20,7 +20,7 @@ Second, there are *software abstractions* that make up the structure of the dist
 This includes elements such as load balancers, services, pods, containers and more.
 Lastly, there are physical machines that provide computational *resources* (e.g. RAM, CPU, disk space, network) to carry out work.
 
-{{< figure src="images/workload_resource_analysis_gregg.png" width=400 caption="workload and resource analysis [[Gregg16]](https://www.brendangregg.com/Slides/ACMApplicative2016_SystemMethodology/#18)" >}}
+{{< figure src="images/workload_resource_analysis.drawio.png" width=400 caption="workload and resource analysis based on [[Gregg16]](https://www.brendangregg.com/Slides/ACMApplicative2016_SystemMethodology/#18)" >}}
 <!-- 
 developers need highly detailed telemetry that they can use to pinpoint specific problems in code. Operators need broad, aggregated information from across hundreds or thousands of servers and nodes so that they can spot trends and respond quickly to outliers. Security teams need to analyze many millions of events across endpoints to discover potential intrusions; 
 -->
@@ -88,9 +88,10 @@ Instead, we perform extensive filtering to locate log events of interest.
 To understand the larger context, we must identify other related events. 
 This often results in lots of manual labour (e.g. comparing timestamps) or requires extensive domain knowledge about the applications.
 Recognizing this problem, Google developed [Dapper](https://storage.googleapis.com/pub-tools-public-publication-data/pdf/36356.pdf), which popularized the concept of distributed tracing.
-On a fundamental level, tracing is logging on steroids.
-The underlying idea is to add transactional context to logs.
-By indexing this based on this information, it is possible to infer causality and reconstruct the journey of requests in the system.
+In essence, tracing is an specialized form of logging.
+First, we add transactional context to logs.
+Then, an engine extracts this contextual information, analyzes it to infer causality between events, and stores it in a indexed manner.
+Thereby, we are able to reconstruct the journey of requests in the system.
 
 #### three pillars of observability
 On the surface, logs, metrics, and traces share many similarities in their lifecycle and components.

tutorial/content/labs/instrumentation/automatic/instrumentation_libraries/index.md

@@ -107,7 +107,8 @@ def get_user():
 def do_stuff():
     time.sleep(0.1)
     url = "http://echo:6000/"
-    _response = requests.get(url)
+    response = requests.get(url)
+    return response
 
 
 @app.route("/")

tutorial/content/labs/instrumentation/manual/_index.md

@@ -5,18 +5,16 @@ draft = false
 weight = 1
 +++
 
-Welcome to the lab on manual instrumentation!
-Let's look at how to instrument an application by directly using API and SDK packages provided by OpenTelemetry.
+Next, let’s look at how to instrument an application by directly using API and SDK packages provided by OpenTelemetry.
 In other words, manual instrumentation requires you to make modifications to the source code.
 This comes with its fair share of benefits and disadvantages.
 The biggest disadvantage is that if you are just starting out, writing manual instrumentation can be daunting because you:
-- need to get familiar with OpenTelemetry packages
+- need to familiarize yourself with OpenTelemetry packages
 - must be willing to explore how telemetry signals work under the hood
 
 It's totally reasonable to think that this is asking too much of the developers in your organization.
 Another downside could be that you don't want to add observability instrumentation to your code base.
-If that's the case, don't worry; there are other options to generate and emit telemetry.
-We'll look at them in later chapters.
+If that's the case, don't worry; OpenTelemetry's instrumentation libraries and auto-instrumentation offer a less invasive approach to generate and emit telemetry.
 
 However, there are also reasons for using manual instrumentation:
 - some languages do not support auto-instrumentation