Quick introduction

  1. #include <bvar/bvar.h>
  2. namespace foo {
  3. namespace bar {
  4. // bvar::Adder<T>用于累加,下面定义了一个统计read error总数的Adder。
  5. bvar::Adder<int> g_read_error;
  6. // 把bvar::Window套在其他bvar上就可以获得时间窗口内的值。
  7. bvar::Window<bvar::Adder<int> > g_read_error_minute("foo_bar", "read_error", &g_read_error, 60);
  8. // ^ ^ ^
  9. // 前缀 监控项名称 60秒,忽略则为10秒
  10. // bvar::LatencyRecorder是一个复合变量,可以统计:总量、qps、平均延时,延时分位值,最大延时。
  11. bvar::LatencyRecorder g_write_latency(“foo_bar", "write”);
  12. // ^ ^
  13. // 前缀 监控项,别加latency!LatencyRecorder包含多个bvar,它们会加上各自的后缀,比如write_qps, write_latency等等。
  14. // 定义一个统计“已推入task”个数的变量。
  15. bvar::Adder<int> g_task_pushed("foo_bar", "task_pushed");
  16. // 把bvar::PerSecond套在其他bvar上可以获得时间窗口内*平均每秒*的值,这里是每秒内推入task的个数。
  17. bvar::PerSecond<bvar::Adder<int> > g_task_pushed_second("foo_bar", "task_pushed_second", &g_task_pushed);
  18. // ^ ^
  19. // 和Window不同,PerSecond会除以时间窗口的大小. 时间窗口是最后一个参数,这里没填,就是默认10秒。
  20. } // bar
  21. } // foo

在应用的地方:

  1. // 碰到read error
  2. foo::bar::g_read_error << 1;
  3. // write_latency是23ms
  4. foo::bar::g_write_latency << 23;
  5. // 推入了1个task
  6. foo::bar::g_task_pushed << 1;

注意Window<>和PerSecond<>都是衍生变量,会自动更新,你不用给它们推值。你当然也可以把bvar作为成员变量或局部变量。

常用的bvar有:

  • bvar::Adder<T> : 计数器,默认0,varname << N相当于varname += N。
  • bvar::Maxer<T> : 求最大值,默认std::numeric_limits::min(),varname << N相当于varname = max(varname, N)。
  • bvar::Miner<T> : 求最小值,默认std::numeric_limits::max(),varname << N相当于varname = min(varname, N)。
  • bvar::IntRecorder : 求自使用以来的平均值。注意这里的定语不是“一段时间内”。一般要通过Window衍生出时间窗口内的平均值。
  • bvar::Window<VAR> : 获得某个bvar在一段时间内的累加值。Window衍生于已存在的bvar,会自动更新。
  • bvar::PerSecond<VAR> : 获得某个bvar在一段时间内平均每秒的累加值。PerSecond也是会自动更新的衍生变量。
  • bvar::LatencyRecorder : 专用于记录延时和qps的变量。输入延时,平均延时/最大延时/qps/总次数 都有了。

**确认变量名是全局唯一的!**否则会曝光失败,如果-bvar_abort_on_same_name为true,程序会直接abort。

程序中有来自各种模块不同的bvar,为避免重名,建议如此命名:模块_类名_指标

  • 模块一般是程序名,可以加上产品线的缩写,比如inf_ds,ecom_retrbs等等。
  • 类名一般是类名或函数名,比如storage_manager, file_transfer, rank_stage1等等。
  • 指标一般是count,qps,latency这类。

一些正确的命名如下:

  1. iobuf_block_count : 29 # 模块=iobuf 类名=block 指标=count
  2. iobuf_block_memory : 237568 # 模块=iobuf 类名=block 指标=memory
  3. process_memory_resident : 34709504 # 模块=process 类名=memory 指标=resident
  4. process_memory_shared : 6844416 # 模块=process 类名=memory 指标=shared
  5. rpc_channel_connection_count : 0 # 模块=rpc 类名=channel_connection 指标=count
  6. rpc_controller_count : 1 # 模块=rpc 类名=controller 指标=count
  7. rpc_socket_count : 6 # 模块=rpc 类名=socket 指标=count

目前bvar会做名字归一化,不管你打入的是foo::BarNum, foo.bar.num, foo bar num , foo-bar-num,最后都是foo_bar_num。

关于指标:

  • 个数以_count为后缀,比如request_count, error_count。
  • 每秒的个数以_second为后缀,比如request_second, process_inblocks_second,已经足够明确,不用写成_count_second或_per_second。
  • 每分钟的个数以_minute为后缀,比如request_minute, process_inblocks_minute

