Ch20 可观测性：监控、性能分析与调试

// kbe/src/lib/helper/watcher.h

// 基类：路径式标识 + 序列化接口
class WatcherObject {
public:
    WatcherObject(std::string path);
    virtual void addToInitStream(MemoryStream* s) {};
    virtual void addToStream(MemoryStream* s) {};
    const char* path() { return path_.c_str(); }
    const char* name() { return name_.c_str(); }
    virtual WATCHER_VALUE_TYPE getType() { return WATCHER_VALUE_TYPE_UNKNOWN; }
protected:
    std::string path_, name_, strval_;
    WATCHER_ID id_;
    int32 numWitness_;   // 当前观察者数量
};

// 监视一个值（引用绑定）
template <class T>
class WatcherValue : public WatcherObject {
public:
    WatcherValue(std::string path, const T& pVal)
      : WatcherObject(path), watchVal_(pVal) {}
    void addToStream(MemoryStream* s) { (*s) << id_ << watchVal_; }
    T getValue() { return watchVal_; }
protected:
    const T& watchVal_;  // 绑定到被监视变量的引用
};

// 监视一个自由函数的返回值
template <class RETURN_TYPE>
class WatcherFunction : public WatcherObject {
    typedef RETURN_TYPE(*FUNC)();
    void addToStream(MemoryStream* s) { (*s) << id_ << (*func_)(); }
protected:
    FUNC func_;
};

// 监视一个成员函数的返回值
template <class RETURN_TYPE, class OBJ_TYPE>
class WatcherMethod : public WatcherObject {
    typedef RETURN_TYPE(OBJ_TYPE::*FUNC)();
    void addToStream(MemoryStream* s) { (*s) << id_ << (obj_->*func_)(); }
protected:
    FUNC func_;
    OBJ_TYPE* obj_;
};

// kbe/src/lib/helper/watcher.h

class Watchers {
public:
    static Watchers& rootWatchers();
    typedef KBEUnordered_map<std::string, KBEShared_ptr<WatcherObject>> WATCHER_MAP;
    bool addWatcher(const std::string& path, WatcherObject* pwo);
    KBEShared_ptr<WatcherObject> getWatcher(const std::string& name);
    void addToStream(MemoryStream* s);  // 序列化所有 watcher 值
};

class WatcherPaths {
public:
    static WatcherPaths& root();
    typedef KBEUnordered_map<std::string, KBEShared_ptr<WatcherPaths>> WATCHER_PATHS;
    bool addWatcher(std::string path, WatcherObject* pwo);
    void dirPath(std::string path, std::vector<std::string>& vec);
};

// BigWorld: lib/network/watcher_nub.hpp

enum WatcherMsg {
    WATCHER_MSG_GET = 16,          // 查询 watcher 值
    WATCHER_MSG_SET = 17,          // 设置 watcher 值
    WATCHER_MSG_TELL = 18,         // 返回 watcher 值
    WATCHER_MSG_GET2 = 26,         // V2 协议
    WATCHER_MSG_SET2 = 27,
    WATCHER_MSG_TELL2 = 28,
    WATCHER_MSG_SET2_TELL2 = 29,
    WATCHER_MSG_EXTENSION_START = 107
};

struct WatcherRegistrationMsg {
    int  version;
    int  uid;
    int  message;     // WATCHER_...
    int  id;          // e.g. 14
    char abrv[32];    // e.g. "cell14"
    char name[64];    // e.g. "Cell 14"
};

// BigWorld: lib/server/watcher_forwarding.hpp

class ForwardingWatcher : public Watcher {
public:
    enum ExposeHints {
        WITH_ENTITY = 0,     // 组件拥有特定实体
        CELL_APPS,           // 所有 CellApp
        WITH_SPACE,          // 特定 Space 的所有组件
        LEAST_LOADED,        // 负载最低的组件
        LOCAL_ONLY,          // 仅本地
        BASE_APPS,           // 所有 BaseApp
        SERVICE_APPS,        // 所有 ServiceApp
        BASE_SERVICE_APPS,   // 所有 Base + Service App
    };

