比最差的API(ETW)更差的API(LTTng)是如何煉成的, 談如何寫一個好的介面

来源:https://www.cnblogs.com/zkweb/archive/2017/12/27/8126303.html
-Advertisement-
Play Games

最近這幾天在幫 "檸檬" 看她的APM系統要如何收集.Net運行時的各種事件, 這些事件包括線程開始, JIT執行, GC觸發等等. .Net在windows上(NetFramework, CoreCLR)通過ETW(Event Tracing for Windows), 在linux上(CoreC ...


最近這幾天在幫檸檬看她的APM系統要如何收集.Net運行時的各種事件, 這些事件包括線程開始, JIT執行, GC觸發等等.
.Net在windows上(NetFramework, CoreCLR)通過ETW(Event Tracing for Windows), 在linux上(CoreCLR)是通過LTTng跟蹤事件.

ETW的API設計已經被很多人詬病, 微軟推出的類庫krabsetw中直指ETW是最差的API並且把操作ETW的文件命名為噩夢.hpp.
而且這篇文章中, Casey Muratori解釋了為什麼ETW是最差的API, 原因包括:

  • 事件類型使用了位標誌(最多只能有32個), 沒有考慮到未來的情況
  • 不同的介面共用一個大的構造體, 介面的輸入和輸出不明確
  • 讓調用者寫無論怎麼看都是多餘的代碼
  • 讓調用者使用魔法數字(而不是提供一個枚舉值)
  • 命名帶有誤導性
  • 返回值的意義不統一
  • 使用過於複雜, 沒有先想好用例
  • 文檔裡面沒有完整的示例代碼, 只能從零碎的代碼拼湊

然而Casey Muratori的文章對我幫助很大, 我只用了1天時間就寫出了使用ETW收集.Net運行時事件的示例代碼.
之後我開始看如何使用LTTng收集這些事件, 按照我以往的經驗linux上的類庫api通常會比windows的好用, 但LTTng是個例外.

我第一件做的事情是去查找怎樣在c程式裡面LTTng的介面, 我打開了他們的文檔然後開始瀏覽.
很快我發現了他們的文檔只談瞭如何使用代碼發送事件, 卻沒有任何說明如何用代碼接收事件, 我意識到我應該去看源代碼.

初始化LTTng

使用LTTng跟蹤事件首先需要創建一個會話, 啟用事件和添加上下文參數, 然後啟用跟蹤, 在命令行裡面是這樣的調用:

lttng create --live
lttng enable-event --userspace --tracepoint DotNETRuntime:GCStart_V2
lttng add-context --userspace --type vpid
lttng add-context --userspace --type vtid
lttng start

lttng這個命令的源代碼在github上, 通過幾分鐘的查找我發現lttng的各個命令的實現都是保存在這個文件夾下的.
打開create.c後又發現了創建會話調用的是lttng_create_session函數, 而lttng_create_session函數可以通過引用lttng.h調用.
再過了幾分鐘我寫出了第一行代碼

int ret = lttng_create_session_live("example-session", "net://127.0.0.1", 1000000);

運行後立刻就報錯了, 錯誤是"No session daemon is available".
原因是lttng-sessiond這個程式沒有啟動, lttng是通過一個獨立服務來管理會話的, 而這個服務需要手動啟動.

使用獨立服務本身沒有錯, 但是lttng-sessiond這個程式提供了很多參數,
如果一個只想跟蹤用戶事件的程式啟動了這個服務並指定了忽略內核事件的參數, 然後另外一個跟蹤內核事件的程式將不能正常運作.
正確的做法是使用systemd來啟動這個服務, 讓系統管理員決定用什麼參數, 而不是讓調用者去啟動它.

解決這個問題只需要簡單粗暴的兩行, 啟動時如果已經啟動過新進程會失敗, 沒有任何影響:

system("lttng-sessiond --daemonize");
std::this_thread::sleep_for(std::chrono::seconds(1));

現在lttng_create_session_live會返回成功了, 但是又發現了新的問題,
創建的會話是由一個單獨的服務管理的, 即使當前進程退出會話也會存在, 第二次創建的時候會返回一個已存在的錯誤.
這個問題和ETW的問題一模一樣, 解決方法也一模一樣, 在創建會話前關閉它就可以了.

於是代碼變成了這樣:

system("lttng-sessiond --daemonize");
std::this_thread::sleep_for(std::chrono::seconds(1));
lttng_destroy_session(SessionName);
int ret = lttng_create_session_live("example-session", "net://127.0.0.1", 1000000);

經過一段時間後, 我用代碼實現了和命令行一樣的功能:

// start processes, won't replace exists
system("lttng-sessiond --daemonize");
std::this_thread::sleep_for(std::chrono::seconds(1));

// create new session
lttng_destroy_session(SessionName);
int ret = lttng_create_session_live(SessionName, SessionUrl, LiveSessionInterval);
if (ret != 0) {
    std::cerr << "lttng_create_session: " << lttng_strerror(ret) << std::endl;
    return -1;
}

// create handle from session
lttng_domain domain = {};
domain.type = LTTNG_DOMAIN_UST;
lttng_handle* handle = lttng_create_handle(SessionName, &domain);
if (handle == nullptr) {
    std::cerr << "lttng_create_handle: " << lttng_strerror(ret) << std::endl;
    return -1;
}

// enable event
lttng_event event = {};
event.type = LTTNG_EVENT_TRACEPOINT;
memcpy(event.name, EventName.c_str(), EventName.size());
event.loglevel_type = LTTNG_EVENT_LOGLEVEL_ALL;
event.loglevel = -1;
ret = lttng_enable_event_with_exclusions(handle, &event, nullptr, nullptr, 0, nullptr);
if (ret < 0) {
    std::cerr << "lttng_enable_event_with_exclusions: " << lttng_strerror(ret) << std::endl;
    return -1;
}

// add context
lttng_event_context contextPid = {};
contextPid.ctx = LTTNG_EVENT_CONTEXT_VPID;
ret = lttng_add_context(handle, &contextPid, nullptr, nullptr);
if (ret < 0) {
    std::cerr << "lttng_add_context: " << lttng_strerror(ret) << std::endl;
    return -1;
}

// start tracing
ret = lttng_start_tracing(SessionName);
if (ret < 0) {
    std::cerr << "lttng_start_tracing: " << lttng_strerror(ret) << std::endl;
    return -1;
}

到這裡為止是不是很簡單? 儘管沒有文檔, 但是這些api都是非常簡單的api, 看源代碼就可以推測如何調用.

獲取事件

在告訴LTTng啟用跟蹤後, 我還需要獲取發送到LTTng的事件, 在ETW中獲取事件是通過註冊回調獲取的:

EVENT_TRACE_LOGFILE trace = { };
trace.LoggerName = (char*)mySessionName.c_str();
trace.EventRecordCallback = (PEVENT_RECORD_CALLBACK)(StaticRecordEventCallback);
trace.BufferCallback = (PEVENT_TRACE_BUFFER_CALLBACK)(StaticBufferEventCallback);
trace.ProcessTraceMode = PROCESS_TRACE_MODE_EVENT_RECORD | PROCESS_TRACE_MODE_REAL_TIME;
TRACEHANDLE sessionHandle = ::OpenTrace(&trace);
if (sessionHandle == INVALID_PROCESSTRACE_HANDLE) {
    // ...
}
ULONG processStatus = ::ProcessTrace(&sessionHandle, 1, nullptr, nullptr);

我尋思lttng有沒有這樣的機制, 首先我看到的是lttng.h中的lttng_register_consumer函數, 這個函數的註釋如下:

This call registers an "outside consumer" for a session and an lttng domain.
No consumer will be spawned and all fds/commands will go through the socket path given (socket_path).

翻譯出來就是給會話註冊一個外部的消費者, 聽上去和我的要求很像吧?
這個函數的第二個參數是一個字元串, 我推測是unix socket, lttng會通過unix socket發送事件過來.
於是我寫了這樣的代碼:

ret = lttng_register_consumer(handle, "/tmp/custom-consumer");

一執行立刻報錯, 錯誤是Command undefined, 也就是命令未定義, 服務端不支持這個命令.
經過搜索發現lttng的源代碼中沒有任何調用這個函數的地方, 也就是說這個函數是個裝飾.
看起來這個辦法行不通.

經過一番查找, 我發現了live-reading-howto這個文檔, 裡面的內容非常少但是可以看出使用lttng-relayd這個服務可以讀取事件.
讀取事件目前只支持TCP, 使用TCP傳輸事件數據不僅複雜而且效率很低, 相對ETW直接通過記憶體傳遞數據這無疑是個愚蠢的辦法.
雖然愚蠢但是還是要繼續寫, 我開始看這TCP傳輸用的是什麼協議.

對傳輸協議的解釋文檔在live-reading-protocol.txt, 這篇文檔寫的很糟糕, 但總比沒有好.
和lttng-relayd進行交互使用的是一個lttng自己創造的半雙工二進位協議, 設計如下:

客戶端發送命令給lttng-relayd需要遵從以下的格式

[data_size: unsigned 64 bit big endian int, 命令體大小]
[cmd: unsigned 32 bit big endian int, 命令類型]
[cmd_version: unsigned 32 bit big endian int, 命令版本]
[命令體, 大小是data_size]

發送命令的設計沒有問題, 大部分二進位協議都是這樣設計的, 問題在於接收命令的設計.
接收命令的格式完全依賴於發送命令的類型, 例如LTTNG_VIEWER_CONNECT這個命令發送過去會收到以下的數據:

[viewer_session_id: unsigned 64 bit big endian int, 服務端指定的會話ID]
[major: unsigned 32 bit big endian int, 大版本]
[minor: unsigned 32 bit big endian int, 中版本]
[type: 客戶端的類型]

可以看出接收的數據沒有數據頭, 沒有數據頭如何決定接收多少數據呢? 這就要求客戶端定義的回應大小必須和服務端完全一致, 一個欄位都不能漏.
服務端在以後的更新中不能給返回數據隨意添加欄位, 返回多少欄位需要取決於發送過來的cmd_version, 保持api的相容性將會非常的麻煩.
目前在lttng中cmd_version是一個預留欄位, 也就是他們沒有仔細的想過api的更新問題.
正確的做法應該是返回數據也應該提供一個數據頭, 然後允許客戶端忽略多出來的數據.

看完協議以後, 我在想既然使用了二進位協議, 應該也會提供一個sdk來減少解析的工作量吧?
經過一番查找找到了一個頭文件lttng-viewer-abi.h, 包含了和lttng-relayd交互使用的數據結構體定義.
這個頭文件在源代碼裡面有, 但是卻不在LTTng發佈的軟體包中, 這意味著使用它需要複製它到項目裡面.
複製別人的源代碼到項目裡面不能那麼隨便, 看了一下LTTng的開源協議, 在include/lttng/*和src/lib/lttng-ctl/*下的文件是LGPL, 其餘文件是GPL,
也就是上面如果把這個頭文件複製到自己的項目裡面, 自己的項目必須使用GPL協議開源, 不想用GPL的話只能把裡面的內容自己一行行重新寫, 還不能寫的太像.

既然是測試就不管這麼多了, 把這個頭文件的代碼複製過來就開始繼續寫, 首先是連接到lttng-relayd:

int fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
if (fd < 0) {
    perror("socket");
    return -1;
}
sockaddr_in address = {};
address.sin_addr.s_addr = inet_addr("127.0.0.1");
address.sin_family = AF_INET;
address.sin_port = htons(5344);
ret = connect(fd, (sockaddr*)&address, sizeof(address));
if (ret < 0) {
    perror("connect");
    return -1;
}

連接成功以後的交互流程在閱讀上面的協議文檔以後可以整理如下:

初始化
    客戶端發送命令 LTTNG_VIEWER_CLIENT_COMMAND + 構造體 lttng_viewer_connect
    服務端返回構造體 lttng_viewer_connect
    客戶端發送命令 LTTNG_VIEWER_CREATE_SESSION + 構造體 lttng_viewer_create_session_response
    服務端返回構造體 lttng_viewer_create_session_response
列出會話
    客戶端發送命令 LTTNG_VIEWER_LIST_SESSIONS, 不帶構造體
    服務端返回構造體 lttng_viewer_list_sessions + 指定長度的 lttng_viewer_session
附加到會話
    客戶端發送命令 LTTNG_VIEWER_ATTACH_SESSION + 構造體 lttng_viewer_attach_session_request
    服務端返回構造體 lttng_viewer_attach_session_response + 指定長度的 lttng_viewer_stream
迴圈 {
    如果需要獲取新的流 {
        客戶端發送命令 LTTNG_VIEWER_GET_NEW_STREAMS + 構造體 lttng_viewer_new_streams_request
        服務端返回構造體 lttng_viewer_new_streams_response + 指定長度的 lttng_viewer_stream
    }
    如果需要獲取新的元數據(metadata) {
        枚舉現存的metadata流列表 {
            客戶端發送命令 LTTNG_VIEWER_GET_METADATA + 構造體 lttng_viewer_get_metadata
            服務端返回構造體 lttng_viewer_metadata_packet + 指定長度的payload
        }
    }
    枚舉現存的trace流列表 {
        客戶端發送命令 LTTNG_VIEWER_GET_NEXT_INDEX + 構造體 lttng_viewer_get_next_index
        服務端返回構造體 lttng_viewer_index
        檢查返回的 index.flags, 如果服務端出現了新的流或者元數據, 需要先獲取新的流和元數據才可以繼續
        客戶端發送命令 LTTNG_VIEWER_GET_PACKET + 構造體 lttng_viewer_trace_packet
        服務端返回構造體 lttng_viewer_trace_packet + 指定長度的payload
        根據metadata packet和trace packet分析事件的內容然後記錄事件
    }
}

是不是覺得很複雜?
因為協議決定了服務端發給客戶端的數據沒有數據頭, 所以服務端不能主動推送數據到客戶端, 客戶端必須主動的去進行輪詢.
如果你註意到構造體的名稱, 會發現有的構造體後面有request和response而有的沒有, 如果不看上下文只看構造體的名稱很難猜到它們的作用.
正確的做法是所有請求和返回的構造體名稱末尾都添加request和response, 不要去省略這些字母而浪費思考的時間.

為了發送命令和接收構造體我寫了一些幫助函數, 它們並不複雜, 使用TCP交互的程式都會有類似的代碼:

int sendall(int fd, const void* buf, std::size_t size) {
    std::size_t pos = 0;
    while (pos < size) {
        auto ret = send(fd,
            reinterpret_cast<const char*>(buf) + pos, size - pos, 0);
        if (ret <= 0) {
            return -1;
        }
        pos += static_cast<std::size_t>(ret);
    }
    return 0;
}

int recvall(int fd, void* buf, std::size_t size) {
    std::size_t pos = 0;
    while (pos < size) {
        auto ret = recv(fd,
            reinterpret_cast<char*>(buf) + pos, size - pos, 0);
        if (ret <= 0) {
            return -1;
        }
        pos += static_cast<std::size_t>(ret);
    }
    return 0;
}

template <class T>
int sendcmd(int fd, std::uint32_t type, const T& body) {
    lttng_viewer_cmd cmd = {};
    cmd.data_size = htobe64(sizeof(T));
    cmd.cmd = htobe32(type);
    if (sendall(fd, &cmd, sizeof(cmd)) < 0) {
        return -1;
    }
    if (sendall(fd, &body, sizeof(body)) < 0) {
        return -1;
    }
    return 0;
}

初始化連接的代碼如下:

lttng_viewer_connect body = {};
body.major = htobe32(2);
body.minor = htobe32(9);
body.type = htobe32(LTTNG_VIEWER_CLIENT_COMMAND);
if (sendcmd(fd, LTTNG_VIEWER_CONNECT, body) < 0) {
    return -1;
}
if (recvall(fd, &body, sizeof(body)) < 0) {
    return -1;
}
viewer_session_id = be64toh(body.viewer_session_id);

後面的代碼比較枯燥我就省略了, 想看完整代碼的可以看這裡.

進入迴圈後會從lttng-relayd獲取兩種有用的數據:

  • 元數據(metadata), 定義了跟蹤數據的格式
  • 跟蹤數據(trace), 包含了事件信息例如GC開始和結束等

獲取元數據使用的是LTTNG_VIEWER_GET_METADATA命令, 獲取到的元數據內容如下:

Wu@"Jtf@oe/* CTF 1.8 */

typealias integer { size = 8; align = 8; signed = false; } := uint8_t;
typealias integer { size = 16; align = 8; signed = false; } := uint16_t;
typealias integer { size = 32; align = 8; signed = false; } := uint32_t;
typealias integer { size = 64; align = 8; signed = false; } := uint64_t;
typealias integer { size = 64; align = 8; signed = false; } := unsigned long;
typealias integer { size = 5; align = 1; signed = false; } := uint5_t;
typealias integer { size = 27; align = 1; signed = false; } := uint27_t;

trace {
    major = 1;
    minor = 8;
    uuid = "a3df4090-0722-4a74-97a4-81e066406f03";
    byte_order = le;
    packet.header := struct {
        uint32_t magic;
        uint8_t  uuid[16];
        uint32_t stream_id;
        uint64_t stream_instance_id;
    };
};

env {
    hostname = "ubuntu-virtual-machine";
    domain = "ust";
    tracer_name = "lttng-ust";
    tracer_major = 2;
    tracer_minor = 9;
};

clock {
    name = "monotonic";
    uuid = "f397e532-4837-402b-8cc9-700ed92a339d";
    description = "Monotonic Clock";
    freq = 1000000000; /* Frequency, in Hz */
    /* clock value offset from Epoch is: offset * (1/freq) */
    offset = 1514336042565610080;
};

typealias integer {
    size = 27; align = 1; signed = false;
    map = clock.monotonic.value;
} := uint27_clock_monotonic_t;

typealias integer {
    size = 32; align = 8; signed = false;
    map = clock.monotonic.value;
} := uint32_clock_monotonic_t;

typealias integer {
    size = 64; align = 8; signed = false;
    map = clock.monotonic.value;
} := uint64_clock_monotonic_t;

struct packet_context {
    uint64_clock_monotonic_t timestamp_begin;
    uint64_clock_monotonic_t timestamp_end;
    uint64_t content_size;
    uint64_t packet_size;
    uint64_t packet_seq_num;
    unsigned long events_discarded;
    uint32_t cpu_id;
};

struct event_header_compact {
    enum : uint5_t { compact = 0 ... 30, extended = 31 } id;
    variant <id> {
        struct {
            uint27_clock_monotonic_t timestamp;
        } compact;
        struct {
            uint32_t id;
            uint64_clock_monotonic_t timestamp;
        } extended;
    } v;
} align(8);

struct event_header_large {
    enum : uint16_t { compact = 0 ... 65534, extended = 65535 } id;
    variant <id> {
        struct {
            uint32_clock_monotonic_t timestamp;
        } compact;
        struct {
            uint32_t id;
            uint64_clock_monotonic_t timestamp;
        } extended;
    } v;
} align(8);

stream {
    id = 0;
    event.header := struct event_header_compact;
    packet.context := struct packet_context;
    event.context := struct {
        integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _vpid;
        integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _vtid;
    };
};

event {
    name = "DotNETRuntime:GCStart_V2";
    id = 0;
    stream_id = 0;
    loglevel = 13;
    fields := struct {
        integer { size = 32; align = 8; signed = 0; encoding = none; base = 10; } _Count;
        integer { size = 32; align = 8; signed = 0; encoding = none; base = 10; } _Depth;
        integer { size = 32; align = 8; signed = 0; encoding = none; base = 10; } _Reason;
        integer { size = 32; align = 8; signed = 0; encoding = none; base = 10; } _Type;
        integer { size = 16; align = 8; signed = 0; encoding = none; base = 10; } _ClrInstanceID;
        integer { size = 64; align = 8; signed = 0; encoding = none; base = 10; } _ClientSequenceNumber;
    };
};

這個元數據的格式是CTF Metadata, 這個格式看上去像json但是並不是, 是LTTng的公司自己創造的一個文本格式.
babeltrace中包含瞭解析這個文本格式的代碼, 但是沒有開放任何解析它的介面, 也就是如果你想自己解析只能寫一個詞法分析器.
這些格式其實可以使用json表示, 體積不會增加多少, 但是這公司硬是發明瞭一個新的格式增加使用者的負擔.
寫一個詞法分析器需要1天時間和1000行代碼, 這裡我就先跳過了.

接下來獲取跟蹤數據, 使用的是LTTNG_VIEWER_GET_NEXT_INDEX和LTTNG_VIEWER_GET_PACKET命令.
LTTNG_VIEWER_GET_NEXT_INDEX返回了當前流的offset和可獲取的content_size, 這裡的content_size單位是位(bit), 也就是需要除以8才可以算出可以獲取多少位元組,
關於content_size的單位LTTng中沒有任何文檔和註釋說明它是位, 只有一個測試代碼裡面的某行寫了/ CHAR_BIT.
使用LTTNG_VIEWER_GET_PACKET命令, 傳入offset和content_size/8可以獲取跟蹤數據(如果不/8會獲取到多餘的數據或者返回ERR).
實際返回的跟蹤數據如下:

000000: c1 1f fc c1 29 82 6b fe 24 10 4c 6b 97 91 4d c3  ....).k.$.Lk..M.
000010: ed d4 41 8f 00 00 00 00 03 00 00 00 00 00 00 00  ..A.............
000020: 92 91 49 96 08 0a 00 00 07 a0 58 b9 08 0a 00 00  ..I.......X.....
000030: 50 05 00 00 00 00 00 00 00 80 00 00 00 00 00 00  P...............
000040: 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
000050: 03 00 00 00 1f 00 00 00 00 92 91 49 96 08 0a 00  ...........I....
000060: 00 e1 1b 00 00 03 00 00 00 02 00 00 00 01 00 00  ................
000070: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 1f  ................
000080: 00 00 00 00 4d ae a7 af 08 0a 00 00 e1 1b 00 00  ....M...........
000090: 04 00 00 00 02 00 00 00 01 00 00 00 00 00 00 00  ................
0000a0: 00 00 00 00 00 00 00 00 00 00                    ..........

