Initial revision of opencensus/trace/. (#2)

Author: g-easy

AUTHORS

@@ -1 +1 @@
-Google Inc.
+Google Inc.

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# How to Contribute
+
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines you need to follow.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution,
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.

README.md

@@ -1,8 +1,8 @@
 # OpenCensus - A stats collection and distributed tracing framework
 [![Gitter chat][gitter-image]][gitter-url]
 
-OpenCensus is a toolkit for collecting application performance and behavior data. It currently 
-includes 3 apis: stats, tracing and tags.
+OpenCensus is a toolkit for collecting application performance and behavior data. It currently
+includes an API for tracing.
 
 The library is in alpha stage and the API is subject to change.
 
@@ -11,3 +11,37 @@ project.
 
 [gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg
 [gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+
+This is not an officially supported Google product.
+
+## Quickstart
+
+Please refer to
+[`trace/examples/span_example.cc`](opencensus/trace/examples/span_example.cc)
+
+## Directory structure
+
+* [`opencensus/`](opencensus) prefix to get `#include` paths like `opencensus/trace/span.h`
+  * [`common/`](opencensus/common) - Provides common libraries and components for OpenCensus.
+  * [`doc/`](opencensus/doc) - Documentation for our APIs, coding style, etc.
+  * [`trace/`](opencensus/trace) - OpenCensus tracing API.
+
+## Language support
+
+* `libstdc++` is required.
+* C++11 is required.
+* [`absl`](https://github.com/abseil/abseil-cpp/) is used for its building blocks.
+* [`googletest`](https://github.com/google/googletest/) is used for tests.
+* [`benchmark`](https://github.com/google/benchmark/) is used for benchmarking.
+* We do not depend on:
+  * Boost
+  * Exception handling
+  * RTTI
+
+## Compiler support
+
+We are targeting the following compilers:
+
+* gcc 4.8.1
+* clang 3.4
+* MSVC 19

WORKSPACE

@@ -0,0 +1,61 @@
+# Copyright 2017, OpenCensus Authors
+#
+# 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.
+
+workspace(name = "io_opencensus_cpp")
+
+# We depend on Abseil.
+http_archive(
+    name = "com_google_absl",
+    strip_prefix = "abseil-cpp-master",
+    urls = ["https://github.com/abseil/abseil-cpp/archive/master.zip"],
+)
+
+# CCTZ (Time-zone framework). Used by absl.
+http_archive(
+    name = "com_googlesource_code_cctz",
+    strip_prefix = "cctz-master",
+    urls = ["https://github.com/google/cctz/archive/master.zip"],
+)
+
+# GoogleTest/GoogleMock framework.
+http_archive(
+    name = "com_google_googletest",
+    strip_prefix = "googletest-master",
+    urls = ["https://github.com/google/googletest/archive/master.zip"],
+)
+
+# Google Benchmark library.
+# Adapted from cctz's WORKSPACE.
+# Upstream support for bazel is tracked in
+#  - https://github.com/google/benchmark/pull/329
+#  - https://github.com/google/benchmark/issues/191
+new_http_archive(
+    name = "com_google_benchmark",
+    urls = ["https://github.com/google/benchmark/archive/master.zip"],
+    strip_prefix = "benchmark-master",
+    build_file_content =
+"""
+cc_library(
+    name = "benchmark",
+    srcs = glob([
+        "src/*.h",
+        "src/*.cc",
+    ]),
+    hdrs = glob(["include/benchmark/*.h"]),
+    copts = ["-DHAVE_POSIX_REGEX"],  # HAVE_STD_REGEX didn't work.
+    includes = ["include"],
+    visibility = ["//visibility:public"],
+)
+"""
+)

opencensus/common/internal/BUILD

@@ -0,0 +1,81 @@
+# OpenCensus C++ internal libraries.
+#
+# Copyright 2017, OpenCensus Authors
+#
+# 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.
+
+licenses(["notice"])  # Apache 2.0
+
+package(default_visibility = ["//opencensus:__subpackages__"])
+
+cc_library(
+    name = "random_lib",
+    srcs = ["random.cc"],
+    hdrs = ["random.h"],
+    deps = [
+        "@com_google_absl//absl/synchronization",
+        "@com_google_absl//absl/time",
+    ],
+)
+
+cc_library(
+    name = "stats_object",
+    hdrs = ["stats_object.h"],
+    deps = [
+        "@com_google_absl//absl/base:core_headers",
+        "@com_google_absl//absl/memory",
+        "@com_google_absl//absl/strings",
+        "@com_google_absl//absl/time",
+        "@com_google_absl//absl/types:span",
+    ],
+)
+
+cc_library(
+    name = "string_vector_hash",
+    hdrs = ["string_vector_hash.h"],
+)
+
+# Tests
+# ========================================================================= #
+
+cc_test(
+    name = "random_test",
+    srcs = ["random_test.cc"],
+    deps = [
+        ":random_lib",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_binary(
+    name = "random_benchmark",
+    testonly = 1,
+    srcs = ["random_benchmark.cc"],
+    linkopts = ["-pthread"],  # Required for absl/synchronization bits.
+    linkstatic = 1,
+    deps = [
+        ":random_lib",
+        "@com_google_benchmark//:benchmark",
+    ],
+)
+
+cc_test(
+    name = "stats_object_test",
+    srcs = ["stats_object_test.cc"],
+    deps = [
+        ":stats_object",
+        "@com_google_absl//absl/strings",
+        "@com_google_absl//absl/types:span",
+        "@com_google_googletest//:gtest_main",
+    ],
+)

opencensus/common/internal/random.cc

@@ -0,0 +1,59 @@
+// Copyright 2017, OpenCensus Authors
+//
+// 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.
+
+#include "opencensus/common/internal/random.h"
+
+#include <cstring>
+
+#include "absl/synchronization/mutex.h"
+
+namespace opencensus {
+namespace common {
+
+uint64_t Generator::Random64() {
+  absl::MutexLock l(&mu_);
+  return rng_();
+}
+
+Random* Random::GetRandom() {
+  static Random* global_random = new Random;
+  return global_random;
+}
+
+uint32_t Random::GenerateRandom32() { return gen_.Random64(); }
+
+uint64_t Random::GenerateRandom64() { return gen_.Random64(); }
+
+float Random::GenerateRandomFloat() {
+  return static_cast<float>(gen_.Random64()) / static_cast<float>(UINT64_MAX);
+}
+
+double Random::GenerateRandomDouble() {
+  return static_cast<double>(gen_.Random64()) / static_cast<double>(UINT64_MAX);
+}
+
+void Random::GenerateRandomBuffer(uint8_t* buf, size_t buf_size) {
+  absl::MutexLock l(&gen_.mu_);
+  for (size_t i = 0; i < buf_size; i += sizeof(uint64_t)) {
+    uint64_t value = gen_.rng_();
+    if (i + sizeof(uint64_t) <= buf_size) {
+      memcpy(&buf[i], &value, sizeof(uint64_t));
+    } else {
+      memcpy(&buf[i], &value, buf_size - i);
+    }
+  }
+}
+
+}  // namespace common
+}  // namespace opencensus

opencensus/common/internal/random.h

@@ -0,0 +1,78 @@
+// Copyright 2017, OpenCensus Authors
+//
+// 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.
+
+#ifndef OPENCENSUS_COMMON_INTERNAL_RANDOM_H_
+#define OPENCENSUS_COMMON_INTERNAL_RANDOM_H_
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <random>
+#include <vector>
+
+#include "absl/synchronization/mutex.h"
+#include "absl/time/clock.h"
+
+namespace opencensus {
+namespace common {
+
+class Generator {
+ public:
+  Generator() : rng_(absl::GetCurrentTimeNanos()) {}
+  explicit Generator(uint64_t seed) : rng_(seed) {}
+
+  uint64_t Random64() LOCKS_EXCLUDED(mu_);
+
+ private:
+  friend class Random;
+
+  absl::Mutex mu_;
+  std::mt19937_64 rng_ GUARDED_BY(mu_);
+};
+
+class Random {
+ public:
+  // Initializes and returns a singleton Random generator.
+  static Random* GetRandom();
+
+  // Generating functions.
+  // Generates a random uint32_t
+  uint32_t GenerateRandom32();
+  // Generates a random uint64_t
+  uint64_t GenerateRandom64();
+  // Generates a random float between [0.0, 1.0]
+  float GenerateRandomFloat();
+  // Generates a random double between [0.0, 1.0]
+  double GenerateRandomDouble();
+  // Fills the given buffer with uniformly random bits.
+  void GenerateRandomBuffer(uint8_t* buf, size_t buf_size);
+
+ private:
+  friend class RandomTest;
+
+  Random() = default;
+
+  Random(const Random&) = delete;
+  Random(Random&&) = delete;
+  Random& operator=(const Random&) = delete;
+  Random& operator=(Random&&) = delete;
+
+  uint64_t GenerateValue();
+  Generator gen_;
+};
+
+}  // namespace common
+}  // namespace opencensus
+
+#endif  // OPENCENSUS_COMMON_INTERNAL_RANDOM_H_

opencensus/common/internal/random_benchmark.cc

@@ -0,0 +1,35 @@
+// Copyright 2017, OpenCensus Authors
+//
+// 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.
+
+#include "benchmark/benchmark.h"
+#include "opencensus/common/internal/random.h"
+
+namespace {
+
+void BM_GetRandom(benchmark::State& state) {
+  while (state.KeepRunning()) {
+    ::opencensus::common::Random::GetRandom();
+  }
+}
+BENCHMARK(BM_GetRandom);
+
+void BM_Random64(benchmark::State& state) {
+  while (state.KeepRunning()) {
+    ::opencensus::common::Random::GetRandom()->GenerateRandom64();
+  }
+}
+BENCHMARK(BM_Random64);
+
+}  // namespace
+BENCHMARK_MAIN()