    virtual ForwardingCollector* newCollector(
        WatcherPathRequestV2& pathRequest,
        const BW::string& destWatcher,
        const BW::string& targetInfo) = 0;
};

// kbe/src/lib/helper/profile.h

class ProfileVal {
public:
    void start() {
        TimeStamp now = timestamp();
        if (inProgress_++ == 0)
            lastTime_ = now;          // 记录第一次进入的时间

        ProfileGroup::PROFILEVALS& stack = pProfileGroup_->stack();

        // 如果栈中有对象，说明从上一个函数进入了本函数
        // 取上一个函数到本函数之间耗时的"内部时间"
        if (!stack.empty()) {
            ProfileVal& profile = *stack.back();
            profile.lastIntTime_ = now - profile.lastIntTime_;
            profile.sumIntTime_ += profile.lastIntTime_;
        }
        stack.push_back(this);
        lastIntTime_ = now;
    }

    void stop(uint32 qty = 0) {
        TimeStamp now = timestamp();
        // inProgress_ 为 0 时，计算本函数的总耗时
        if (--inProgress_ == 0) {
            lastTime_ = now - lastTime_;
            sumTime_ += lastTime_;
        }
        lastQuantity_ = qty;
        sumQuantity_ += qty;
        ++count_;

        ProfileGroup::PROFILEVALS& stack = pProfileGroup_->stack();
        stack.pop_back();
        lastIntTime_ = now - lastIntTime_;
        sumIntTime_ += lastIntTime_;

        // 恢复上层函数的内部时间起点
        if (!stack.empty())
            stack.back()->lastIntTime_ = now;
    }

    // 关键字段
    std::string  name_;
    TimeStamp    lastTime_;       // 最近一次总耗时
    TimeStamp    sumTime_;        // 累计总耗时
    TimeStamp    lastIntTime_;    // 最近一次内部耗时
    TimeStamp    sumIntTime_;     // 累计内部耗时
    uint32       count_;          // 调用次数
    int          inProgress_;     // 重入计数
};

// kbe/src/lib/helper/profile.h

class ScopedProfile {
public:
    ScopedProfile(ProfileVal& profile, const char* filename, int lineNum)
      : profile_(profile), filename_(filename), lineNum_(lineNum) {
        profile_.start();
    }
    ~ScopedProfile() { profile_.stop(filename_, lineNum_); }
};

// 使用方式
#define AUTO_SCOPED_PROFILE(NAME)                   \
    static ProfileVal _localProfile(NAME);          \
    ScopedProfile _autoScopedProfile(_localProfile, __FILE__, __LINE__);

#define START_PROFILE(PROFILE)  PROFILE.start();
#define STOP_PROFILE(PROFILE)   PROFILE.stop(__FILE__, __LINE__);

// kbe/src/server/cellapp/profile.h（示例，各组件独立定义）

// cellapp 中定义的关键 ProfileVal：
extern ProfileVal ON_MOVE_PROFILE;
extern ProfileVal ON_NAVIGATE_PROFILE;
extern ProfileVal CLIENT_UPDATE_PROFILE;
extern ProfileVal AOI_UPDATE_PROFILE;
// ... 更多

// BigWorld: lib/cstdmf/profiler.hpp

class Profiler {
public:
    enum ProfileMode {
        PROFILE_OFF = 0,
        HIERARCHICAL,       // 层次化显示
        SORT_BY_TIME,       // 按耗时排序
        SORT_BY_NUMCALLS,   // 按调用次数排序
        SORT_BY_NAME,       // 按名称排序
        CPU_GPU,            // CPU/GPU 分离显示
        GRAPHS,             // 图形化
        CORES,              // 按核心显示
    };

    enum EventType {
        EVENT_START,        // 计时开始
        EVENT_START_IDLE,   // 空闲计时开始
        EVENT_END,          // 计时结束
        EVENT_COUNTER       // 计数器事件
    };