跟蹤數據的格式是CTF Stream Packet, 也是一個自定義的二進位格式, 需要配合元數據解析.
babeltrace中同樣沒有開放解析它的介面(有python binding但是沒有解析數據的函數), 也就是需要自己寫二進位數據解析器.

操作LTTng + 和relayd通訊 + 元數據詞法分析器 + 跟蹤數據解析器全部加起來預計需要2000行代碼, 而這一切使用ETW只用了100多行代碼.
糟糕的設計, 複雜的使用, 落後的文檔, 各種各樣的自定義協議和數據格式, 不提供SDK把LTTng打造成了一個比ETW更難用的跟蹤系統.
目前在github上LTTng只有100多星而babeltrace只有20多, 也印證了沒有多少人在用它們.
我不清楚為什麼CoreCLR要用LTTng, 但欣慰的是CoreCLR 2.1會有新的跟蹤機制EventPipe, 到時候可以更簡單的實現跨平臺捕獲CoreCLR跟蹤事件.

我目前寫的調用ETW的代碼放在了這裡, 調用LTTng的代碼放在了這裡, 有興趣的可以去參考.

教訓

最差的API(ETW)和更差的API(LTTng)都看過了, 那麼應該如何避免他們的錯誤, 編寫一個好的API呢?

Casey Muratori提到的教訓有:

設計API的第一條和第二條規則: "永遠都從編寫用例開始"

設計一個API時, 首先要做的是站在調用者的立場, 想想調用者需要什麼, 如何才能最簡單的達到這個需求.
編寫一個簡單的用例代碼永遠是設計API中必須的一步.
不要過多的去想內部實現, 如果內部實現機制讓API變得複雜, 應該想辦法去抽象它.

考慮到未來的擴展

因為需求會不斷變化, 設計API的時候應該為未來的變化預留空間, 保證向後相容性.
例如ETW中監聽的事件類型使用了位標記, 也就是參數是32位時最多只能有32種事件, 考慮到未來有更多事件應該把事件類型定義為連續的數值並提供額外的API啟用事件.
現在有很多介面在設計時會考慮到版本, 例如用v1和v2區分, 這是一個很好的策略.

明確介面的輸入和輸出

不要為了節省代碼去讓一個介面接收或者返回多餘的信息.
在ETW中很多介面都共用了一個大構造體EVENT_TRACE_PROPERTIES, 調用者很難搞清楚介面使用了構造體裡面的哪些值, 又影響了哪些值.
設計API時應該明確介面的目的, 讓介面接收和返回必要且最少的信息.

提供完整的示例代碼

對調用者來說, 100行的示例代碼通常比1000行的文檔更有意義.
因為介面的設計者和調用者擁有的知識量通常不對等, 調用者在沒有看到實際的例子之前, 很可能無法理解設計者編寫的文檔.

