doc: clarify SDK configuration options (command vs function) and fina…

…l developing.md & readme.md audits (#105)

<!--
Thank you for contributing to the project! 💜
Please see our [OSS process
document](https://github.com/honeycombio/home/blob/main/honeycomb-oss-lifecycle-and-practices.md#)
to get an idea of how we operate.
-->

## Which problem is this PR solving?

- Closes #57 
- Closes #77 

## Short description of the changes
- Created an examples overview 
- Comments to smoke tests re: testing both configure_opentelemetry() and
opentelemetry_instrument
- Moved example development notes to developing.md
- Left additional breadcrumbs for others to use the smoke-test
docker-compose for running examples with collector should they so choose

## How to verify that this has the expected result
All the links in the readme's work.
Finding information about example usage is clear.
It's clear there are two ways to use the distro:
configure_opentelemetry() or opentelemetry_instrument

Note: This is probably best reviewed by viewing the readme's in the
[repo
view](https://github.com/honeycombio/honeycomb-opentelemetry-python/tree/emash-config-vs-command)
rather than the .md diffs :)

DEVELOPING.md

@@ -18,14 +18,9 @@ make build
 ```
 
 ## Examples
+Check out the [Example Application overview](/examples/). 
 
-### Example Flask Application
-
-Readme can be found [here](examples/hello-world-flask/README.md) for setting this up.
-
-### Example Python Application
-
-Readme can be found [here](examples/hello-world/README.md) for setting this up.
+Note: Changes to python files in `src/honeycomb/opentelemetry` should propagate to the example applications upon save. Changes in the honeycomb.opentelemetry's pyproject.toml may need a `poetry build` to take effect in the example applications.
 
 ### Running with Docker-Compose
 

Makefile

@@ -57,31 +57,31 @@ smoke-tests/collector/data.json:
 	@echo "+++ Zhuzhing smoke test's Collector data.json"
 	@touch $@ && chmod o+w $@
 
-#: smoke test the app using grpc protocol
+#: smoke test the hello-world app using grpc protocol and configure_opentelemetry()
 smoke-sdk-grpc: smoke-tests/collector/data.json
 	@echo ""
-	@echo "+++ Running gRPC smoke tests."
+	@echo "+++ Running gRPC smoke tests on configure_opentelemetry()"
 	@echo ""
 	cd smoke-tests && bats ./smoke-sdk-grpc.bats --report-formatter junit --output ./
 
-#: smoke test the app using http/protobuf protocol
+#: smoke test the hello-world app using http/protobuf protocol and configure_opentelemetry()
 smoke-sdk-http: smoke-tests/collector/data.json
 	@echo ""
-	@echo "+++ Running HTTP smoke tests."
+	@echo "+++ Running HTTP smoke tests on configure_opentelemetry()"
 	@echo ""
 	cd smoke-tests && bats ./smoke-sdk-http.bats --report-formatter junit --output ./
 
-#: smoke test the flask app using grpc protocol
+#: smoke test the flask app using grpc protocol and opentelemetry_instrument
 smoke-sdk-grpc-flask: smoke-tests/collector/data.json
 	@echo ""
-	@echo "+++ Running GRPC Flask smoke tests."
+	@echo "+++ Running GRPC Flask smoke tests on opentelemetry_instrument"
 	@echo ""
 	cd smoke-tests && bats ./smoke-sdk-grpc-flask.bats --report-formatter junit --output ./
 
-#: smoke test the flask app using http protocol
+#: smoke test the flask app using http protocol and opentelemetry_instrument
 smoke-sdk-http-flask: smoke-tests/collector/data.json
 	@echo ""
-	@echo "+++ Running HTTP Flask smoke tests."
+	@echo "+++ Running HTTP Flask smoke tests on opentelemetry_instrument"
 	@echo ""
 	cd smoke-tests && bats ./smoke-sdk-http-flask.bats --report-formatter junit --output ./
 

README.md

@@ -31,12 +31,3 @@ Honeycomb's Distribution of OpenTelemetry for python allows you to streamline co
 
 [Apache 2.0 License](./LICENSE).
 
-## Examples
-
-### Example Flask Application
-
-Readme can be found [here](examples/hello-world-flask/README.md) for setting this up.
-
-### Example Python Application
-
-Readme can be found [here](examples/hello-world/README.md) for setting this up.

examples/README.md

@@ -0,0 +1,35 @@
+# Examples
+
+## [Hello World Flask](hello-world-flask/)
+
+This example configures the distro using the `opentelemetry_instrument` command, and contains examples of:
+- configuring the distro with environment variables
+ - sending metrics with OpenTelemetry using a counter
+ - using baggage with context tokens
+ - manually passing baggage with context
+ - setting a span attribute
+
+Check out the [Hello-World-Flask Readme](hello-world-flask/README.md) for setting this up!
+
+## [Hello World Python](hello-world/)
+
+This example configures the distro using the `configure_opentelemetry()` function, and contains examples of:
+ - configuring the distro with a combination of parameters and set environment variables
+ - sending metrics with OpenTelemetry using a counter
+ - using baggage with context tokens
+ - setting a span attribute
+
+Check out the [Hello-World Readme](hello-world/README.md) for setting this up!
+
+## Running Examples with Docker-Compose
+
+If you'd like to use Docker for running these examples, there is a `docker-compose.yml` we use for smoke-tests [that may be helpful.](../smoke-tests/docker-compose.yml)
+
+We have the HONEYCOMB_API_ENDPOINT set to an OpenTelemetry Collector. This can be modified as needed or deleted entirely to use the default Honeycomb API Endpoint.
+
+Because each example uses the same port, either comment out the other apps in the docker-compose file, or specify the app and protocol to run:
+
+```bash
+cd smoke-tests && docker-compose up --build app-sdk-grpc
+```
+

examples/hello-world-flask/README.md

@@ -1,6 +1,14 @@
 # hello-world-flask
 
-This simple Flask app that returns "Hello World". This app configures OpenTelemetry to send data to Honeycomb through environment variables. It also contains an example of sending metrics with OpenTelemetry.
+This simple Flask app that returns "Hello World". This app configures OpenTelemetry to send data to Honeycomb using the `opentelemetry_instrument` command and environment variables. 
+
+It also contains examples of:
+ - sending metrics with OpenTelemetry using a counter
+ - using baggage with context tokens
+ - manually passing baggage with context
+ - setting a span attribute
+
+If you are looking for an example using the `configure_opentelemetry()` function and parameters, check out [hello-world app](../hello-world/README.md).
 
 ## Prerequisites
 
@@ -31,21 +39,18 @@ Hello World
 
 To send traces to local console:
 
-For local export right now
-
 ```bash
 DEBUG=TRUE poetry run opentelemetry-instrument flask run
 ```
 
-To send to Honeycomb:
+To send traces to Honeycomb:
 
 ```bash
 HONEYCOMB_API_KEY="your-api-key" OTEL_SERVICE_NAME="your-service-name" poetry run opentelemetry-instrument flask run
 ```
 
-You can configure exporter protocol with this flag:
-`OTEL_EXPORTER_OTLP_PROTOCOL=grpc` or `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`
-
-If you make changes in the package's pyproject.toml you may need to run `poetry build` for the changes to take effect
+To enable metrics, you will need to set a metrics dataset:
+`HONEYCOMB_METRICS_DATASET=otel-python-example-metrics`
 
-If you make changes in python files in src/honeycomb/opentelemetry, with this setup the changes should propagate to this example app upon save.
+You can configure exporter protocol with this flag:
+`OTEL_EXPORTER_OTLP_PROTOCOL=grpc` or `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

examples/hello-world-flask/app.py

@@ -20,9 +20,6 @@
 bee_counter = meter.create_counter("bee_counter")
 
 
-meter = metrics.get_meter("hello_world_flask_meter")
-bee_counter = meter.create_counter("bee_counter")
-
 @app.route("/")
 # Recommended: use attach and detach tokens for Context management with Baggage
 def hello_world():

examples/hello-world/README.md

@@ -1,6 +1,6 @@
 # hello-world
 
-This simple Python app returns "Hello World". This app uses the `configure_opentelemetry` method from `honeycomb.opentelemetry` to set up OpenTelemetry to export data to Honeycomb through configuration options set in the app's code. It is also possible to set configuration options through environment varaibles (see the [flask app](examples/hello-world-flask/README.md) as an example).
+This simple Python app returns "Hello World". This app uses the `configure_opentelemetry` method from `honeycomb.opentelemetry` to set up OpenTelemetry to export data to Honeycomb through configuration options set in the app's code. It is also possible to set configuration options through the `opentelemetry_instrument` command (see the [flask app](../hello-world-flask/README.md) as an example).
 
 ## Prerequisites
 
@@ -24,7 +24,8 @@ The app will output `Hello World` and then exit.
 
 ## Distro Instrumentation Example
 
-This app uses configuration in code instead of environment variables.
+This app uses configuration in code parameters rather than stricly commandline and environment variables. 
+You can also use environment variables as parameters like below:
 
 ```python
 configure_opentelemetry(
@@ -47,6 +48,3 @@ HONEYCOMB_API_KEY="your-api-key" poetry run python3 app.py
 You can configure exporter protocol with this flag:
 `OTEL_EXPORTER_OTLP_PROTOCOL=grpc` or `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`
 
-If you make changes in the package's pyproject.toml you may need to run `poetry build` for the changes to take effect.
-
-If you make changes in python files in src/honeycomb/opentelemetry, with this setup the changes should propagate to this example app upon save.

examples/hello-world/app.py

@@ -5,9 +5,11 @@
 
 configure_opentelemetry(
     HoneycombOptions(
-        debug=True, # prints exported traces & metrics to the console, useful for debugging and setting up
-        apikey=os.getenv("HONEYCOMB_API_KEY"), # Honeycomb API Key, required to send data to Honeycomb
-        service_name="otel-python-example", # Dataset that will be populated with data from this service in Honeycomb
+        debug=True,  # prints exported traces & metrics to the console, useful for debugging and setting up
+        # Honeycomb API Key, required to send data to Honeycomb
+        apikey=os.getenv("HONEYCOMB_API_KEY"),
+        # Dataset that will be populated with data from this service in Honeycomb
+        service_name="otel-python-example",
         # enable_local_visualizations=True, # Will print a link to a trace produced in Honeycomb to the console, useful for debugging
         # traces_apikey = None, Set a specific Honeycomb API key just for traces
         # metrics_apikey = None, Set a specific Honeycomb API key just for metrics
@@ -28,16 +30,12 @@
     )
 )
 
-# or use environment variables instead of configure_opentelemetry
-# export DEBUG=true
-# export HONEYCOMB_API_KEY=abc123
-# export OTEL_SERVICE_NAME=otel-python-example
-
 meter = metrics.get_meter("hello_world_meter")
 sheep = meter.create_counter('sheep')
 
 tracer = trace.get_tracer("hello_world_tracer")
 
+
 def hello_world():
     token = attach(baggage.set_baggage(
         "baggy", "important_value"))
@@ -52,4 +50,5 @@ def hello_world():
     sheep.add(1, {'app.route': '/'})
     return "Hello World"
 
+
 hello_world()