    enum EventCategory {
        CATEGORY_CPP    = (1 << 0),
        CATEGORY_GPU    = (1 << 1),
        CATEGORY_PYTHON = (1 << 2),
        CATEGORY_ALL    = (1 << 3) - 1
    };

    void addEntry(const char* text, EventType e,
                  int32 value, EventCategory category);
    void tick();
    void setProfileMode(ProfileMode mode, bool inclusive);
    void getStatistics(BW::vector<ProfileLine>* profileOutput);
};

// BigWorld: lib/server/entity_profiler.hpp

class EntityProfiler {
public:
    void start() const;
    void stop() const;
    void tick(uint64 tickDtInStamps,
              float smoothingFactor,
              EntityTypeProfiler& typeProfiler);

    float load() const { return currAdjustedLoad_; }
    float rawLoad() const { return currRawLoad_; }
    float maxRawLoad() const { return maxRawLoad_; }

    // RAII 自动作用域追踪
    template <class ENTITY>
    class AutoScopedHelper {
    public:
        AutoScopedHelper(const ENTITY* pEntity) : pEntity_() {
            if (pEntity) {
                pEntity_ = pEntity;
                pEntity->profiler().start();
            }
        }
        ~AutoScopedHelper() {
            if (pEntity_) pEntity_->profiler().stop();
        }
    private:
        ConstSmartPointer<ENTITY> pEntity_;
    };

private:
    mutable uint64 elapsedTickTime_;
    float currAdjustedLoad_;   // 指数平滑后的负载
    float currRawLoad_;        // 原始负载
    float maxRawLoad_;         // 最大负载
};

// 使用宏
#define AUTO_SCOPED_THIS_ENTITY_PROFILE  \
    EntityProfiler::AutoScopedHelper<BaseOrEntity> _autoEntityProfile(this)

// BigWorld: lib/server/entity_type_profiler.hpp

class EntityTypeProfiler {
public:
    void addEntityLoad(float entitySmoothedLoad,
                       float entityRawLoad,
                       float entityAddedLoad);
    void tick();

    float load() const { return currSmoothedLoad_; }
    float rawLoad() const { return currRawLoad_; }
    int numEntities() const { return numEntities_; }

private:
    float currSmoothedLoad_;  // 该类型的平均平滑负载
    float currRawLoad_;
    float currAddedLoad_;
    int numEntities_;         // 该类型的实体数量
};

// BigWorld: server/cellapp/cell_profiler.hpp

class CellProfiler {
public:
    void addEntityLoad(float entitySmoothedLoad, float entityRawLoad);
    void tick();
    float load() const { return currSmoothedLoad_; }
    float rawLoad() const { return currRawLoad_; }
    float maxRawLoad() const { return maxRawLoad_; }

private:
    float currSmoothedLoad_;
    float currRawLoad_;
    float maxRawLoad_;
    float accSmoothedLoad_;  // 一个 tick 内的累积值
    float accRawLoad_;
};

// kbe/src/lib/network/network_stats.h

class NetworkStats : public Singleton<NetworkStats> {
public:
    enum S_OP { SEND, RECV };

    struct Stats {
        std::string name;
        uint32 send_size;    // 发送总字节数
        uint32 send_count;   // 发送次数
        uint32 recv_size;    // 接收总字节数
        uint32 recv_count;   // 接收次数
    };

    typedef KBEUnordered_map<std::string, Stats> STATS;

    void trackMessage(S_OP op, const MessageHandler& msgHandler, uint32 size);
    STATS& stats() { return stats_; }

private:
    STATS stats_;
};

// BigWorld: lib/network/sending_stats.hpp

class SendingStats : public TimerHandler {
public:
    double bitsPerSecond() const;
    double packetsPerSecond() const;
    double messagesPerSecond() const;