不要使用魔法數字

這是很多介面都會犯的錯誤, 例如ETW中決定事件附加的信息時, 1表示時間戳, 2表示系統時間, 3表示CPU周期計數.
如果你需要傳遞具有某種意義的數字給介面, 請務必在SDK中為該數字定義枚舉類型.

我從LTTng中吸收到的教訓有:

寫文檔

99%的調用者沒有看源代碼的興趣或者能力, 不寫文檔沒有人會懂得如何去調用你的介面.
現在有很多自動生成文檔的工具, 用這些工具可以減少很多的工作量, 但是你仍然應該手動去編寫一個入門的文檔.

不要輕易的去創造一個協議

創造一個新的協議意味著需要編寫新的代碼去解析它, 而且每個程式語言都要重新編寫一次.
除非你很有精力, 可以為主流的程式語言都提供一個SDK, 否則不推薦這樣做.
很多項目都提供了REST API, 這是很好的趨勢, 因為幾乎每個語言都有現成的類庫可以方便地調用REST API.

謹慎的去定義二進位協議

定義一個好的二進位協議需要很深的功力, LTTng定義的協議明顯考慮的太少.
推薦的做法是明確區分請求和回應, 請求和回應都應該有一個帶有長度的頭, 支持全雙工通信.
如果你想設計一個二進位協議, 強烈建議參考Cassandra資料庫的協議文檔, 這個協議無論是設計還是文檔都是一流的水平.
但是如果你沒有對傳輸性能有很苛刻的要求, 建議使用現成的協議加json或者xml.

