Initial stats implementation. (#8)

README.md

@@ -3,7 +3,7 @@
 [![Build Status][travis-image]][travis-url]
 
 OpenCensus is a toolkit for collecting application performance and behavior data. It currently
-includes an API for tracing.
+includes an API for tracing and stats.
 
 This library is currently in alpha: the API is in the process of being
 finalized; much of the implementation will be replaced with a more optimized
@@ -18,12 +18,16 @@ This is not an officially supported Google product.
 
 Please refer to
 [`trace/examples/span_example.cc`](opencensus/trace/examples/span_example.cc)
+for tracing and
+[`stats/examples/view_and_recording_example.cc`](opencensus/stats/examples/view_and_recording_example.cc)
+for stats.
 
 ## 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.
+  * [`stats/`](opencensus/stats) - OpenCensus stats API.
   * [`trace/`](opencensus/trace) - OpenCensus tracing API.
 
 ## Language support

opencensus/stats/BUILD

@@ -0,0 +1,179 @@
+# OpenCensus C++ Stats library.
+#
+# 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 License 2.0
+
+package(default_visibility = ["//visibility:private"])
+
+# The public stats API.
+cc_library(
+    name = "stats",
+    hdrs = ["stats.h"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":core",
+        ":export",
+        ":recording",
+    ],
+)
+
+cc_library(
+    name = "core",
+    srcs = [
+        "internal/aggregation.cc",
+        "internal/aggregation_window.cc",
+        "internal/bucket_boundaries.cc",
+        "internal/distribution.cc",
+        "internal/measure.cc",
+        "internal/measure_descriptor.cc",
+        "internal/measure_registry.cc",
+        "internal/measure_registry_impl.cc",
+        "internal/stats_manager.cc",
+        "internal/view_data.cc",
+        "internal/view_data_impl.cc",
+        "internal/view_descriptor.cc",
+    ],
+    hdrs = [
+        "aggregation.h",
+        "aggregation_window.h",
+        "bucket_boundaries.h",
+        "distribution.h",
+        "internal/measure_registry_impl.h",
+        "internal/stats_manager.h",
+        "internal/view_data_impl.h",
+        "measure.h",
+        "measure_descriptor.h",
+        "measure_registry.h",
+        "view_data.h",
+        "view_descriptor.h",
+    ],
+    deps = [
+        "@com_google_absl//absl/base:core_headers",
+        "@com_google_absl//absl/memory",
+        "@com_google_absl//absl/strings",
+        "@com_google_absl//absl/synchronization",
+        "@com_google_absl//absl/time",
+        "@com_google_absl//absl/types:optional",
+        "@com_google_absl//absl/types:span",
+        "//opencensus/common/internal:stats_object",
+        "//opencensus/common/internal:string_vector_hash",
+    ],
+)
+
+cc_library(
+    name = "recording",
+    srcs = ["internal/recording.cc"],
+    hdrs = ["recording.h"],
+    deps = [
+        ":core",
+        "@com_google_absl//absl/strings",
+    ],
+)
+
+cc_library(
+    name = "export",
+    srcs = [
+        "internal/stats_exporter.cc",
+        "internal/view.cc",
+    ],
+    hdrs = [
+        "stats_exporter.h",
+        "view.h",
+    ],
+    deps = [
+        ":core",
+        "@com_google_absl//absl/base:core_headers",
+        "@com_google_absl//absl/memory",
+        "@com_google_absl//absl/strings",
+        "@com_google_absl//absl/synchronization",
+        "@com_google_absl//absl/time",
+    ],
+)
+
+# Tests
+# ========================================================================= #
+
+cc_test(
+    name = "debug_string_test",
+    srcs = ["internal/debug_string_test.cc"],
+    deps = [
+        ":core",
+        "@com_google_absl//absl/time",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "distribution_test",
+    srcs = ["internal/distribution_test.cc"],
+    deps = [
+        ":core",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "bucket_boundaries_test",
+    srcs = ["internal/bucket_boundaries_test.cc"],
+    deps = [
+        ":core",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "measure_registry_test",
+    srcs = ["internal/measure_registry_test.cc"],
+    deps = [
+        ":core",
+        "@com_google_absl//absl/strings",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "stats_exporter_test",
+    srcs = ["internal/stats_exporter_test.cc"],
+    deps = [
+        ":core",
+        ":export",
+        "@com_google_absl//absl/memory",
+        "@com_google_absl//absl/time",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "stats_manager_test",
+    srcs = ["internal/stats_manager_test.cc"],
+    deps = [
+        ":core",
+        ":export",
+        ":recording",
+        "@com_google_absl//absl/types:optional",
+        "@com_google_googletest//:gtest_main",
+    ],
+)
+
+cc_test(
+    name = "view_data_impl_test",
+    srcs = ["internal/view_data_impl_test.cc"],
+    deps = [
+        ":core",
+        "@com_google_absl//absl/time",
+        "@com_google_googletest//:gtest_main",
+    ],
+)

opencensus/stats/aggregation.h

@@ -0,0 +1,79 @@
+// 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_STATS_AGGREGATION_H_
+#define OPENCENSUS_STATS_AGGREGATION_H_
+
+#include <string>
+#include <utility>
+
+#include "opencensus/stats/bucket_boundaries.h"
+
+namespace opencensus {
+namespace stats {
+
+// Aggregation defines how to aggregate data for each view. See the static
+// constructors for details of the various options.
+// Aggregation is immutable.
+class Aggregation final {
+ public:
+  // Count aggregation counts the number of records, ignoring their individual
+  // values.
+  static Aggregation Count() {
+    return Aggregation(Type::kCount, BucketBoundaries::Explicit({}));
+  }
+
+  // Sum aggregation sums all records.
+  static Aggregation Sum() {
+    return Aggregation(Type::kSum, BucketBoundaries::Explicit({}));
+  }
+
+  // Distribution aggregation records the number of records in each bucket
+  // defined by 'buckets', and calculates distribution stats from that.
+  static Aggregation Distribution(BucketBoundaries buckets) {
+    return Aggregation(Type::kDistribution, std::move(buckets));
+  }
+
+  enum class Type {
+    kCount,
+    kSum,
+    kDistribution,
+  };
+
+  Type type() const { return type_; }
+  const BucketBoundaries& bucket_boundaries() const {
+    return bucket_boundaries_;
+  }
+
+  std::string DebugString() const;
+
+  bool operator==(const Aggregation& other) const {
+    return type_ == other.type_ &&
+           bucket_boundaries_ == other.bucket_boundaries_;
+  }
+  bool operator!=(const Aggregation& other) const { return !(*this == other); }
+
+ private:
+  Aggregation(Type type, BucketBoundaries buckets)
+      : type_(type), bucket_boundaries_(std::move(buckets)) {}
+
+  Type type_;
+  // Ignored except if type_ == kDistribution.
+  BucketBoundaries bucket_boundaries_;
+};
+
+}  // namespace stats
+}  // namespace opencensus
+
+#endif  // OPENCENSUS_STATS_AGGREGATION_H_

opencensus/stats/aggregation_window.h

@@ -0,0 +1,71 @@
+// 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_STATS_AGGREGATION_WINDOW_H_
+#define OPENCENSUS_STATS_AGGREGATION_WINDOW_H_
+
+#include <string>
+
+#include "absl/time/time.h"
+
+namespace opencensus {
+namespace stats {
+
+// AggregationWindow defines the time range over which recorded data is
+// aggregated for each view.
+// AggregationWindow is immutable.
+class AggregationWindow final {
+ public:
+  // Cumulative aggregation accumulates data over the lifetime of the process.
+  static AggregationWindow Cumulative() {
+    return AggregationWindow(Type::kCumulative, absl::InfiniteDuration());
+  }
+
+  // Interval aggregation keeps a rolling total of usage over the previous
+  // 'interval' of time.
+  static AggregationWindow Interval(absl::Duration interval) {
+    return AggregationWindow(Type::kInterval, interval);
+  }
+
+  enum class Type {
+    kCumulative,
+    kInterval,
+  };
+
+  Type type() const { return type_; }
+  absl::Duration duration() const { return duration_; }
+
+  std::string DebugString() const;
+
+  bool operator==(const AggregationWindow& other) const {
+    return type_ == other.type_ && duration_ == other.duration_;
+  }
+  bool operator!=(const AggregationWindow& other) const {
+    return !(*this == other);
+  }
+
+ private:
+  AggregationWindow(Type type, absl::Duration duration)
+      : type_(type), duration_(duration) {}
+
+  Type type_;
+  // Should always be InfiniteDuration if type_ == kCumulative, to simplify
+  // equality checking.
+  absl::Duration duration_;
+};
+
+}  // namespace stats
+}  // namespace opencensus
+
+#endif  // OPENCENSUS_STATS_AGGREGATION_WINDOW_H_