如果需要使用定义在另一个文件中的计数器,需要在头文件中声明对应的变量。

  1. namespace foo {
  2. namespace bar {
  3. // 注意g_read_error_minute和g_task_pushed_per_second都是衍生的bvar,会自动更新,不要声明。
  4. extern bvar::Adder<int> g_read_error;
  5. extern bvar::LatencyRecorder g_write_latency;
  6. extern bvar::Adder<int> g_task_pushed;
  7. } // bar
  8. } // foo

不要跨文件定义全局Window或PerSecond。不同编译单元中全局变量的初始化顺序是未定义的。在foo.cpp中定义Adder<int> foo_count,在foo_qps.cpp中定义PerSecond<Adder<int> > foo_qps(&foo_count);错误的做法。

About thread-safety:

  • bvar是线程兼容的。你可以在不同的线程里操作不同的bvar。比如你可以在多个线程中同时expose或hide不同的bvar,它们会合理地操作需要共享的全局数据,是安全的。
  • 除了读写接口,bvar的其他函数都是线程不安全的:比如说你不能在多个线程中同时expose或hide同一个bvar,这很可能会导致程序crash。一般来说,读写之外的其他接口也没有必要在多个线程中同时操作。

计时可以使用butil::Timer,接口如下:

  1. #include <butil/time.h>
  2. namespace butil {
  3. class Timer {
  4. public:
  5. enum TimerType { STARTED };
  6. Timer();
  7. // butil::Timer tm(butil::Timer::STARTED); // tm is already started after creation.
  8. explicit Timer(TimerType);
  9. // Start this timer
  10. void start();
  11. // Stop this timer
  12. void stop();
  13. // Get the elapse from start() to stop().
  14. int64_t n_elapsed() const; // in nanoseconds
  15. int64_t u_elapsed() const; // in microseconds
  16. int64_t m_elapsed() const; // in milliseconds
  17. int64_t s_elapsed() const; // in seconds
  18. };
  19. } // namespace butil

bvar::Variable

Variable是所有bvar的基类,主要提供全局注册,列举,查询等功能。

用户以默认参数建立一个bvar时,这个bvar并未注册到任何全局结构中,在这种情况下,bvar纯粹是一个更快的计数器。我们称把一个bvar注册到全局表中的行为为“曝光”,可通过expose函数曝光:

  1. // Expose this variable globally so that it's counted in following functions:
  2. // list_exposed
  3. // count_exposed
  4. // describe_exposed
  5. // find_exposed
  6. // Return 0 on success, -1 otherwise.
  7. int expose(const butil::StringPiece& name);
  8. int expose_as(const butil::StringPiece& prefix, const butil::StringPiece& name);

全局曝光后的bvar名字便为name或prefix + name,可通过以_exposed为后缀的static函数查询。比如Variable::describe_exposed(name)会返回名为name的bvar的描述。

当相同名字的bvar已存在时,expose会打印FATAL日志并返回-1。如果选项**—bvar_abort_on_same_name**设为true (默认是false),程序会直接abort。

下面是一些曝光bvar的例子:

  1. bvar::Adder<int> count1;
  2. count1 << 10 << 20 << 30; // values add up to 60.
  3. count1.expose("count1"); // expose the variable globally
  4. CHECK_EQ("60", bvar::Variable::describe_exposed("count1"));
  5. count1.expose("another_name_for_count1"); // expose the variable with another name
  6. CHECK_EQ("", bvar::Variable::describe_exposed("count1"));
  7. CHECK_EQ("60", bvar::Variable::describe_exposed("another_name_for_count1"));
  8. bvar::Adder<int> count2("count2"); // exposed in constructor directly
  9. CHECK_EQ("0", bvar::Variable::describe_exposed("count2")); // default value of Adder<int> is 0
  10. bvar::Status<std::string> status1("count2", "hello"); // the name conflicts. if -bvar_abort_on_same_name is true,
  11. // program aborts, otherwise a fatal log is printed.

为避免重名,bvar的名字应加上前缀,建议为。为了方便使用,我们提供了expose_as函数,接收一个前缀。

  1. // Expose this variable with a prefix.
  2. // Example:
  3. // namespace foo {
  4. // namespace bar {
  5. // class ApplePie {
  6. // ApplePie() {
  7. // // foo_bar_apple_pie_error
  8. // _error.expose_as("foo_bar_apple_pie", "error");
  9. // }
  10. // private:
  11. // bvar::Adder<int> _error;
  12. // };
  13. // } // foo
  14. // } // bar
  15. int expose_as(const butil::StringPiece& prefix, const butil::StringPiece& name);