不要去創造一個DSL(Domain-specific language)

這裡我沒有寫輕易, 如果你有一個數據結構需要表示成文本, 請使用更通用的格式.
LTTng表示元數據時使用了一個自己創造的DSL, 但裡面的內容用json表示也不會增加多少體積, 也就是說創造一個DSL沒有任何好處.
解析DSL需要自己編寫詞法分析器, 即使是經驗老道的程式員編寫一個也需要不少時間(包含單元測試更多), 如果使用json等通用格式那麼編寫解析的代碼只需要幾分鐘.

寫在最後

雖然這篇文章把LTTng批評了一番, 但這可能是目前全世界唯一一篇提到如何通過代碼調用LTTng和接收事件數據的文章.
希望看過這篇文章的設計API時多為調用者著想, 你偷懶省下幾分鐘往往會導致別人浪費幾天的時間.


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • 圖形的滾動及顏色區域的拉移
    首先準備兩個盒子： 再寫樣式： 最後是js代碼部分： 演示效果：http://localhost:63342/demo/work7.html ...
  • AngularJS路由使用案例
    AngularJS路由使用案例： javaee.html代碼： angularjs.html代碼： easyui.html代碼： mysql.html代碼： ...
  • 不可思議的混合模式 background-blend-mode
    本文接前文：不可思議的混合模式 mix-blend-mode 。由於 mix-blend-mode 這個屬性的強大，很多應用場景和動效的製作不斷完善和被髮掘出來，遂另起一文繼續介紹一些使用 mix-blend-mode 製作的酷炫動畫。 CSS3 新增了一個很有意思的屬性 -- mix-blend- ...
  • 前端MVC Vue2學習總結（二）——Vue的實例、生命周期與Vue腳手架（vue-cli）
    一、Vue的實例 1.1、創建一個 Vue 的實例 每個 Vue 應用都是通過 Vue 函數創建一個新的 Vue 實例開始的： 雖然沒有完全遵循 MVVM 模型，Vue 的設計無疑受到了它的啟發。因此在文檔中經常會使用 vm (ViewModel 的簡稱) 這個變數名錶示 Vue 實例。 1、vue ...
  • 雲計算應用開發演變
    Related links:https://12factor.net/https://serverless.com/http://microservices.io/--------------------------------------------------------------------... ...
  • 助力中小企業級連雲端，促進工業互聯網平臺蓬勃發展，全套解決方案。附：技術產品
    目錄 1.概述 2.總體方案 3.Super Link N1 一體化智能網關 4.ServerSuperIO物聯網通訊框架 5.SuperRTDB高性能實時資料庫 6.SuperView Web組態 7.行業領域應用 8.接入雲端 9.工業互聯網平臺 10．結束語 1．概述 經過兩年多團體的努力，四 ...
  • dubbo-monitor安裝監控中心，管理控制台安裝
    一、安裝監控中心 1、創建安裝目錄 2、解壓 上傳文件解壓文件 解壓 3、修改配置文件 4、啟動 如果一直出現點。只需要加大記憶體即可，記憶體至少大於1024，然後reboot重啟 5、測試 二、安裝管理控制台 上傳 1、 解壓tomcat、清空tomcat/webapps/ROOT 清空tomcat/ ...
  • 分散式系統的消息&服務模式簡單總結
    在一個分散式系統中，有各種消息的處理，有各種服務模式，有同步非同步，有高併發問題甚至應對高併發問題的Actor編程模型，本文嘗試對這些問題做一個簡單思考和總結。 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 QuestPDF 是一個開源 .NET 庫，用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫，它徹底改變了我們生成 PDF 文檔的方 ...
  • 彈幕樹洞項目功能新增篇
    項目地址 項目後端地址： https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址： ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址： http://tree ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類