OpenTelemetry

總之為了方便找問題，過往會自己寫的一些東西，想試試看用像是 Grafana 或 Jaeger 這些現成比較完整的解決方案來實現。要把程式中的狀態傳出來，目前主流會是 OpenTelemetry 這套，名詞很多一直忘記，因此做一些紀錄。

---

下面是 What is OpenTelemetry 的摘要:

OpenTelemetry 是一套專注在產生、收集、管理、匯出應用程式與系統遙測資料 (主要是: Trace, Metric, Log) 的框架與工具集，讓 instrument 應用程式與系統的過程儘量的簡單，在儘可能多的程式語言、運算基礎建設、執行環境等都可以運作。遙測資料的儲存與視覺化沒有包含在 OpenTelemetry 中，而是留給其他工具來實現。

構成 OpenTelemetry 的是以下元件:

1. A specification for all components.

   描述有哪些元件的規格，規格中說明包含名詞定義、各語言函式庫該有什麼功能、各遙測資訊的資料鍵值、有哪些通訊協定等資訊。

2. A standard protocol that defines the shape of telemetry data

   遙測資料的標準資料格式協定。

3. Semantic conventions that define a standard naming scheme for common telemetry data types.

   定義了常見遙測資料型別的標準命名規則的 Semantic conventions (semconv)。

4. APIs that define how to generate telemetry data.

   定義了怎麼產生遙測資料的 API。

5. Language SDKs that implement the specification, APIs, and export of telemetry data.

   實作了規格、API、匯出遙測資料等功能的各主流程式語言 SDK。

6. A library ecosystem that implements instrumentation for common libraries and frameworks.

   實作了對常見函式庫或框架進行 instrument 的函式庫生態系。

7. Automatic instrumentation components that generate telemetry data without requiring code changes.

   可以不用改程式碼就產生出遙測資料的自動化 instrument 元件。

8. The OpenTelemetry Collector, a proxy that receives, processes, and exports telemetry data.

   作為一個中間轉運站，對遙測資料進行接收、處理、匯出作業的 OpenTelemetry Collector。

9. Various other tools, such as the OpenTelemetry Operator for Kubernetes, OpenTelemetry Helm Charts, and community assets for FaaS.

   各種其他的工具。

OpenTelemetry 是設計為可以擴充的，以下是一些例子:

1. Adding a receiver to the OpenTelemetry Collector to support telemetry data from a custom source.

   增加 receiver 到 OpenTelemetry Collector 以便從客製化的遙測資料源收取資料。

2. Loading custom instrumentation libraries into an SDK.

   可以將客製化的 instrumentation 函式庫載入 SDK 使用。

3. Creating a distribution of an SDK or the Collector tailored to a specific use case.

   可以針對特定使用情境建立 SDK 或 Collector 的發布版本 (distribution)，不用 fork 整個或特定 OpenTelemetry 元件。

4. Creating a new exporter for a custom backend that doesn’t yet support the OpenTelemetry protocol (OTLP).

   如果有遙測資料處理系統還不支援 OTLP 的話，可以做一個 exporter 來將資料匯過去。

5. Creating a custom propagator for a nonstandard context propagation format.

   當碰到非標準的 context propagation 機制或格式時，可以製作客製的 propagator 來應對。

在 Angular Material 從 Moment.js 轉移到 Luxon

這幾年瀏覽器變很多，連帶的一些本來過去在 Library 做的功能在標準裡面都有相對的替代品，時間相關的部分像是時區以及顯示本地化部分也不例外。

另外就是實作上寫法的問題，現在的 Library 要能夠讓最佳化編譯器可以運作，以便減少下載傳輸量。

曾經處理時間首選就是 Moment.js 函式庫，但時代變了，在 Moment.js 的官網也貼出建議移轉的說明。

總之，雖然個人的 Web 前端是湊合著做，不求用到最新的技術。但是終於到了因為 Moment.js 不支援 tree-shaking 而沒辦法簡單無腦 ng update 的時候啊...

npm uninstall @angular/material-moment-adapter
npm uninstall moment
npm install --save luxon
npm install --save-dev @types/luxon
ng add @angular/material-luxon-adapter

程式的部分有相當多的變動，像是在 Luxon 所有物件都是不可變的，所以就不需要 clone 了。轉換日期時間為字串的 format token 也變不少，不過用 Google Gemini 轉效果不錯。

Linux 上應用程式利用使用者資料夾的標準

整個 Linux 作業系統怎麼安排檔案系統，有 Filesystem Hierarchy Standard (FHS) 作為參考標準，在使用者資料夾 (Home directory; ~/) 的部分，目前主要應該都是參考 XDG Base Directory 來放。

使用者設定: $XDG_CONFIG_HOME (~/.config/)

使用者為應用程式做的偏好設定。

使用者資料: $XDG_DATA_HOME (~/.local/share/)

存放類似書籤、憑證、郵件、金鑰等使用者操作應用程式所得到或產生的資料，期待資料格式應具備一定程度的可攜性，使用者可能會想要備份這些資料。

應用程式狀態: $XDG_STATE_HOME (~/.local/state/)

存放像是執行紀錄 (log) 檔、最近存取資料的紀錄、視窗最後位置等，可以用在應用程式啟動時初始狀態的資料，使用者備份這些資料可能沒有太多意義。

使用者自行安裝的程式: ~/.local/bin/

各 distribution 應該自動的在這個資料夾存在時，把他加到使用者的 $PATH 環境變數中。

雖然沒有那麼常見，但最好可以考慮使用者資料夾可能會在不同處理器架構的主機間共用的情形。

