ext/cloudtrace: added more Cloud Trace troubleshooting tips (open-telemetry#827)

Andrew Xue · sjbrunst · c24t · web-flow · commit fe4f3418621e · 2020-06-16T13:39:35.000-07:00
Co-authored-by: Shawn Brunsting &lt;brunsting@google.com&gt;
Co-authored-by: Chris Kleinknecht &lt;libc@google.com&gt;
diff --git a/docs/examples/cloud_monitoring/README.rst b/docs/examples/cloud_monitoring/README.rst
@@ -22,9 +22,9 @@ To use this exporter you first need to:
 
 * Run example
 
-.. code-block:: sh
-
-    python basic_metrics.py
+.. literalinclude:: basic_metrics.py
+    :language: python
+    :lines: 1-
 
 Viewing Output
 --------------------------
diff --git a/docs/examples/cloud_trace_exporter/README.rst b/docs/examples/cloud_trace_exporter/README.rst
@@ -8,9 +8,10 @@ Basic Example
 -------------
 
 To use this exporter you first need to:
-    * A Google Cloud project. You can `create one here. <https://console.cloud.google.com/projectcreate>`_
-    * Enable Cloud Trace API (aka Stackdriver Trace API) in the project `here. <https://console.cloud.google.com/apis/library?q=cloud_trace>`_
-    * Enable `Default Application Credentials. <https://developers.google.com/identity/protocols/application-default-credentials>`_
+    * A Google Cloud project. You can `create one here <https://console.cloud.google.com/projectcreate>`_.
+    * Enable Cloud Trace API (listed in the Cloud Console as Stackdriver Trace API) in the project `here <https://console.cloud.google.com/apis/library?q=cloud%20trace&filter=visibility:public>`_.
+      * If the page says "API Enabled" then you're done! No need to do anything.
+    * Enable Default Application Credentials by creating setting `GOOGLE_APPLICATION_CREDENTIALS <https://cloud.google.com/docs/authentication/getting-started>`_ or by `installing gcloud sdk <https://cloud.google.com/sdk/install>`_ and calling ``gcloud auth application-default login``.
 
 * Installation
 
@@ -20,12 +21,11 @@ To use this exporter you first need to:
     pip install opentelemetry-sdk
     pip install opentelemetry-exporter-cloud-trace
 
-* Run example locally
+* Run an example locally
 
-.. code-block:: sh
-
-    cd opentelemetry-python/docs/examples/cloud_trace_exporter
-    python basic_trace.py
+.. literalinclude:: basic_trace.py
+    :language: python
+    :lines: 1-
 
 Checking Output
 --------------------------
@@ -47,4 +47,33 @@ Running basic_trace.py hangs:
 
 Getting error ``google.api_core.exceptions.ResourceExhausted: 429 Resource has been exhausted``:
 ################################################################################################
-    * Check that you've enabled the `Cloud Trace (Stackdriver Trace) API <https://console.cloud.google.com/apis/library?q=cloud_trace>`_
+    * Check that you've enabled the `Cloud Trace (Stackdriver Trace) API <https://console.cloud.google.com/apis/library?q=cloud%20trace&filter=visibility:public>`_
+
+bash: pip: command not found:
+#############################
+    * `Install pip <https://cloud.google.com/python/setup#installing_python>`_
+    * If your machine uses python2 by default, pip will also be the python2 version. Try using ``pip3`` instead of ``pip``.
+
+pip install is hanging
+######################
+Try upgrading pip
+
+.. code-block:: sh
+
+    pip install --upgrade pip
+
+``pip install grcpio`` has been known to hang when you aren't using an upgraded version.
+
+ImportError: No module named opentelemetry
+##########################################
+Make sure you are using python3. If
+
+.. code-block:: sh
+
+    python --version
+
+returns ``Python 2.X.X`` try calling
+
+.. code-block:: sh
+
+    python3 basic_trace.py
