samples: add OTel Tracing quickstart (#1371)

* samples: add otel tracing quickstart

* update test

* fix lint

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

* review comments

* align samples to use ALWAYS_ON

* address comments

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
Co-authored-by: Frank Natividad <[email protected]>

Author: 3 people

samples/snippets/requirements.txt

@@ -3,3 +3,6 @@ google-cloud-storage==2.19.0
 pandas===1.3.5; python_version == '3.7'
 pandas===2.0.3; python_version == '3.8'
 pandas==2.2.3; python_version >= '3.9'
+opentelemetry-exporter-gcp-trace
+opentelemetry-propagator-gcp
+opentelemetry-instrumentation-requests

samples/snippets/snippets_test.py

@@ -75,6 +75,7 @@
 import storage_set_client_endpoint
 import storage_set_object_retention_policy
 import storage_set_metadata
+import storage_trace_quickstart
 import storage_transfer_manager_download_bucket
 import storage_transfer_manager_download_chunks_concurrently
 import storage_transfer_manager_download_many
@@ -850,3 +851,15 @@ def test_create_bucket_hierarchical_namespace(test_bucket_create, capsys):
     )
     out, _ = capsys.readouterr()
     assert f"Created bucket {test_bucket_create.name} with hierarchical namespace enabled" in out
+
+
+def test_storage_trace_quickstart(test_bucket, capsys):
+    blob_name = f"trace_quickstart_{uuid.uuid4().hex}"
+    contents = "The quick brown fox jumps over the lazy dog."
+    storage_trace_quickstart.run_quickstart(test_bucket.name, blob_name, contents)
+    out, _ = capsys.readouterr()
+
+    assert f"{blob_name} uploaded to {test_bucket.name}" in out
+    assert (
+        f"Downloaded storage object {blob_name} from bucket {test_bucket.name}" in out
+    )

samples/snippets/storage_trace_quickstart.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+
+# Copyright 2024 Google LLC. All Rights Reserved.
+#
+# 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 sys
+
+"""
+Sample that exports OpenTelemetry Traces collected from the Storage client to Cloud Trace.
+"""
+
+
+def run_quickstart(bucket_name, blob_name, data):
+    # [START storage_enable_otel_tracing]
+
+    from opentelemetry import trace
+    from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
+    from opentelemetry.resourcedetector.gcp_resource_detector import (
+        GoogleCloudResourceDetector,
+    )
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    from opentelemetry.sdk.trace.sampling import ALWAYS_ON
+    # Optional: Enable traces emitted from the requests HTTP library.
+    from opentelemetry.instrumentation.requests import RequestsInstrumentor
+
+    from google.cloud import storage
+
+    # The ID of your GCS bucket
+    # bucket_name = "your-bucket-name"
+    # The ID of your GCS object
+    # blob_name = "your-object-name"
+    # The contents to upload to the file
+    # data = "The quick brown fox jumps over the lazy dog."
+
+    # In this sample, we use Google Cloud Trace to export the OpenTelemetry
+    # traces: https://cloud.google.com/trace/docs/setup/python-ot
+    # Choose and configure the exporter for your environment.
+
+    tracer_provider = TracerProvider(
+        # Sampling is set to ALWAYS_ON.
+        # It is recommended to sample based on a ratio to control trace ingestion volume,
+        # for instance, sampler=TraceIdRatioBased(0.2)
+        sampler=ALWAYS_ON,
+        resource=GoogleCloudResourceDetector().detect(),
+    )
+
+    # Export to Google Cloud Trace.
+    tracer_provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
+    trace.set_tracer_provider(tracer_provider)
+
+    # Optional: Enable traces emitted from the requests HTTP library.
+    RequestsInstrumentor().instrument(tracer_provider=tracer_provider)
+
+    # Get the tracer and create a new root span.
+    tracer = tracer_provider.get_tracer("My App")
+    with tracer.start_as_current_span("trace-quickstart"):
+        # Instantiate a storage client and perform a write and read workload.
+        storage_client = storage.Client()
+        bucket = storage_client.bucket(bucket_name)
+        blob = bucket.blob(blob_name)
+        blob.upload_from_string(data)
+        print(f"{blob_name} uploaded to {bucket_name}.")
+
+        blob.download_as_bytes()
+        print("Downloaded storage object {} from bucket {}.".format(blob_name, bucket_name))
+
+    # [END storage_enable_otel_tracing]
+
+
+if __name__ == "__main__":
+    run_quickstart(bucket_name=sys.argv[1], blob_name=sys.argv[2], data=sys.argv[3])