update README plus test

README.rst

@@ -108,6 +108,59 @@ Windows
     .\<your-env>\Scripts\activate
     pip install google-cloud-storage
 
+
+Tracing With OpenTelemetry
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library uses `OpenTelemetry`_ to generate traces on calls to Google Cloud Storage.
+For information on the benefits and utility of tracing, read the `Cloud Trace Overview <https://cloud.google.com/trace/docs/overview>`_.
+
+To enable OpenTelemetry tracing in the Cloud Storage client, first install OpenTelemetry:
+
+.. code-block:: console
+
+    pip install google-cloud-storage[tracing]
+
+Set the ``ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES`` environment variable to selectively opt-in tracing for the Cloud Storage client:
+
+.. code-block:: console
+
+    export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
+
+You will also need to tell OpenTelemetry which exporter to use. An example to export traces to Google Cloud Trace can be found below.
+
+.. code-block:: console
+
+    # Install the Google Cloud Trace exporter and propagator, however you can use any exporter of your choice.
+    pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
+
+    # [Optional] Install the OpenTelemetry Requests Instrumentation to trace the underlying HTTP requests.
+    pip install opentelemetry-instrumentation-requests
+
+.. code-block:: python
+
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+
+    tracer_provider = TracerProvider()
+    tracer_provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
+    trace.set_tracer_provider(TracerProvider())
+
+    # Optional yet recommended to instrument the requests HTTP library
+    from opentelemetry.instrumentation.requests import RequestsInstrumentor
+    RequestsInstrumentor().instrument(tracer_provider=tracer_provider)
+
+In this example, tracing data will be published to the `Google Cloud Trace`_ console.
+Tracing is most effective when many libraries are instrumented to provide insight over the entire lifespan of a request.
+For a list of libraries that can be instrumented, refer to the `OpenTelemetry Registry`_.
+
+.. _OpenTelemetry: https://opentelemetry.io
+.. _OpenTelemetry Registry: https://opentelemetry.io/ecosystem/registry
+.. _Google Cloud Trace: https://cloud.google.com/trace
+
+
 Next Steps
 ~~~~~~~~~~
 

tests/unit/test__opentelemetry_tracing.py

@@ -204,19 +204,20 @@ def test_set_conditional_retry_attr(setup, setup_optin):
 def test_set_api_request_attr():
     from google.cloud.storage import Client
 
-    api_request = {
-        "method": "GET",
-        "path": "/foo/bar/baz",
-        "timeout": (100, 100),
-    }
+    test_client = Client()
+    args_method = {"method": "GET"}
+    expected_attributes = {"http.request.method": "GET"}
+    attr = _opentelemetry_tracing._set_api_request_attr(args_method, test_client)
+    assert attr == expected_attributes
+
+    args_path = {"path": "/foo/bar/baz"}
+    expected_attributes = {"url.full": "https://storage.googleapis.com/foo/bar/baz"}
+    attr = _opentelemetry_tracing._set_api_request_attr(args_path, test_client)
+    assert attr == expected_attributes
 
+    args_timeout = {"timeout": (100, 100)}
     expected_attributes = {
-        "http.request.method": "GET",
-        "url.full": "https://storage.googleapis.com/foo/bar/baz",
         "connect_timeout,read_timeout": (100, 100),
     }
-    test_client = Client()
-    api_reqest_attributes = _opentelemetry_tracing._set_api_request_attr(
-        api_request, test_client
-    )
-    assert api_reqest_attributes == expected_attributes
+    attr = _opentelemetry_tracing._set_api_request_attr(args_timeout, test_client)
+    assert attr == expected_attributes