Add Trace code samples (GoogleCloudPlatform#1941)

* Skeletal trace example

* Initial sample code

* Completed sample

* Simple way to run the server

* New library version available

.kokoro/presubmit_tests_trace.cfg

@@ -0,0 +1,15 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Download secrets from Cloud Storage.
+gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/python-docs-samples"
+
+# Tell the trampoline which build file to use.
+env_vars: {
+    key: "TRAMPOLINE_BUILD_FILE"
+    value: "github/python-docs-samples/.kokoro/system_tests.sh"
+}
+
+env_vars: {
+    key: "NOX_SESSION"
+    value: "trace and py36 and not appengine"
+}

.kokoro/system_tests_trace.cfg

@@ -0,0 +1,15 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Download secrets from Cloud Storage.
+gfile_resources: "/bigstore/cloud-devrel-kokoro-resources/python-docs-samples"
+
+# Tell the trampoline which build file to use.
+env_vars: {
+    key: "TRAMPOLINE_BUILD_FILE"
+    value: "github/python-docs-samples/.kokoro/system_tests.sh"
+}
+
+env_vars: {
+    key: "NOX_SESSION"
+    value: "trace and py36 and not appengine"
+}

trace/README.rst

@@ -0,0 +1,97 @@
+.. This file is automatically generated. Do not edit this file directly.
+
+Stackdriver Trace Python Samples
+===============================================================================
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=trace/README.rst
+
+
+This directory contains samples for Stackdriver Trace. `Stackdriver Trace`_ collects latency data from applications and displays it in near real time in the Google Cloud Platform Console.
+
+
+
+
+.. _Stackdriver Trace: https://cloud.google.com/trace/docs
+
+Setup
+-------------------------------------------------------------------------------
+
+
+Authentication
+++++++++++++++
+
+This sample requires you to have authentication setup. Refer to the
+`Authentication Getting Started Guide`_ for instructions on setting up
+credentials for applications.
+
+.. _Authentication Getting Started Guide:
+    https://cloud.google.com/docs/authentication/getting-started
+
+Install Dependencies
+++++++++++++++++++++
+
+#. Clone python-docs-samples and change directory to the sample directory you want to use.
+
+    .. code-block:: bash
+
+        $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
+
+#. Install `pip`_ and `virtualenv`_ if you do not already have them. You may want to refer to the `Python Development Environment Setup Guide`_ for Google Cloud Platform for instructions.
+
+   .. _Python Development Environment Setup Guide:
+       https://cloud.google.com/python/setup
+
+#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.
+
+    .. code-block:: bash
+
+        $ virtualenv env
+        $ source env/bin/activate
+
+#. Install the dependencies needed to run the samples.
+
+    .. code-block:: bash
+
+        $ pip install -r requirements.txt
+
+.. _pip: https://pip.pypa.io/
+.. _virtualenv: https://virtualenv.pypa.io/
+
+Samples
+-------------------------------------------------------------------------------
+
+Web Server
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. image:: https://gstatic.com/cloudssh/images/open-btn.png
+   :target: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=trace/main.py,trace/README.rst
+
+
+
+
+To run this sample:
+
+.. code-block:: bash
+
+    $ python main.py
+
+
+
+
+The client library
+-------------------------------------------------------------------------------
+
+This sample uses the `Google Cloud Client Library for Python`_.
+You can read the documentation for more details on API usage and use GitHub
+to `browse the source`_ and  `report issues`_.
+
+.. _Google Cloud Client Library for Python:
+    https://googlecloudplatform.github.io/google-cloud-python/
+.. _browse the source:
+    https://github.com/GoogleCloudPlatform/google-cloud-python
+.. _report issues:
+    https://github.com/GoogleCloudPlatform/google-cloud-python/issues
+
+
+.. _Google Cloud SDK: https://cloud.google.com/sdk/

trace/README.rst.in

@@ -0,0 +1,21 @@
+# This file is used to generate README.rst
+
+product:
+  name: Stackdriver Trace
+  short_name: Stackdriver Trace
+  url: https://cloud.google.com/trace/docs
+  description: > 
+    `Stackdriver Trace`_ collects latency data from applications and displays
+    it in near real time in the Google Cloud Platform Console.
+
+setup:
+- auth
+- install_deps
+
+samples:
+- name: Web Server
+  file: main.py
+
+cloud_client_library: true
+
+folder: trace

trace/main.py

@@ -0,0 +1,51 @@
+# Copyright 2018 Google LLC
+#
+# 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 random
+import time
+
+from flask import Flask, redirect, url_for
+
+# [START trace-setup-python-configure]
+from opencensus.trace.exporters import stackdriver_exporter
+import opencensus.trace.tracer
+
+exporter = stackdriver_exporter.StackdriverExporter()
+tracer = opencensus.trace.tracer.Tracer(exporter=exporter)
+# [END trace-setup-python-configure]
+
+app = Flask(__name__)
+
+
+@app.route('/', methods=['GET'])
+def root():
+    return redirect(url_for('index'))
+
+
+# [START trace_setup_python_quickstart]
+@app.route('/index.html', methods=['GET'])
+def index():
+    tracer.start_span(name='index')
+
+    # Add up to 1 sec delay, weighted toward zero
+    time.sleep(random.random() ** 2)
+    result = "Tracing requests"
+
+    tracer.end_span()
+    return result
+# [END trace_setup_python_quickstart]
+
+
+if __name__ == '__main__':
+    app.run()

trace/main_test.py

@@ -0,0 +1,33 @@
+# Copyright 2018 Google LLC
+#
+# 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 main
+
+
+def test_index():
+    main.app.testing = True
+    client = main.app.test_client()
+
+    resp = client.get('/index.html')
+    assert resp.status_code == 200
+    assert 'Tracing requests' in resp.data.decode('utf-8')
+
+
+def test_redirect():
+    main.app.testing = True
+    client = main.app.test_client()
+
+    resp = client.get('/')
+    assert resp.status_code == 302
+    assert '/index.html' in resp.headers.get('location', '')

trace/requirements.txt

@@ -0,0 +1,3 @@
+google-cloud-trace==0.20.2
+opencensus==0.1.10
+Flask==1.0.2