規格中另外有定義一些環境變數，用來指定搜尋資料的順序。

在 WSL 2 上掛載 USB disk

如果要在 WSL 2 (Windows Subsystem for Linux) 掛載在 Linux 格式 (EXT4, XFS ... etc.) 的 USB 外接磁碟，可以先試試看這篇 Mount a Linux disk in WSL 2 說的方法，萬一不行再去試 Connect USB devices 的方式。

雖然第一篇說該方法針對的是內部儲存裝置，外接式裝置無法支援，但我自己在 Windows 11 (23H2; build 22631) 試是可以的。反而透過 USBIPD 的方式，因為 WSL 提供的 kernel 沒有包含 USB mass storage 的驅動程式，雖然 lsusb 看得到裝置，但是沒辦法掛載起來使用。

Markdown

目前都是基於 CommonMark 上面再去增加語法或限制，疊在 CommonMark 上面新增的規格稱為 extension。

Extension 在函式庫看起來作法大概是這樣:

1. 解析部份目前都是產生 AST 再去生成輸出，大概有兩種讓 extension 介入解析的方式:
   1. 讓 extension 實作註冊關注的字元，再去觸發解析與 AST 加工。
   2. 掃出來的 AST 整個讓 extension 實作再去解析與加工。
2. 完成 AST 之後再進行 render 來產生輸出，看起來多半是讓 extension 註冊處理所屬 token 型別的輸出函式，在 render 時呼叫來處理生成輸出的作業。

直接從 Markdown 產生 HTML 的方式因為比較難擴充的關係，即使有機會比較快，但現在看起來比較不流行了。

Ref:

• GitHub (GFM) 的規格: https://github.github.com/gfm/
• Visual Studio Code 用的引擎: https://github.com/markdown-it/markdown-it
• CommonMark: https://spec.commonmark.org/
• Go: https://github.com/gomarkdown/markdown
• Go: https://gitlab.com/golang-commonmark/markdown
• 規格的範例本身可以當成 test suite: https://github.com/commonmark/commonmark-spec
• 在 CommonMark.org 首頁提到的 test suite: https://github.com/michelf/mdtest
• Markdown Guide 有一些最佳建議實踐與常見的 extension 使用說明: https://www.markdownguide.org/
• GFM 規格發表公告，有說明所謂「移轉到 CommonMark 上」的背景: https://github.blog/2017-03-14-a-formal-spec-for-github-markdown/

Linux 上的 load average 怎麼解釋？

在 Linux 或是大多數的 UNIX-like 的系統上，系統核心 (kernel) 會提供一組稱為 load average 的值，用來反應系統負載狀態。

這組值原則上是基於工作佇列中的工作數量與工作特性權重去計算出來，可以說是在等待資源中的工作數量，系統會提供 1, 5, 15 分鐘的平均值。

以 Linux 來說，納入考量的資源包含了處理器、被分頁置換的記憶體、儲存設備、網路介面等等，因此在 Linux 上 load average 可以說是一個綜合性的指標，可以相當程度的反映出程式分享設備資源的狀況。

舉例來說，如果這個值是 2.00 的話，可以想像成有兩個工作正在等待資源，換句話說，這些等待中的工作所需要的資源目前是完全使用中的。

系統中多半會有許多程式在運行，他們會因為程式本身設計的目的使用不同的資源，因此 load average 也一定程度可以反映出工作組合在特定主機設備上的狀況。

比如說，如果主機上的工作是類似資料庫或是需要大量存取檔案的應用程式，由於儲存設備相對處理器與記憶體多半是相對慢的，工作勢必是需要做一些等待來得到資料，所以在偏高的 load average 下整體而言還是可以有不錯的處理能力 (throughput) 表現。

但如果是使用處理器為主的應用程式，那麼偏高的 load average 就意味著有工作在進行單純的等待，在這個情況下如果處理能力不符合需求的話，可以考慮是不是做一些硬體資源的調整來提升處理能力。

利用這樣的特性，我們也可以透過監視 load average 來偵測到系統的工作組合是不是發生了變化。比如要是遭到了勒索軟體的入侵，由於勒索軟體會進行大量的儲存裝置操作，那麼 load average 就會衝到比平常還高的數值上。

Ref:

• Wikipedia: Load (computing)
• Monitoring CPU Utilization on Red Hat Enterprise Linux
• Linux Load Averages: Solving the Mystery
• Linux 核心設計: Load average

Visual Studio Code 無法識別 PATH_MAX 或 realpath

利用 Visual Studio Code 寫 C/C++ 程式時，發現一些系統定義或是函數被畫了無法識別的紅色波浪 (red squiggly line) 在下面，但是真的編譯程式又會過。

原因是那些定義被放在 feature test macros (FTM) 的後面，當沒有特別給像是 -ansi, -std=c17 之類的參數時 gcc 預設會定義 _DEFAULT_SOURCE 巨集，因此編譯可以順利進行。但是 vscode 的解析器似乎是比照給了 -std=c17 之類的參數，因此這些 Linux 上特有的常數或函數定義就不會被抓到。

解決方法就是在 .vscode/c_cpp_properties.json 的 defines 區塊中，加上 _DEFAULT_SOURCE=1 或是 _XOPEN_SOURCE=700 來把 Linux 上的常數或函數定義納入。或是，為求慎重的話，也可以看函數的 man page 裡面所描述的 feature test macros 需求，來決定要怎麼設定。

Ref:

• vscode: c_cpp_properties.json reference
• glibc: Feature test macros (GNU C Library)
• man7: feature_test_macros(7)