stats: export mutex contention data (#4750)

Signed-off-by: James Buckland <jbuckland@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 0287a6feb03e773ed8a15955536bb8285d0ae4a6

docs/BUILD

@@ -16,6 +16,7 @@ proto_library(
         "//envoy/admin/v2alpha:clusters",
         "//envoy/admin/v2alpha:config_dump",
         "//envoy/admin/v2alpha:memory",
+        "//envoy/admin/v2alpha:mutex_stats",
         "//envoy/admin/v2alpha:server_info",
         "//envoy/api/v2:cds",
         "//envoy/api/v2:discovery",

envoy/admin/v2alpha/BUILD

@@ -38,6 +38,12 @@ api_proto_library_internal(
     visibility = ["//visibility:public"],
 )
 
+api_proto_library_internal(
+    name = "mutex_stats",
+    srcs = ["mutex_stats.proto"],
+    visibility = ["//visibility:public"],
+)
+
 api_proto_library_internal(
     name = "certs",
     srcs = ["certs.proto"],

envoy/admin/v2alpha/mutex_stats.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package envoy.admin.v2alpha;
+
+// [#protodoc-title: MutexStats]
+
+// Proto representation of the statistics collected upon absl::Mutex contention, if Envoy is run
+// under :option:`--enable-mutex-tracing`. For more information, see the `absl::Mutex`
+// [docs](https://abseil.io/about/design/mutex#extra-features).
+//
+// *NB*: The wait cycles below are measured by `absl::base_internal::CycleClock`, and may not
+// correspond to core clock frequency. For more information, see the `CycleClock`
+// [docs](https://github.com/abseil/abseil-cpp/blob/master/absl/base/internal/cycleclock.h).
+message MutexStats {
+
+  // The number of individual mutex contentions which have occurred since startup.
+  uint64 num_contentions = 1;
+
+  // The length of the current contention wait cycle.
+  uint64 current_wait_cycles = 2;
+
+  // The lifetime total of all contention wait cycles.
+  uint64 lifetime_wait_cycles = 3;
+}