Export all variables

最常见的导出需求是通过HTTP接口查询和写入本地文件。前者在brpc中通过/vars服务提供,后者则已实现在bvar中,默认不打开。有几种方法打开这个功能:

  • gflags解析输入参数,在程序启动时加入-bvar_dump,或在brpc中也可通过/flags服务在启动后动态修改。gflags的解析方法如下,在main函数处添加如下代码:
  1. #include <gflags/gflags.h>
  2. ...
  3. int main(int argc, char* argv[]) {
  4. google::ParseCommandLineFlags(&argc, &argv, true/*表示把识别的参数从argc/argv中删除*/);
  5. ...
  6. }
  • 不想用gflags解析参数,希望直接在程序中默认打开,在main函数处添加如下代码:
  1. #include <gflags/gflags.h>
  2. ...
  3. int main(int argc, char* argv[]) {
  4. if (google::SetCommandLineOption("bvar_dump", "true").empty()) {
  5. LOG(FATAL) << "Fail to enable bvar dump";
  6. }
  7. ...
  8. }

dump功能由如下gflags控制:

名称默认值作用
bvardumpfalseCreate a background thread dumping all bvar periodically, all bvar_dump flags are not effective when this flag is off
bvar_dump_exclude“”Dump bvar excluded from these wildcards(separated by comma), empty means no exclusion
bvar_dump_filemonitor/bvar..dataDump bvar into this file
bvar_dump_include“”Dump bvar matching these wildcards(separated by comma), empty means including all
bvar_dump_interval10Seconds between consecutive dump
bvar_dump_prefix<app>Every dumped name starts with this prefix
bvar_dump_tabs<check the code>Dump bvar into different tabs according to the filters (seperated by semicolon), format: (tab_name=wildcards)

当bvar_dump_file不为空时,程序会启动一个后台导出线程以bvar_dump_interval指定的间隔更新bvar_dump_file,其中包含了被bvar_dump_include匹配且不被bvar_dump_exclude匹配的所有bvar。

比如我们把所有的gflags修改为下图:

img

导出文件为:

  1. $ cat bvar.echo_server.data
  2. rpc_server_8002_builtin_service_count : 20
  3. rpc_server_8002_connection_count : 1
  4. rpc_server_8002_nshead_service_adaptor : brpc::policy::NovaServiceAdaptor
  5. rpc_server_8002_service_count : 1
  6. rpc_server_8002_start_time : 2015/07/24-21:08:03
  7. rpc_server_8002_uptime_ms : 14740954

像”iobuf_block_count : 8”被bvar_dump_include过滤了,“rpc_server_8002_error : 0”则被bvar_dump_exclude排除了。

如果你的程序没有使用brpc,仍需要动态修改gflag(一般不需要),可以调用google::SetCommandLineOption(),如下所示:

  1. #include <gflags/gflags.h>
  2. ...
  3. if (google::SetCommandLineOption("bvar_dump_include", "*service*").empty()) {
  4. LOG(ERROR) << "Fail to set bvar_dump_include";
  5. return -1;
  6. }
  7. LOG(INFO) << "Successfully set bvar_dump_include to *service*";

请勿直接设置FLAGS_bvar_dump_file / FLAGS_bvar_dump_include / FLAGS_bvar_dump_exclude。 一方面这些gflag类型都是std::string,直接覆盖是线程不安全的;另一方面不会触发validator(检查正确性的回调),所以也不会启动后台导出线程。

用户也可以使用dump_exposed函数自定义如何导出进程中的所有已曝光的bvar:

  1. // Implement this class to write variables into different places.
  2. // If dump() returns false, Variable::dump_exposed() stops and returns -1.
  3. class Dumper {
  4. public:
  5. virtual bool dump(const std::string& name, const butil::StringPiece& description) = 0;
  6. };
  7. // Options for Variable::dump_exposed().
  8. struct DumpOptions {
  9. // Contructed with default options.
  10. DumpOptions();
  11. // If this is true, string-type values will be quoted.
  12. bool quote_string;
  13. // The ? in wildcards. Wildcards in URL need to use another character
  14. // because ? is reserved.
  15. char question_mark;
  16. // Separator for white_wildcards and black_wildcards.
  17. char wildcard_separator;
  18. // Name matched by these wildcards (or exact names) are kept.
  19. std::string white_wildcards;
  20. // Name matched by these wildcards (or exact names) are skipped.
  21. std::string black_wildcards;
  22. };
  23. class Variable {
  24. ...
  25. ...
  26. // Find all exposed variables matching `white_wildcards' but
  27. // `black_wildcards' and send them to `dumper'.
  28. // Use default options when `options' is NULL.
  29. // Return number of dumped variables, -1 on error.
  30. static int dump_exposed(Dumper* dumper, const DumpOptions* options);
  31. };