    uint numPacketsSent() const;
    uint numBundlesSent() const;
    uint numPacketsResent() const;     // 重传统计
    uint numPiggybacks() const;        // 捎带统计
    uint numFailedBundleSend() const;  // 发送失败统计
    uint numFailedPacketSend() const;

private:
    Stat numBytesSent_;
    Stat numBytesResent_;
    Stat numPacketsSent_;
    Stat numPacketsResent_;
    Stat numPiggybacks_;
    Stat numBytesPiggybacked_;
    Stat numBundlesSent_;
    Stat numMessagesSent_;
    Stat numReliableMessagesSent_;
    Stat numFailedPacketSend_;
    Stat numFailedBundleSend_;
};

// kbe/src/lib/server/telnet_handler.h

class TelnetHandler : public Network::InputNotificationHandler {
public:
    enum TELNET_STATE {
        TELNET_STATE_PASSWD,    // 密码认证
        TELNET_STATE_ROOT,      // 根命令模式
        TELNET_STATE_PYTHON,    // Python 解释器模式
        TELNET_STATE_READONLY,  // 只读模式
        TELNET_STATE_QUIT       // 退出
    };

    TelnetHandler(Network::EndPoint* pEndPoint,
                  TelnetServer* pTelnetServer,
                  Network::NetworkInterface* pNetworkInterface,
                  TELNET_STATE defstate = TELNET_STATE_ROOT);
};

// kbe/src/server/cellapp/cellapp.cpp

pTelnetServer_ = new TelnetServer(&this->dispatcher(), &this->networkInterface());
pTelnetServer_->pScript(&this->getScript());
pTelnetServer_->start(g_kbeSrvConfig.getCellApp().telnet_passwd,
                       g_kbeSrvConfig.getCellApp().telnet_deflayer,
                       g_kbeSrvConfig.getCellApp().telnet_port);

// 组件初始化时自动执行
pTelnetServer_ = new TelnetServer(...);
pTelnetServer_->start(passwd, deflayer, port);

// kbe/src/server/tools/logger/logger.h（简化）

struct LOG_ITEM {
    int uid;
    int logtype;
    int componentType;
    int componentID;
    double t;
    KBEngine::KBETime kbetime;
    std::string logstream;
    bool persistent;           // 是否持久化
};

class Logger {
public:
    void writeLog(Network::Channel* pChannel, KBEngine::MemoryStream& s);
    void registerLogWatcher(Network::Channel* pChannel, KBEngine::MemoryStream& s);
    void sendInitLogs(LogWatcher& logWatcher);
    size_t bufferedLogsSize();

private:
    std::deque<LOG_ITEM*> buffered_logs_;  // 缓冲最近一批日志指针
};

// BigWorld: server/tools/message_logger/logger.hpp

class Logger : public WatcherRequestHandler, public TimerHandler {
public:
    bool init(int argc, char* argv[]);
    bool handleNextMessage();
    bool shouldLogPriority(MessageLogger::NetworkMessagePriority priority);
protected:
    virtual void processExtensionMessage(int messageID,
            char* data, int dataLen, WatcherEndpoint& watcherEndpoint);
};

// 日志条目
struct LogEntry {
    LogEntry(const struct timeval& tv,
             MessageLogger::UserComponentID componentID, ...);
    const struct timeval& time() const;
    int categoryID() const;
    int messagePriority() const;
    int stringOffset() const;
};

// BigWorld: lib/server/server_info.hpp

class ServerInfo {
public:
    const BW::string& serverName() const { return serverName_; }
    const BW::string& cpuInfo() const { return cpuInfo_; }
    const CpuSpeeds& cpuSpeeds() const { return cpuSpeeds_; }
    const BW::string& memInfo() const { return memInfo_; }
    uint64 memTotal() const { return memTotal_; }
    uint64 memUsed() const { return memUsed_; }
    void updateMem();    // 运行时刷新内存使用

private:
    BW::string serverName_;
    BW::string cpuInfo_;
    BW::vector<float> cpuSpeeds_;
    BW::string memInfo_;
    uint64 memTotal_;
    uint64 memUsed_;
};