Implement trace, trace_span, span_context and reporters

trace/.coveragerc

@@ -0,0 +1,11 @@
+[run]
+branch = True
+
+[report]
+fail_under = 100
+show_missing = True
+exclude_lines =
+    # Re-enable the standard pragma
+    pragma: NO COVER
+    # Ignore debug-only repr
+    def __repr__

trace/README.rst

@@ -0,0 +1,12 @@
+OpenCensus - A stats collection and distributed tracing framework
+=================================================================
+
+OpenCensus provides a framework to define and collect stats against metrics and
+to break those stats down across user-defined dimensions. The library is in
+pre-alpha stage and the API is subject to change.
+
+
+Disclaimer
+----------
+
+This is not an official Google product.

trace/nox.py

@@ -0,0 +1,76 @@
+# Copyright 2016 Google Inc.
+#
+# 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.
+
+from __future__ import absolute_import
+
+import nox
+
+
+@nox.session
+@nox.parametrize('python_version', ['2.7', '3.4', '3.5', '3.6'])
+def unit_tests(session, python_version):
+    """Run the unit test suite."""
+
+    # Run unit tests against all supported versions of Python.
+    session.interpreter = 'python{}'.format(python_version)
+
+    # Install all test dependencies, then install this package in-place.
+    session.install('mock', 'pytest', 'pytest-cov', 'google-cloud-core')
+    session.install('-e', '.')
+
+    # Run py.test against the unit tests.
+    session.run(
+        'py.test',
+        '--quiet',
+        '--cov=opencensus.trace',
+        '--cov-append',
+        '--cov-config=.coveragerc',
+        '--cov-report=',
+        '--cov-fail-under=97',
+        'tests/',
+        *session.posargs
+    )
+
+
+@nox.session
+def lint(session):
+    """Run flake8.
+    Returns a failure if flake8 finds linting errors or sufficiently
+    serious code quality issues.
+    """
+    session.interpreter = 'python3.6'
+    session.install('flake8')
+    session.install('.')
+    session.run('flake8', 'opencensus/trace')
+
+
+@nox.session
+def lint_setup_py(session):
+    """Verify that setup.py is valid (including RST check)."""
+    session.interpreter = 'python3.6'
+    session.install('docutils', 'pygments')
+    session.run(
+        'python', 'setup.py', 'check', '--restructuredtext', '--strict')
+
+
+@nox.session
+def cover(session):
+    """Run the final coverage report.
+    This outputs the coverage report aggregating coverage from the unit
+    test runs (not system test runs), and then erases coverage data.
+    """
+    session.interpreter = 'python3.6'
+    session.install('coverage', 'pytest-cov')
+    session.run('coverage', 'report', '--show-missing', '--fail-under=100')
+    session.run('coverage', 'erase')

trace/opencensus/__init__.py

@@ -0,0 +1,20 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+try:
+    import pkg_resources
+    pkg_resources.declare_namespace(__name__)
+except ImportError:
+    import pkgutil
+    __path__ = pkgutil.extend_path(__path__, __name__)

trace/opencensus/trace/__init__.py

@@ -0,0 +1,19 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+from opencensus.trace.trace import Trace
+from opencensus.trace.trace_span import TraceSpan
+
+
+__all__ = ['Trace', 'TraceSpan']

trace/opencensus/trace/enums.py

@@ -0,0 +1,41 @@
+# Copyright 2016 Google Inc. 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.
+
+"""Wrappers for protocol buffer enum types.
+
+See
+https://cloud.google.com/trace/docs/reference/v1/rpc/google.devtools.
+cloudtrace.v1#google.devtools.cloudtrace.v1.ListTracesRequest.ViewType
+
+https://cloud.google.com/trace/docs/reference/v1/rpc/google.devtools.
+cloudtrace.v1#google.devtools.cloudtrace.v1.TraceSpan.SpanKind
+"""
+
+
+class Enum(object):
+    class SpanKind(object):
+        """
+        Type of span. Can be used to specify additional relationships between
+        spans in addition to a parent/child relationship.
+
+        Attributes:
+          SPAN_KIND_UNSPECIFIED (int): Unspecified.
+          RPC_SERVER (int): Indicates that the span covers server-side handling
+                            of an RPC or other remote network request.
+          RPC_CLIENT (int): Indicates that the span covers the client-side
+                            wrapper around an RPC or other remote request.
+        """
+        SPAN_KIND_UNSPECIFIED = 0
+        RPC_SERVER = 1
+        RPC_CLIENT = 2

trace/opencensus/trace/reporters/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2017 Google Inc.
+#
+# 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.

trace/opencensus/trace/reporters/file_reporter.py

@@ -0,0 +1,37 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Export the trace spans to a local file."""
+
+import json
+
+
+class FileReporter(object):
+    """
+    :type file_name: str
+    :param file_name: The name of the output file.
+    """
+
+    def __init__(self, file_name):
+        self.file_name = file_name
+
+    def report(self, traces):
+        """Report the traces by printing it out.
+
+        :type traces: dict
+        :param traces: Traces collected.
+        """
+        with open(self.file_name, 'w+') as file:
+            traces_str = json.dumps(traces)
+            file.write(traces_str)

trace/opencensus/trace/reporters/print_reporter.py

@@ -0,0 +1,29 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Export the trace spans by printing them out."""
+
+
+class PrintReporter(object):
+    def report(self, traces):
+        """Report the traces by printing it out.
+
+        :type traces: dict
+        :param traces: Traces collected.
+
+        :rtype: dict
+        :returns: Traces printed.
+        """
+        print(traces)
+        return traces