bvar::Reducer

Reducer用二元运算符把多个值合并为一个值,运算符需满足结合律,交换律,没有副作用。只有满足这三点,我们才能确保合并的结果不受线程私有数据如何分布的影响。像减法就不满足结合律和交换律,它无法作为此处的运算符。

  1. // Reduce multiple values into one with `Op': e1 Op e2 Op e3 ...
  2. // `Op' shall satisfy:
  3. // - associative: a Op (b Op c) == (a Op b) Op c
  4. // - commutative: a Op b == b Op a;
  5. // - no side effects: a Op b never changes if a and b are fixed.
  6. // otherwise the result is undefined.
  7. template <typename T, typename Op>
  8. class Reducer : public Variable;

reducer << e1 << e2 << e3的作用等价于reducer = e1 op e2 op e3。

常见的Redcuer子类有bvar::Adder, bvar::Maxer, bvar::Miner。

bvar::Adder

顾名思义,用于累加,Op为+。

  1. bvar::Adder<int> value;
  2. value << 1 << 2 << 3 << -4;
  3. CHECK_EQ(2, value.get_value());
  4. bvar::Adder<double> fp_value; // 可能有warning
  5. fp_value << 1.0 << 2.0 << 3.0 << -4.0;
  6. CHECK_DOUBLE_EQ(2.0, fp_value.get_value());

Adder<>可用于非基本类型,对应的类型至少要重载T operator+(T, T)。一个已经存在的例子是std::string,下面的代码会把string拼接起来:

  1. // This is just proof-of-concept, don't use it for production code because it makes a
  2. // bunch of temporary strings which is not efficient, use std::ostringstream instead.
  3. bvar::Adder<std::string> concater;
  4. std::string str1 = "world";
  5. concater << "hello " << str1;
  6. CHECK_EQ("hello world", concater.get_value());

bvar::Maxer

用于取最大值,运算符为std::max。

  1. bvar::Maxer<int> value;
  2. value << 1 << 2 << 3 << -4;
  3. CHECK_EQ(3, value.get_value());

Since Maxer<> use std::numeric_limits::min() as the identity, it cannot be applied to generic types unless you specialized std::numeric_limits<> (and overloaded operator<, yes, not operator>).

bvar::Miner

用于取最小值,运算符为std::min。

  1. bvar::Maxer<int> value;
  2. value << 1 << 2 << 3 << -4;
  3. CHECK_EQ(-4, value.get_value());

Since Miner<> use std::numeric_limits::max() as the identity, it cannot be applied to generic types unless you specialized std::numeric_limits<> (and overloaded operator<).

bvar::IntRecorder

用于计算平均值。

  1. // For calculating average of numbers.
  2. // Example:
  3. // IntRecorder latency;
  4. // latency << 1 << 3 << 5;
  5. // CHECK_EQ(3, latency.average());
  6. class IntRecorder : public Variable;

bvar::LatencyRecorder

专用于计算latency和qps的计数器。只需填入latency数据,就能获得latency / max_latency / qps / count。统计窗口是最后一个参数,不填为bvar_dump_interval(这里没填)。

注意:LatencyRecorder没有继承Variable,而是多个bvar的组合。

  1. LatencyRecorder write_latency("table2_my_table_write"); // produces 4 variables:
  2. // table2_my_table_write_latency
  3. // table2_my_table_write_max_latency
  4. // table2_my_table_write_qps
  5. // table2_my_table_write_count
  6. // In your write function
  7. write_latency << the_latency_of_write;

bvar::Window

获得之前一段时间内的统计值。Window不能独立存在,必须依赖于一个已有的计数器。Window会自动更新,不用给它发送数据。出于性能考虑,Window的数据来自于每秒一次对原计数器的采样,在最差情况下,Window的返回值有1秒的延时。

  1. // Get data within a time window.
  2. // The time unit is 1 second fixed.
  3. // Window relies on other bvar which should be constructed before this window and destructs after this window.
  4. // R must:
  5. // - have get_sampler() (not require thread-safe)
  6. // - defined value_type and sampler_type
  7. template <typename R>
  8. class Window : public Variable;

