// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you 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.
// Date: 2014/09/22 11:57:43
#ifndef BVAR_VARIABLE_H
#define BVAR_VARIABLE_H
#include <ostream> // std::ostream
#include <initializer_list> // std::initializer_list
#include <string> // std::string
#include <vector> // std::vector
#include <memory> // std::shared_ptr
#include <utility> // std::declval
#include <gflags/gflags_declare.h>
#include "butil/macros.h" // DISALLOW_COPY_AND_ASSIGN
#include "butil/strings/string_piece.h" // butil::StringPiece
#include "butil/type_traits.h"
#include "bvar/detail/exposed_ref.h" // detail::ExposedRef
#ifdef BAIDU_INTERNAL
#include <boost/any.hpp>
#else
namespace boost {
class any;
}
#endif
namespace bvar {
DECLARE_bool(save_series);
#define COMMON_VARIABLE_CONSTRUCTOR(TypeName) \
TypeName() = default; \
TypeName(const butil::StringPiece& name) { \
this->expose(name); \
} \
TypeName(const butil::StringPiece& prefix, const butil::StringPiece& name) { \
this->expose_as(prefix, name); \
} \
// Bitwise masks of displayable targets
enum DisplayFilter {
DISPLAY_ON_HTML = 1,
DISPLAY_ON_PLAIN_TEXT = 2,
DISPLAY_ON_ALL = 3,
};
// Implement this class to write variables into different places.
class Dumper {
public:
virtual ~Dumper() = default;
// Dump one variable under its exposed `name`. `description` is produced by
// Variable::describe(). Returning false stops Variable::dump_exposed(),
// which then returns -1.
virtual bool dump(const std::string& name,
const butil::StringPiece& description) = 0;
// Dump one metric of a variable that maps to several of them, namely a
// multiple dimension var or a Histogram. `name` already carries the labels
// if there're any, as in `foo_bucket{le="10"}`.
// Unlike dump(), implementations must NOT emit any per-metric preamble:
// the whole family is described by a single preceding dump_comment().
virtual bool dump_mvar(const std::string& /*name*/,
const butil::StringPiece& /*description*/) {
return true;
}
// Dump the comment describing the type of the metric family `name`, which
// precedes the dump_mvar() of all the metrics inside. Only meaningful to
// the prometheus service, ignored by default.
virtual bool dump_comment(const std::string&, const std::string& /*type*/) {
return true;
}
};
// One prometheus metric family exported by a composite metric, see the
// dump_samples() contract below.
struct MetricFamily {
// Appended to the name the metric is exposed under. Empty for the main
// family, as a Histogram has: it exports foo_bucket/foo_sum/foo_count,
// which are the series of the single family `foo`. A LatencyRecorder in
// contrast exports five families, "_latency", "_avg_latency" and so on.
const char* suffix;
// "gauge" / "counter" / "histogram" / "summary".
const char* type;
// Label names emitted by samples in this family. An enclosing
// MultiDimension must not use any of them, otherwise one sample would
// contain the same label more than once and be invalid prometheus text.
std::vector<std::string> reserved_labels;
};
// The contract of a composite metric inside a MultiDimension
//
// A type that maps to more than one prometheus metric (Histogram,
// LatencyRecorder, or one of your own) cannot be dumped as a MultiDimension
// value the default way, which writes describe() as a single number. Declare
// these two members on it instead and MultiDimension will pick them up:
//
// // The families this type exports, in the order they should be dumped.
// // Each family also declares the label names it emits, if any.
// // Return a reference to immutable storage with static lifetime.
// static const std::vector<bvar::MetricFamily>& list_metric_families();
//
// // Emit the samples of the family at `family_index` and nothing else: the
// // "# TYPE" line belongs to the whole family, so the caller writes it once
// // for all the label sets. `name' is the exposed name with the family's
// // suffix already appended. `labels` is the labels of the enclosing
// // MultiDimension as `k="v",k="v"` with no enclosing braces, empty when
// // there is no MultiDimension; merge it into the brace group of every
// // sample, before any label of your own:
// // foo_bucket{method="echo",le="10"} 3
// // Return false to stop, as Dumper::dump() does.
// bool dump_samples(bvar::Dumper* dumper, size_t family_index,
// const std::string& name,
// butil::StringPiece labels) const;
//
// Neither a base class nor a template specialization is involved: the members
// travel with the type, so they cannot go missing in a translation unit that
// forgot an include, which is exactly what would make a traits class dangerous
// here: the value would silently fall back to json.
namespace detail {
// A double as the prometheus text format spells it, used both for sample
// values and for the numbers inside a label such as `le` or `quantile`.
// Neither of the two obvious ways of writing one will do:
// - printf("%g") is locale dependent, and an application that called
// setlocale under a de_DE environment gets `quantile="0,99"`, where the
// comma ends the label and starts another one;
// - butil::DoubleToString is locale free but spells the non finite values
// "Infinity" and "NaN", while the sample value grammar only takes `+Inf`,
// `-Inf` and `NaN`, and a line it cannot parse is dropped from the scrape.
// It also leaves out the integer part, and `.5` reads worse than `0.5`
// next to the values the scalar path prints through an ostream.
std::string prometheus_double_to_string(double value);
// True if `T` declares both members of the contract above.
template <typename T>
class IsCompositeMetric {
template <typename U>
static auto probe(int) -> decltype(
U::list_metric_families(),
std::declval<const U&>().dump_samples(
(Dumper*)nullptr, (size_t)0, std::declval<const std::string&>(),
butil::StringPiece()),
butil::true_type());
template <typename>
static butil::false_type probe(...);
public:
// An enum rather than `static const bool`: the latter is odr-used as soon as
// it is bound to a reference, and C++14 would then ask for an out-of-class
// definition of it. An enumerator never does.
enum { value = decltype(probe<T>(0))::value };
};
} // namespace detail
// Options for Variable::dump_exposed().
struct DumpOptions {
// Constructed with default options.
DumpOptions();
// If this is true, string-type values will be quoted.
bool quote_string;
// The ? in wildcards. Wildcards in URL need to use another character
// because ? is reserved.
char question_mark;
// Dump variables with matched display_filter
DisplayFilter display_filter;
// Name matched by these wildcards (or exact names) are kept.
std::string white_wildcards;
// Name matched by these wildcards (or exact names) are skipped.
std::string black_wildcards;
};
struct SeriesOptions {
SeriesOptions() : fixed_length(true), test_only(false) {}
bool fixed_length; // useless now
bool test_only;
};
// Base class of all bvar.
//
// About thread-safety:
// bvar is thread-compatible:
// Namely you can create/destroy/expose/hide or do whatever you want to
// different bvar simultaneously in different threads.
// bvar is NOT thread-safe:
// You should not operate one bvar from different threads simultaneously.
// If you need to, protect the ops with locks. Similarly with ordinary
// variables, const methods are thread-safe, namely you can call
// describe()/get_description()/get_value() etc from diferent threads
// safely (provided that there's no non-const methods going on).
class Variable {
public:
using SharedExposedRef = detail::SharedExposedRef<Variable>;
Variable() = default;
// bvar uses TLS, thus copying/assignment need to copy TLS stuff as well,
// which is heavy. We disable copying/assignment now.
DISALLOW_COPY_AND_ASSIGN(Variable);
virtual ~Variable();
// Implement this method to print the variable into ostream.
virtual void describe(std::ostream&, bool quote_string) const = 0;
// string form of describe().
std::string get_description() const;
#ifdef BAIDU_INTERNAL
// Get value.
// If subclass does not override this method, the value is the description
// and the type is std::string.
virtual void get_value(boost::any* value) const;
#endif
// Describe saved series as a json-string into the stream.
// The output will be ploted by flot.js
// Returns 0 on success, 1 otherwise(this variable does not save series).
virtual int describe_series(std::ostream&, const SeriesOptions&) const
{ return 1; }
// Send this variable to `dumper` under the exposed name `name`.
// The default implementation sends describe() as a single metric, which is
// what almost every variable wants. Variables mapping to several metrics
// (Histogram maps to one metric per bucket plus `_sum` and `_count`) override
// this to drive `dumper' themselves: one dump_comment() describing the
// family followed by a dump_mvar() per metric.
// Returns false to stop dump_exposed(), as Dumper::dump() does.
virtual bool dump(Dumper* dumper, const DumpOptions& options,
const std::string& name) const;
// Expose this variable globally so that it's counted in following
// functions:
// list_exposed
// count_exposed
// describe_exposed
// find_exposed
// Return 0 on success, -1 otherwise.
int expose(const butil::StringPiece& name,
DisplayFilter display_filter = DISPLAY_ON_ALL) {
return expose_impl(butil::StringPiece(), name, display_filter);
}
// Expose this variable with a prefix.
// Example:
// namespace foo {
// namespace bar {
// class ApplePie {
// ApplePie() {
// // foo_bar_apple_pie_error
// _error.expose_as("foo_bar_apple_pie", "error");
// }
// private:
// bvar::Adder<int> _error;
// };
// } // foo
// } // bar
// Returns 0 on success, -1 otherwise.
int expose_as(const butil::StringPiece& prefix,
const butil::StringPiece& name,
DisplayFilter display_filter = DISPLAY_ON_ALL) {
return expose_impl(prefix, name, display_filter);
}
// Hide this variable so that it's not counted in *_exposed functions.
// Returns false if this variable is already hidden.
// CAUTION!! Subclasses must call hide() manually to avoid displaying
// a variable that is just destructing.
bool hide();
// Check if this variable is is_hidden.
bool is_hidden() const;
// Get exposed name. If this variable is not exposed, the name is empty.
const std::string& name() const { return _name; }
// ====================================================================
// Put names of all exposed variables into `names'.
// If you want to print all variables, you have to go through `names'
// and call `describe_exposed' on each name. This prevents an iteration
// from taking the lock too long.
static void list_exposed(std::vector<std::string>* names,
DisplayFilter = DISPLAY_ON_ALL);
// Get number of exposed variables.
static size_t count_exposed();
// Find an exposed variable by `name' and put its description into `os'.
// Returns 0 on found, -1 otherwise.
static int describe_exposed(const std::string& name,
std::ostream& os,
bool quote_string = false,
DisplayFilter = DISPLAY_ON_ALL);
// String form. Returns empty string when not found.
static std::string describe_exposed(const std::string& name,
bool quote_string = false,
DisplayFilter = DISPLAY_ON_ALL);
// Describe saved series of variable `name' as a json-string into `os'.
// The output will be ploted by flot.js
// Returns 0 on success, 1 when the variable does not save series, -1
// otherwise (no variable named so).
static int describe_series_exposed(const std::string& name,
std::ostream&,
const SeriesOptions&);
#ifdef BAIDU_INTERNAL
// Find an exposed variable by `name' and put its value into `value'.
// Returns 0 on found, -1 otherwise.
static int get_exposed(const std::string& name, boost::any* value);
#endif
// Find all exposed variables matching `white_wildcards' but
// `black_wildcards' and send them to `dumper'.
// Use default options when `options' is nullptr.
// Return number of dumped variables, -1 on error.
static int dump_exposed(Dumper* dumper, const DumpOptions* options);
protected:
virtual int expose_impl(const butil::StringPiece& prefix,
const butil::StringPiece& name,
DisplayFilter display_filter);
private:
std::string _name;
// Shared indirection handle for calling describe() outside the VarMap lock.
SharedExposedRef _ref;
};
// Make name only use lowercased alphabets / digits / underscores, and append
// the result to `out'.
// Examples:
// foo-inl.h -> foo_inl_h
// foo::bar::Apple -> foo_bar_apple
// Car_Rot -> car_rot
// FooBar -> foo_bar
// RPCTest -> rpctest
// HELLO -> hello
void to_underscored_name(std::string* out, const butil::StringPiece& name);
} // namespace bvar
// Make variables printable.
namespace std {
inline ostream& operator<<(ostream &os, const ::bvar::Variable &var) {
var.describe(os, false);
return os;
}
} // namespace std
#endif // BVAR_VARIABLE_H