bvar::PerSecond

获得之前一段时间内平均每秒的统计值。它和Window基本相同,除了返回值会除以时间窗口之外。

  1. bvar::Adder<int> sum;
  2. // sum_per_second.get_value()是sum在之前60秒内*平均每秒*的累加值,省略最后一个时间窗口的话默认为bvar_dump_interval。
  3. bvar::PerSecond<bvar::Adder<int> > sum_per_second(&sum, 60);

PerSecond并不总是有意义

上面的代码中没有Maxer,因为一段时间内的最大值除以时间窗口是没有意义的。

  1. bvar::Maxer<int> max_value;
  2. // 错误!最大值除以时间是没有意义的
  3. bvar::PerSecond<bvar::Maxer<int> > max_value_per_second_wrong(&max_value);
  4. // 正确,把Window的时间窗口设为1秒才是正确的做法
  5. bvar::Window<bvar::Maxer<int> > max_value_per_second(&max_value, 1);

和Window的差别

比如要统计内存在上一分钟内的变化,用Window<>的话,返回值的含义是”上一分钟内存增加了18M”,用PerSecond<>的话,返回值的含义是“上一分钟平均每秒增加了0.3M”。

Window的优点是精确值,适合一些比较小的量,比如“上一分钟的错误数“,如果这用PerSecond的话,得到可能是”上一分钟平均每秒产生了0.0167个错误”,这相比于”上一分钟有1个错误“显然不够清晰。另外一些和时间无关的量也要用Window,比如统计上一分钟cpu占用率的方法是用一个Adder同时累加cpu时间和真实时间,然后用Window获得上一分钟的cpu时间和真实时间,两者相除就得到了上一分钟的cpu占用率,这和时间无关,用PerSecond会产生错误的结果。

bvar::Status

记录和显示一个值,拥有额外的set_value函数。

  1. // Display a rarely or periodically updated value.
  2. // Usage:
  3. // bvar::Status<int> foo_count1(17);
  4. // foo_count1.expose("my_value");
  5. //
  6. // bvar::Status<int> foo_count2;
  7. // foo_count2.set_value(17);
  8. //
  9. // bvar::Status<int> foo_count3("my_value", 17);
  10. //
  11. // Notice that Tp needs to be std::string or acceptable by boost::atomic<Tp>.
  12. template <typename Tp>
  13. class Status : public Variable;

bvar::PassiveStatus

按需显示值。在一些场合中,我们无法set_value或不知道以何种频率set_value,更适合的方式也许是当需要显示时才打印。用户传入打印回调函数实现这个目的。

  1. // Display a updated-by-need value. This is done by passing in an user callback
  2. // which is called to produce the value.
  3. // Example:
  4. // int print_number(void* arg) {
  5. // ...
  6. // return 5;
  7. // }
  8. //
  9. // // number1 : 5
  10. // bvar::PassiveStatus status1("number1", print_number, arg);
  11. //
  12. // // foo_number2 : 5
  13. // bvar::PassiveStatus status2(typeid(Foo), "number2", print_number, arg);
  14. template <typename Tp>
  15. class PassiveStatus : public Variable;

虽然很简单,但PassiveStatus是最有用的bvar之一,因为很多统计量已经存在,我们不需要再次存储它们,而只要按需获取。比如下面的代码声明了一个在linux下显示进程用户名的bvar:

  1. static void get_username(std::ostream& os, void*) {
  2. char buf[32];
  3. if (getlogin_r(buf, sizeof(buf)) == 0) {
  4. buf[sizeof(buf)-1] = '\0';
  5. os << buf;
  6. } else {
  7. os << "unknown";
  8. }
  9. }
  10. PassiveStatus<std::string> g_username("process_username", get_username, NULL);

bvar::GFlag

Expose important gflags as bvar so that they’re monitored (in noah).

  1. DEFINE_int32(my_flag_that_matters, 8, "...");
  2. // Expose the gflag as *same-named* bvar so that it's monitored (in noah).
  3. static bvar::GFlag s_gflag_my_flag_that_matters("my_flag_that_matters");
  4. // ^
  5. // the gflag name
  6. // Expose the gflag as a bvar named "foo_bar_my_flag_that_matters".
  7. static bvar::GFlag s_gflag_my_flag_that_matters_with_prefix("foo_bar", "my_flag_that_matters");