六小編 Editor Leon

Fluent Bit 收集 Log

2026-02-16T00:00:00+00:00

Fluent Bit</a> 是主流的 log 收集器之一，典型的用法是收到 log 後再轉發給下一手，廣義的說它不只收 log，也收 metric 等其他資料，這裡直接引用 Fluent Bit 網站的概念圖：

發 log 就發 log，為什麼要過一手 Fluent Bit？以我自己而言，每個服務的 log 會集中到 CloudWatch，對於自己寫的程式這沒什麼問題，但對於像是 Traefik、Caddy、Nginx 這類被廣泛使用的服務，它們並不原生支援 CloudWatch，偏偏 web server 的 log 對於稽核或安全方面的分析又很重要，以 Fluent Bit 來收集並轉發就成為主流的解決方案之一。

雖然 AWS 有出 CloudWatch Agent</a>，但我覺得它的目的太過單一、有侷限性，要是哪天想跳槽離開 AWS，又要匆匆忙忙連滾帶爬把它換掉，相較之下支援多輸入／多輸出的 Fluent Bit 是更泛用的選擇。

選用 Fluent Bit 的另一個理由是 Docker logging driver 原生支援 Forward 協議</a>，而 Forward 協議</a>正是 Fluent Bit 團隊開發的，因此採用 Fluent Bit 成為理所當然的選項之一，之所以說「之一」，是因為其他收集器也大多支援 Forward，主流的選手有：

Vector</a>：大廠 DataDog 出的收集器</li> </ul>

幾乎每款收集器都標榜自己輕巧不吃資源、處理 log 快吞吐又快、支援各式各樣輸入／輸出，看起來都差不多的情況下挑一套自己看得順眼的就好，也有些人跑了他們之間的評比 benchmark，有的 A 好有的 B 好，參考就好。

配置 Fluent Bit</h2>

在使用前必須先寫 Fluent Bit 的配置文件，這裡我們採用較新的 YAML</a> 配置文件，下面是一份簡單的配置文件：

service</span>:</span></span>
  # Log_Level</span></span>
  # =========</span></span>
  # Set the verbosity level of the service, values can be:</span></span>
  #</span></span>
  # - error</span></span>
  # - warning</span></span>
  # - info</span></span>
  # - debug</span></span>
  # - trace</span></span>
  #</span></span>
  # by default 'info' is set, that means it includes 'error' and 'warning'.</span></span>
  # log_level: info</span></span>
</span>
  # Parsers File</span></span>
  # ============</span></span>
  # specify an optional 'Parsers' configuration file</span></span>
  parsers_file</span>:</span> parsers.conf</span></span>
</span>
  # Plugins File</span></span>
  # ============</span></span>
  # specify an optional 'Plugins' configuration file to load external plugins.</span></span>
  plugins_file</span>:</span> plugins.conf</span></span>
</span>
pipeline</span>:</span></span>
  inputs</span>:</span></span>
    -</span> name</span>:</span> forward</span></span>
      port</span>:</span> 24224</span></span>
</span>
  outputs</span>:</span></span>
    -</span> name</span>:</span> stdout</span></span>
      match</span>:</span> "*"</span></span>
</span>
    -</span> name</span>:</span> cloudwatch_logs</span></span>
      match</span>:</span> "*"</span></span>
      region</span>:</span> ${AWS_DEFAULT_REGION}</span></span>
      log_group_name</span>:</span> ${LOG_GROUP_NAME}</span></span></code></pre>
能夠望文生義的部分就不提，其中 service</code> 區塊是配置 Fluent Bit 本身，旗下的 parsers_file</code>、.plugins_file` 兩項指定的檔案不用自己生，都存在現成的 Fluent Bit 映像內。</p>
Pipeline 指的是資料的輸入、處理、輸出的流程，這裡我們不對資料做處理，所以只有 inputs</code> 與 outputs</code>。</p>
前面提到 Docker logging driver 支援 Forward 協議輸出 log，在 Fluent Bit 這邊，就要設定收 Forward log 的 input</a>，設定 input 識別名 forward</code> 與 port 24224 就可以了，非常簡單。</p>
Output 的話就是 stdout 和 CloudWatch，stdout output</a> 的識別名就是 stdout</code>，match: "*"</code> 就是不比對（不過濾）。</p>
CloudWatch output</a> 配置項目比較多一點，但也滿好懂，其中 region</code> 與 log_group_name</code> 的值取自 OS 環境變數。</p>
要打資料給 AWS CloudWatch 還需要 AWS 認證，最簡單的方法是在 OS 環境變數中就設好 AWS_ACCESS_KEY_ID</code> 與 AWS_SECRET_ACCESS_KEY</code>，CloutWatch output 會自己使用，或者是讓運行 Fluent Bit 的 EC2 本身就有具備 CloudWatch permission 的 IAM role，要採用哪種取決於你有多追求把安全性無限上綱以及有多想被 AWS vendor-lock。</p>
配置完存成檔名 fluent-bit.yaml，接著來搞容器。</p>
容器 log 到 Fluent Bit</h2>
前面提過，自己寫的服務多半可以利用 AWS SDK 直接把 log 打給 CloudWatch，所以我們關注的重點放在怎麼把 Traefik log 打給 Fluent Bit 再打給 CloudWatch。</p>
先看 compose.yaml：</p>
services</span>:</span></span>
  fluent-bit</span>:</span></span>
    image</span>:</span> cr.fluentbit.io/fluent/fluent-bit:4.2</span></span>
    restart</span>:</span> unless-stopped</span></span>
    ports</span>:</span></span>
      -</span> "24224:24224"</span> # Forward protocal</span></span>
    volumes</span>:</span></span>
      -</span> ./fluent-bit-data/fluent-bit.yaml:/fluent-bit/etc/fluent-bit.yaml</span></span>
    command</span>:</span></span>
      -</span> /fluent-bit/bin/fluent-bit</span></span>
      -</span> --config=/fluent-bit/etc/fluent-bit.yaml</span></span>
    environment</span>:</span></span>
      -</span> AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION}</span></span>
      -</span> AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}</span></span>
      -</span> AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}</span></span>
</span>
  traefik</span>:</span></span>
    image</span>:</span> traefik:v3.6</span></span>
    restart</span>:</span> unless-stopped</span></span>
    security_opt</span>:</span></span>
      -</span> no-new-privileges=true</span></span>
    ports</span>:</span></span>
      -</span> "80:80"</span></span>
      -</span> "443:443"</span></span>
      -</span> "443:443/udp"</span></span>
    logging</span>:</span></span>
      driver</span>:</span> fluentd</span></span>
      options</span>:</span></span>
        fluentd-address</span>:</span> 127.0.0.1:24224</span> # macOS: host.docker.internal:24224</span></span>
        fluentd-async</span>:</span> 'true'</span></span>
        tag</span>:</span> traefik</span></span></code></pre>
這份 compose.yaml 只保留我們關注的重點，省略其他元素。</p>
在 Fluent Bit 方面，我們把前面的 fluent-bit.yaml 掛載進容器內，並自訂 command 讓 Fluent Bit 讀取之。</p>
在 Traefik 方面，我們啟用 Fluentd logging driver</a>，它本質上就是支援 Forward 協議的 logging driver。</p>
前面提到，Fluent Bit 的 Forward input 的 port 為 24224，而 Traefik 的 fluentd-address</code> 不能填 Docker container network 的位址，所以我們把 fluent-bit:24224 映射到實體素主機的 24224，Traefik 的 fluentd-address</code> 則填入 127.0.0.1:24224</code>，如此方可讓 Traefik log 送到 Fluent Bit，如果宿主機是 Mac，那又多了一層 Docker VM，所以得改成 host.docker.internal:24224</code>。</p>
fluent-bit</code> 服務作為非主要之週邊服務，它不應成為其他服務的依賴，不應列入其他服務的 depends_on</code>，所以啟用 fluentd-async</code> 來讓 Traefik 能自行啟動並送出 log，不需要關心 Fluent Bit 啟用與否。</p>
至此一套具體而微的 Fluent Bit ＋ Traefik 系統就配置完成了，一套組合拳下來，Traefik log 輸出到容器的 stdout / stderr，然後由 Docker logging driver 轉發給 Fluent Bit，再轉發給 CloudWatch，一筆筆 log 就這麼風塵僕僕的抵達了 CloudWatch。</p>


怎麼算有小數點的錢？
2025-06-15T00:00:00+00:00
離上篇文過去了半年，連載再開！</p>
台幣最小到元，在我小時候還見過五角的台幣，查了一下維基百科，實際上五角還是有效貨幣，不過實務上沒人用就是了，總之，雖然台灣交易一般算到元，不過其實帶有小數點的金額還發生在不同的角落，例如：</p>

B2B 交易，供應商報價有可能有小數點。</li>
營業稅前金額，也有可能有小數點。</li>
別國貨幣，也可能有角、分等，用元為單位的話也會有小數點。</li>
油價，例如每公升 26.6 元。</li>
通話費，例如每秒 0.05 元。</li>
充電費，與通話費類似，例如每小時 10 元，以分計費會是每分鐘 0.166667 元。</li>
</ul>
比較討厭的是時間計價，因為時間是 60 進位，換算成較細的單位後很容易遇到無窮小數問題。</p>
對於電腦算錢，特別是有小數點的錢，如果不特別處理的話，一定會遇到浮點誤差，對於錢這麼重要的數字，誤差是不被允許的，那什麼是浮點誤差？</p>
浮點誤差</h2>
先看實際問題：</p>
>>></span> 0.1</span> +</span> 0.2</span></span>
0.30000000000000004</span></span></code></pre>
0.1 加 0.2 竟然不是 0.3，很違背常理，但就這麼發生了。</p>
用最簡單的話說，電腦底層是二進位，而一般帶有小數的十進位數字在轉換為二進位制時會出現無限循環，但電腦容量有限只能截斷，截斷後的二進位再轉回十進位時就會出現誤差。</p>
就像 1/3 以十進位表示是 0.3333… 無窮小數一樣，十進位制 0.1 轉為二進位制會是 0.0001100110011…，再轉回十進位制時就不再是 0.1：</p>
>>></span> 0.1</span></span>
0.1</span></span>
</span>
>>></span> format</span>(</span>0.1</span>,</span> '.17f'</span>)</span></span>
'0.10000000000000001'</span></span></code></pre>
上面程式碼中，一般情況下，Python 在顯示值時會幫我們「美化」，0.1 就是 0.1，但實際上，對 Python 而言，真正的值是不是精確的 0.1，而僅是近似值。再看 0.3 的例子：</p>
>>></span> 0.3</span></span>
0.3</span></span>
</span>
>>></span> format</span>(</span>0.3</span>,</span> '.17f'</span>)</span></span>
'0.29999999999999999'</span></span>
</span>
>>></span> 0.1</span> +</span> 0.2</span></span>
0.30000000000000004</span></span>
</span>
>>></span> 0.1</span> +</span> 0.2</span> ==</span> 0.3</span></span>
False</span></span></code></pre>
可以看到，對電腦來說 0.3 不是 0.3，0.1 + 0.2 也不是 0.3，是不是很逆天？</p>
由於以上種種，所以江湖上流傳一句話「算錢用浮點，遲早被人扁」。</p>
對於浮點誤差比較簡明的解釋，可以看 Python 的這份文件〈浮點數運算：問題與限制</a>〉。</p>
Floating Point Math</a> 展示了各種語言 0.1 + 0.2 的結果。</p>
解決浮點誤差</h2>
第一招——不用小數</h3>
解決浮點誤差的第一種思路是用更小的單位算錢，因為十進制二進制轉換誤差只發生在小數點，那不用小數點總可以了吧，我用「分」算錢總可以了吧。</p>
因為浮點誤差在多次運算中都會各自產生並累積，這個方案是在運算與儲存都以「分」為單位，只在最終顯示時才轉為以「元」表示。</p>
但要注意的是，浮點誤差也會發生在資料庫，所以這招也得在儲存時以「分」儲存金額，如果資料庫又給其他應用或報表提供資料，它們也得以「分」計算並以「元」顯示。如果是大應用，有多個資料庫與子應用，很容易會精神錯亂，這邊忘記除以一百，那邊忘記乘以一百，或是欄位 A 是分，欄位 B 是元等狀況。</p>
第二招——Decimal</h3>
儘管大部分程式語言都有浮點誤差問題，但它們也都提供了類似的解決方案——decimal，不論是內建或外裝，大多程式語言都有個 decimal 工具，例如 decimal.js</a> 或是 Python 內建的 decimal</a> 模組。</p>
最基礎的 decimal 用法：</p>
>>> from</span> decimal</span> import</span> Decimal</span></span>
</span>
>>></span> Decimal(</span>'3.14'</span>)</span></span>
Decimal(</span>'3.14'</span>)</span></span></code></pre>
這個 3.14 就是 3.14，不會是 3.1401 也不會是 3.1399。</p>
要注意的是，建立 Decimal</code> 物件最好餵字串而不是數字，如果餵數字的話：</p>
>>></span> Decimal(</span>3.14</span>)</span></span>
Decimal(</span>'3.140000000000000124344978758017532527446746826171875'</span>)</span></span></code></pre>
Python 會以已經發生浮點誤差的數字建立 Decimal</code> 物件，而這當然與我們的預期不符。</p>
Decimal</code> 物件可以直接與另一個 Decimal</code> 物件或整數做算數運算，但不能和浮點數做運算：</p>
>>></span> Decimal(</span>'3.14'</span>)</span> +</span> Decimal(</span>'1.618'</span>)</span></span>
Decimal(</span>'4.758'</span>)</span></span>
</span>
>>></span> Decimal(</span>'2'</span>)</span> +</span> 3</span></span>
Decimal(</span>'5'</span>)</span></span>
</span>
>>></span> Decimal(</span>'3'</span>)</span> +</span> 1.618</span></span>
# TypeError: unsupported operand type(s) for +: 'decimal.Decimal' and 'float'</span></span></code></pre>
Decimal 模組還可以依需求設定小數位數與進退位規則，在程式內我們會盡可能保有全部小數點，採取高精度運算，但最後秀給用戶的值可能只秀到小數點三位，甚至只秀整數，就可以利用 quantize()</code> 方法與 ROUND_HALF_UP</code> 做四捨五入：</p>
>>> from</span> decimal</span> import</span> Decimal,</span> ROUND_HALF_UP</span></span>
</span>
>>></span> total_cost</span> =</span> Decimal(</span>'3.1415927'</span>)</span></span>
>>></span> total_cost.quantize(</span>exp</span>=</span>Decimal(</span>'0.001'</span>),</span> rounding</span>=</span>ROUND_HALF_UP</span>)</span></span>
Decimal(</span>'3.142'</span>)</span></span></code></pre>
餵給 quantize()</code> 的 exp</code> 參數也是一個 Deciaml</code> 物件，表示我們想要的位數，而第二個參數望文生義就是進退位規則啦，ROUND_HALF_UP</code> 表示四捨五入，另外也有無條件進位、無條件捨去等規則。</p>
前面說到電腦底層是以二進位制處理數字，那 decimal 是怎麼解決浮點誤差的呢？其實它也是用上第一招，全部改為整數就好，不過相對於我們自幹的土炮方式，decimal 設計的更周全，除了可以自定位數、進退位規則外，decimal</a> 還有好多其他特性，並且我們不用自己操煩單位換算的工作，省心省力。</p>
Decimal 唯一的缺點是慢，因為它以整數形態儲存數值，並且還要額外的空間存放小數位數、正負號等資訊，相較於以浮點運算器加速的原生浮點數，decimal 顯然要慢得多了，幸好這種慢在體感上並不明顯，特別是在講究數字精確性的應用中，慢這麼一點點更顯得微不足道。</p>
在儲存方面，各大資料庫也有提供相同的 DECIMAL 或 NUMERIC 型別，它們提供與上述 decimal 相似的特性，所以簡單的說，像錢這樣重要又可能帶小數的數字，不管是在應用層還是資料層，最好都用 decimal 來處理，從此再也沒有出門被人扁的風險。</p>
無窮小數問題</h2>
前面提到的浮點誤差，來自十進位制與二進位制轉換時的無限循環，然而除此之外，有一些數字本身就是無窮小數，例如 1/3 = 0.3333…。</p>
以高功率充電樁為例，以時間計價一分鐘 28 元，即便在表面上是以分計費，但在系統實作層面，為了提供不同充電站業者足夠大的彈性，還是可能得精算到秒，以免哪個歐洲客戶想以 30 秒計費，或者要做階梯費率什麼的。</p>
總之，以秒計費的話，一秒 28/60 元，相當於 0.046666… 元，這種本身就是無窮小數的狀況就不能靠 decimal 了，Python 有為此開立特別處方 fractions</a> 模組，與 decimal 狀況類似，JS 也有 fraction.js</a> 可供使用。</p>
Fraction</h3>
建立 Fraction</code> 物件就是為給它分子、分母：</p>
>>> from</span> fractions</span> import</span> Fraction</span></span>
</span>
>>></span> Fraction(</span>1</span>,</span> 3</span>)</span></span>
Fraction(</span>1</span>,</span> 3</span>)</span></span></code></pre>
Fraction(1, 3)</code> 表示分數 1/3。</p>
與 decimal 類似，如果有小數，最好以字串形式餵入，避免浮點誤差：</p>
>>></span> Fraction(</span>1.1</span>)</span></span>
Fraction(</span>2476979795053773</span>,</span> 2251799813685248</span>)</span></span>
</span>
>>></span> Fraction(</span>'1.1'</span>)</span></span>
Fraction(</span>11</span>,</span> 10</span>)</span></span></code></pre>
在這個例子裡沒餵分母，分母會是 1，就是分數 1.1/1。</p>
要做運算的話，其他運算元最好也是 Fraction</code> 或整數物件，如果其他運算元是浮點數的話，那結果會變成不精確的浮點數：</p>
>>></span> Fraction(</span>28</span>,</span> 60</span>)</span> *</span> 0.5</span></span>
0.23333333333333334</span></span>
</span>
>>></span> Fraction(</span>28</span>,</span> 60</span>)</span> *</span> Fraction(</span>'0.5'</span>)</span></span>
Fraction(</span>7</span>,</span> 30</span>)</span></span></code></pre>
Fraction 與 decimal 用起來頗相似，也一樣有較慢的問題，但也一樣體感不明顯，是追求數字正確時可接受的慢。</p>
與 decimal 不同的是，資料庫沒有類似 fraction 的型別，可以考慮轉成 decimal 儲存，或是如果需要追求極度精確的話，以字串儲存：</p>
>>></span> str</span>(Fraction(</span>7</span>,</span> 30</span>))</span></span>
'7/30'</span></span></code></pre>
算錢大概就這樣，祝大家數錢數到手抽筋 💸。</p>


如何在 macOS 掛載 ext4
2024-12-25T00:00:00+00:00
上禮拜主要工作的桌機突然掛掉，經過一番交叉測試，應該是主機板掛了，還好還有筆電，接上大螢幕還可以繼續工作，程式專案的部分有遠端 Git 庫存不怕掉檔案，但其他一些文件、相片就要想辦法讀出來了，macOS 讀 Windows 的 exFAT、NTFS 沒問題，反倒是不支援 ext4，這點令人感到意外，調查一波後發現，macOS 要掛上 ext4 並不簡單，要抉擇用哪些工具鏈，還要自行編譯，自己曲曲折折走對一條路後寫下這篇筆記。</p>
macOS 原生不支援 ext4，當插入 ext4 硬碟，系統可以認得有硬碟插入，在磁碟工具程式可以看見它以及分配的設備編號（例如 disk4s1），但無法掛載，我們需要利用 FUSE</a> 機制來掛載它。</p>
在 macOS 世界，FUSE 底層套件有兩個選擇，傳統的 macFUSE</a>（= OSXFUSE = Fuse4X）使用 macOS 核心擴充機制（KEXT），KEXT 已經逐漸被淘汰</a>，所以我選用無 KEXT 成分的 FUSE-T</a>，FUSE-T 是以 NFS 的方式掛載，讓 ext4 或其他檔案系統變成一個假的網路硬碟。</p>
要把整套工具搭起來需要：</p>

Xcode command line tools，內含 Git、make 等開發工具。</li>
Homebrew，macOS 世界的套件管理器。</li>
FUSE-T，FUSE 底層套件。</li>
pkg-config，編譯 ext4fuse 所需工具。</li>
ext4fuse，掛載 ext4 硬碟工具。</li>
</ul>
Xcode command line tools</h2>
一行安裝：</p>
$</span> xcode-select</span> --install</span></span></code></pre>
裝完就有 Git 和 make 可用了。</p>
Homebrew</h2>
Homebrew</a> 是 macOS 世界的套件管理器，它也可以在 Linux 工作，只不過沒什麼人用罷了，Linux 早有 APT 等主流套件管理器了，Homebrew 安裝請參見它的文件。</p>
FUSE-T</h2>
有了 Homebrew，安裝 FUSE-T 就很簡單了：</p>
$</span> brew install macos-fuse-t/homebrew-cask/fuse-t</span></span></code></pre>
裝完它會在 /usr/local/lib/ 內，另外 /usr/local/lib/pkgconfig/fuse-t.pc 為 FUSE-T 的 pkg-config 配置檔，內容如下：</p>
prefix=/usr/local</span></span>
exec_prefix=${prefix}</span></span>
libdir=${prefix}/lib</span></span>
includedir=${prefix}/include/fuse</span></span>
</span>
Name: fuse-t</span></span>
Description: Userspace FUSE implementation for macOS</span></span>
Version: 1.0.44</span></span>
Libs:  -L${libdir} -Wl,-rpath,${libdir} -lfuse-t</span></span>
Cflags: -I${includedir}</span></span></code></pre>
不論是 macFUSE 或 FUSE-T，他們都是 FUSE 機制的底層套件，具體要掛載 ext4 或其他檔案系統，還要另外安裝各自套件，後續我們需要 ext4fuse，並且還需要自行編譯。</p>
編譯 ext4fuse 需要引用 FUSE-T 的 fuse.h，根據上面的定義，fuse.h 應該位在 includedir</code> 變數位置，也就是 /usr/local/include/fuse/ 內，而 fuse.h 及其他源碼在專案 libfuse</a> 內，我們把它 clone 下來：</p>
$</span> git clone https://github.com/macos-fuse-t/libfuse</span></span></code></pre>
然後把 libfuse/include/ 所有檔案複製到 /usr/local/include/fuse/ 內：</p>
$</span> sudo mkdir /usr/local/include</span></span>
$</span> sudo mkdir /usr/local/include/fuse</span></span>
$</span> sudo cp</span> -R</span> ~/Projects/libfuse/include/</span>*</span> /usr/local/include/fuse/</span></span></code></pre>
至此前置備料完成一半，另一半是裝 pkg-config。</p>
pkg-config</h2>
pkg-config 是編譯期間的相依套件管理工具，前面我們已經備好 FUSE-T 的 pkg-config 配置以及源碼，但還需要安裝 pkg-config 工具本身，為了避免落入編譯輪迴地獄，這裡我們用速成方式一行搞定：</p>
$</span> brew install pkgconf</span></span></code></pre>
pkgconf</a> 是與 pkg-confg 相同，重新發明的輪子，具體差異為何不深究，總之安裝很間單。</p>
至此備料完畢，總算可以編譯了。</p>
ext4fuse</h2>
ext4fuse 是掛載 ext4 硬碟工具，注意它只能讀不能寫。</p>
ext4fuse 編譯時需要引用 fuse.h，而因為我們用的是 FUSE-T，因此這 fuse.h 也必須是 FUSE-T 的 fuse.h，這句話出現了六次「fuse」，看來頗令人困惑，總之就是 ext4fuse 也要選用 FUSE-T 的修改版，首先把它 clone 下來，注意網址中間是「macos-fues-t」：</p>
$</span> git clone https://github.com/macos-fuse-t/ext4fuse</span></span></code></pre>
然後跑 make：</p>
$</span> make</span></span></code></pre>
下面出現一陣幾哩呱啦，警告什麼的，先無視，編譯完，專案資料夾內應該會出現一支執行檔 ext4fuse，終於我們可以掛上 ext4 了：</p>
$</span> mkdir ~/ext4_mount</span></span>
$</span> sudo ./ext4fuse /dev/disk4s1 ~/ext4_mount</span> -o</span> allow_other</span></span></code></pre>
此時在 Finder 應該就可以看到掛上去的 ext4 了，賀 🎉。</p>
用完卸載：</p>
$</span> sudo umount ~/ext4_mount</span></span></code></pre>
如果卸載失敗，就先關電腦，再拔 ext4 硬碟，這樣比較安全。</p>


重新認識異步
2024-12-01T00:00:00+00:00
異步是 Python 3.4 起引入的重大變革，透過 asyncio 模組與新的 async</code>、await</code> 語法達到與 JavaScript 類似的異步執行效果，這篇寫一下異步的用法與特性。</p>
一個最簡單的異步程式例子：</p>
import</span> asyncio</span></span>
</span>
async def</span> main</span>():</span></span>
    print</span>(</span>'hello'</span>)</span></span>
    await</span> asyncio.sleep(</span>10</span>)</span></span>
    print</span>(</span>'world'</span>)</span></span>
</span>
if</span> __name__</span> ==</span> '__main__'</span>:</span></span>
    asyncio.run(main())</span></span></code></pre>
在上面的例子內有幾個 Python 異步程式的特徵：</p>

由 async</code> 關鍵字定義 main()</code> 為異步函式。</li>
函式內有 await</code> 關鍵字的敘述句表示該敘述為異步執行。</li>
await</code> 後呼叫的函式 asyncio.sleep()</code> 為一個具有 awaitable 的函式，對 await</code> 關鍵字來說，後面呼叫的函式有 awaitable 屬性是必須的，否則會引發錯誤。</li>
asyncio.run()</code> 負責把 main()</code> 丟進 event loop 執行。</li>
</ul>
協程與 event loop</h2>
如果我們直接跑那個 async 定義的 main()</code>，Python 會告訴我們此函式它生成一個 coroutine（協程）物件，並且因為沒有 asyncio 模組幫忙把它丟給 event loop，此時函式不會被執行：</p>
main()</span></span>
<</span>coroutine</span> object</span> main at</span> 0x</span>1053bb7c8</span>></span></span></code></pre>
從這裡我們可以瞭解到，async 函式會生成 coroutine（協程）物件，它們是反應物與生成物的關係，口語上，我們比較常講「async 函式」，實際上，在 event loop 中被執行的是生成的 coroutine 物件，書面上或口語上可以把它們等而視之。</p>
Event loop</a> 接受並調度一系列的 async 函式（嚴謹的說是協程物件）。不像上面簡化的例子，在真實的場景中，往往有多個工作需要並行前進，例如某個 API 後端，要一邊持續收 message queue 訊息，一邊要回應客戶端請求，又例如要並行下載多個檔案等等，這類涉及網路 IO 與磁碟 IO 的任務統稱為 IO-bound 任務，IO-bound 特性是 IO 存取頻繁，而 CPU 運算強度不高，如同 asyncio 名字所表示，它特別適合處理 IO-bound 類並行任務，反之如果是 CPU-bound 或 GPU-bound 這類運算密集型任務，例如算圖、音訊、視訊、影像處理，則比較適合用多進程解決，發揮 CPU 多核心的特長，或是調用 GPU 運算函式庫處理，當然也有某些應用場景可能既是 IO-bound 又是 CPU-bound 也是 GPU-bound，那它就會同時用上多進程多線程 asyncio + CUDA。</p>
Python event loop 的一項特性是一個線程只能跑一個 event loop，event loop 不能跨線程，但是如上段結尾所提，我可以開很多個線程，每個線程都跑自己的 event loop，當然，要玩多進程又多線程還要跑 asyncio / event loop，就很考驗我們的調度能力了。</p>
async / await</h2>
回到上文程式範例，event loop 會自行調度每個協程任務，無需人為介入，執行 await asyncio.sleep(10)</code> 語句時，如果在這個 event loop 中還有其他協程任務時，睡著的這十秒並不會阻塞其他協程任務進行，在睡覺期間，event loop 會叫起別的協程任務運行，如此達到並行運算的效果。</p>
然而因為 await</code> 的關係，Python 會確保下一句 print('world')</code> 在睡完後再執行，因為我們還是要求程式是有序執行的嘛，如果程式主要邏輯變成這樣：</p>
await</span> asyncio.sleep(</span>10</span>)</span></span>
await</span> asyncio.sleep(</span>10</span>)</span></span></code></pre>
那 Python 會睡幾秒？答案是二十秒，它們並沒有「並行睡十秒」，這似乎和前文說的並行運算有所違背，癥結就在那個 await</code>，它保證了程式執行的有序性，問題來了，既然有序，又如何並行？</p>
TaskGroup</h2>
從 Python 3.11 起，對於並行協程，引入了 task group 方案，在此之前，什麼 asyncio.create_task()</code>、asyncio.gather()</code> 等等的招式在此不提，task group 跑並行協程範例如下，這次我們用比較實際的（假裝）並行下載示範：</p>
import</span> asyncio</span></span>
</span>
async def</span> download</span>(url:</span> str</span>, sleep_duration:</span> int</span>):</span></span>
  await</span> asyncio.sleep(sleep_duration)</span></span>
  print</span>(url)</span></span>
  return</span> url</span></span>
</span>
url1</span> =</span> 'task1'</span></span>
url2</span> =</span> 'task2'</span></span>
</span>
async def</span> main</span>():</span></span>
  async with</span> asyncio.TaskGroup()</span> as</span> tg:</span></span>
    task1</span> =</span> tg.create_task(download(url1,</span> 10</span>))</span></span>
    task2</span> =</span> tg.create_task(download(url2,</span> 3</span>))</span></span>
    task1_result</span> = await</span> task1</span></span>
    task2_result</span> = await</span> task2</span></span>
    print</span>(</span>'All done'</span>)</span></span>
  return</span> (task1_result, task2_result)</span></span>
</span>
if</span> __name__</span> ==</span> '__main__'</span>:</span></span>
    asyncio.run(main())</span></span></code></pre>
輸出為：</p>
task2</span></span>
task1</span></span>
All done</span></span></code></pre>
並且此時總時長為 10 秒，不是 13 秒。</p>
來認識一下 task group：</p>


async with xxx</code> 啟動了異步的 context，而 asyncio.TaskGroup()</code> 本身就是異步 context 的生成器，它負責實作異步 context 要求的 aenter()</code> 與 aexit()</code>，如同一般的 context 生成器一樣，只不過前綴了 a</code> 表示 async，異步 context 裡面理所當然的可以執行 await xxx()</code>。</p>
</li>

task1 = tg.create_task(download(url1, 10))</code> 這句會生成一個 Task</code> 物件，這也是 event loop 的管理對象，一個 coroutine 可以顯式或隱式的被封裝成 Task</code> 物件，然後交由 event loop 管理與執行，這裡我們需要關注的是 Task</code> 物件一旦生成就立刻被執行，因此 task1</code> 與 task2</code> 兩者幾乎是同時執行，也就是並行。</p>
</li>

await task1</code> 用於取得 task1</code> 的回傳值，如上點所說 task1</code> 本身不是函式，它是個 Task</code> 物件，所以是 await task1</code>，後面不用加括號。await xxx</code> 在這裡不影響兩個任務的進行順序，如上點所說，它們在各自建立為 Task</code> 物件時就已經執行了，所以我們看到先輸出的是只睡三秒的 task2 而不是先 await</code> 的 task1。</p>
</li>
</ul>
Task</code> 是 asyncio 的一個類，顧名思義，就是任務。前面定義的異步函式、coroutine 物件都需要被顯式</strong>的或隱式</strong>的轉換成 Task</code> 物件才能交給 event loop 去運行，Task</code> 物件可以是一份任務，或者是 N 份任務的清單。</p>
透過 create_task()</code> 去運行多個任務，就可以做到並行的效果。</p>
再舉個實際例子，某個專案要訂閱 MQTT 訊息，把訊息轉入 MongoDB job queue，又要跑 job worker，還要透過 ZeroMQ 把 job 處理結果丟出去，這麼多事摻在一起，至少有兩個無限迴圈要跑：</p>

監看 queue job 的 job worker</li>
監聽 MQTT 訊息的訂閱器</li>
</ul>
此專案啟動範例如下：</p>
import</span> mongodb</span></span>
import</span> mqtt</span></span>
import</span> zeromq</span></span>
</span>
async def</span> main</span>():</span></span>
  # 先連接到 MongoDB</span></span>
  await</span> mongodb.initialize()</span></span>
        </span></span>
  # 再綁定 ZeroMQ</span></span>
  await</span> zeromq.bind_address()</span></span>
</span>
  async with</span> asyncio.TaskGroup()</span> as</span> tg:</span></span>
    # 跑 MongoDB job queue worker</span></span>
    tg.create_task(job_queue.run())</span></span>
    </span></span>
    # 監聽 MQTT 訂閱訊息</span></span>
    tg.create_task(mqtt.listen())</span></span>
</span>
if</span> __name__</span> ==</span> '__main__'</span>:</span></span>
    asyncio.run(main())</span></span></code></pre>
主函式裡面透過 await xxx</code> 確保了會先連線到 MongoDB 與綁定 ZeroMQ，才會去跑後面的 task group，而 task group 內跑 job worker 與接收 MQTT 訊息則是並行發生的，如此保證了該有序執行的有序執行，該並行運行的並行運行。</p>
結語</h2>
其實用上 asyncio 很多時候是因為被套件所逼，一旦某套件說它得異步調用，那我們就得一路 async</code> / await</code> 下去，而 asyncio 對 IO-bound 工作究竟有沒有神奇的功效，目前說法莫衷一是，畢竟每個評價方式都不一樣，無論如何 asyncio 還是要用上的，等 Python GIL 封印解除，就可以到達提速五倍的境界了吧。</p>


前端權限檢查 CASL
2024-08-15T00:00:00+00:00
本頻道之前寫過後端存取控制套件 Vakt</a> 與 Oso</a>，這篇則來談談前端部份的權限檢查機制。</p>
還是快速介紹一下常見的存取控制模式 RBAC 與 ABAC。</p>
RBAC 全稱 role-based access control，以「角色」為基礎的權限控制，最常見的例子就是 Admin，不論我的帳號為何，只要被賦予了 Admin 角色，我就能做任何事。</p>
相對於權限霸總 Admin，另一個角色 User 就弱小得多，通常只能讀取、查詢，不能異動資料，大多新帳號建立之初被賦予的就是 User 角色。</p>
ABAC 全稱 attribute-based access control，它是較細粒度的存取控制模式，組織 A 旗下的用戶只能看到組織 A 的資料，看不到組織 B 的資料。</p>
之所以能作到這些 XXAC，除了靠自己寫出很巢的 if</code> 邏輯外，最好還是利用專門的套件來幫我們制定以及執行檢查邏輯。</p>
在之前的文章談到後端存取控制，在前端這邊，好像可以沿用但又不完全一樣，舉個例子，前端的主選單完全與後端無關，Admin 角色登入可以看到用戶管理，別的角色看不到，或者 Admin 在畫面上多了幾顆超能力按鈕，別的角色看不到，即便後端也制定了只有 Admin 能對用戶帳號增刪改，別人做就吐 403 Forbidden，但這不表示前端可以大剌剌把那些超能力選單、按鈕都放出來給大家看，而這些超能力選單、按鈕又是 UI 層的東西，與後端的權限規則不直接相關，所以無法避免的前端得有自己的一套權限制定與檢查機制，這裡我們選用 CASL。</p>
CASL</h2>
CASL</a>（唸作 /ˈkæsəl/</code>）是 JavaScript 的存取控制套件，起手式當然是先安裝：</p>
$</span> npm install @casl/ability</span></span></code></pre>
最最最簡單的用法：</p>
// ability.ts</span></span>
</span>
import</span> { defineAbility }</span> from</span> '@casl/ability'</span></span>
</span>
const</span> abilityFor</span> =</span> (</span>roles</span>:</span> string</span>[])</span> =></span> defineAbility</span>((</span>can</span>)</span> =></span> {</span></span>
    if</span> (roles.</span>includes</span>(</span>'Admin'</span>)) {</span></span>
        can</span>(</span>'see menu item'</span>,</span> 'UsersMenu'</span>)</span></span>
        can</span>(</span>'see menu item'</span>,</span> 'SystemMenu'</span>)</span></span>
        can</span>(</span>'delete'</span>,</span> 'SystemLog'</span>)</span></span>
    }</span></span>
})</span></span>
</span>
export default</span> abilityFor</span></span></code></pre>
這段程式的核心方法是 defineAbility()</code> 與 can()</code>，前者顧名思義就是﹍define ability﹍，而那 can()</code> 的第一個參數是「幹什麼」，第二個參數是「對什麼」，就上例而言，只有 Admin 能：</p>

見到用戶管理選單</li>
見到系統設定選單</li>
刪除系統紀錄</li>
</ul>
當然這些只是規則，真正要用得呼叫它：</p>
// app.ts</span></span>
</span>
import</span> { abilityFor }</span> from</span> '@/ability'</span></span>
</span>
def</span> getUserRoles</span>() {</span> return</span> [</span>'admin'</span>] }</span></span>
</span>
const</span> roles</span> =</span> getUserRoles</span>()</span></span>
</span>
const</span> ability</span> =</span> abilityFor</span>(roles)</span></span>
</span>
const</span> menusItems</span>:</span> MenuOptions</span>[]</span> =</span> [</span></span>
    { label:</span> 'home'</span>, name:</span> '首頁'</span>, icon: House, route:</span> '/'</span> },</span></span>
    { label:</span> 'transaction'</span>, name:</span> '交易清單'</span>, icon: List, route:</span> '/transactions'</span>, },</span></span>
]</span></span>
if</span> (ability.</span>can</span>(</span>'see menu item'</span>,</span> 'UsersMenu'</span>)) {</span> // true</span></span>
    menusItems.</span>push</span>({ label:</span> 'user'</span>, name:</span> '用戶管理'</span>, icon: Users, route:</span> '/users'</span> })</span></span>
}</span></span></code></pre>
我們先呼叫 abilityFor()</code>，餵它當前用戶角色，做出 ability</code> 物件，然後呼叫 ability.can()</code> 確認是否可行，注意這裡的 ability.can()</code> 不同於制定規則時的 can()</code>，這裡的 ability.can()</code> 用於檢查行為與對象有沒有准許。</p>
因為範例中的角色是 Admin，當然是准許啦，就這樣 Admin 登入就可以看到用戶管理選單囉，反之，如果不是 Admin，拿到的答案會是 false</code>，選單也就不可見囉。</p>
不可見歸不可見，如果有個反派他手動打網址進 /users 該怎麼辦？舉一反三一下，先制定規則，然後在前端路由程式那邊一樣呼叫 ability.can()</code> 來確認就好，拿到 False</code> 就把他擋掉。</p>
對於現代化，具反應性、資料綁定的前端生態，例如 Vue.js，可以把那 const ability = abilityFor(roles)</code> 放到 Pinia store 裡面，如此可以達到跨頁面使用，省去一直重複生成 ability</code> 物件的工作，像我是弄個 authStore</code>，所有與認證、授權有關的物件與方法都在裡面，大概長這樣：</p>
import</span> abilityFor</span> from</span> '@/ability'</span></span>
import</span> { defineStore }</span> from</span> 'pinia'</span></span>
import</span> { computed, ref }</span> from</span> 'vue'</span></span>
</span>
export const</span> useAuthStore</span> =</span> defineStore</span>(</span></span>
  // id</span></span>
  'auth'</span>,</span></span>
</span>
  // storeSetup</span></span>
  ()</span> =></span> {</span></span>
    // States</span></span>
    const</span> token</span> =</span> ref</span><</span>Token</span>>()</span></span>
</span>
    // Getters</span></span>
    const</span> payload</span> =</span> computed</span>(()</span> =></span> {</span> return</span> token.value.payload })</span></span>
    const</span> ability</span> =</span> computed</span>(()</span> =></span> {</span></span>
      return</span> abilityFor</span>(payload.value?.roles)</span></span>
    })</span></span>
</span>
    // Actions</span></span>
    async function</span> signIn</span>() { }</span></span>
    async function</span> refresh</span>() { }</span></span>
    function</span> signOut</span>() { }</span></span>
</span>
    // return states, getters, actions</span></span>
    return</span> { token, payload, ability, signIn, refresh, signOut }</span></span>
  },</span></span>
)</span></span></code></pre>
如此一來，只要用戶登出換帳號登入，就會拿到新的 token，也就會拿到新的角色，也就會拿到只屬於自己的 ability.can()</code> 答案了。</p>
本文只介紹 CASL 最簡單的用法與概念，它能做的還多得多，不過簡單的版本已經能滿足一些粗粒度需求，其他以後有遇到再說吧。</p>


權限檢查利器 Vakt
2024-08-13T00:00:00+00:00
之前寫過一篇〈存取控制與 Oso</a>〉，一段時間下來也沒什麼不好，就是始終不適應 Oso 那獨家的權限規則語法 Polar，最近又偶然發現了 Vakt</a>，看起來它有可能成為 Oso 的替代品，就讓我來開箱一下吧。</p>
Vakt 意思是挪威語的 guard。</p>
與 Oso 一樣 Vakt 也是權限檢查套件，對於現代化應用，常見的權限模式有 RBAC</a>，以「角色」基礎的權限管理模式，例如班長能批假單，如此以角色為中心做權限規則制定，不以一個個帳號去制定，畢竟角色應該是有限的，而帳號很有可能是無限的。</p>
另一種典型的權限模式為 ABAC</a>，它是更細化的權限管理模式，沿用上面的案例，不僅班長必須是班長，ABAC 還限制只有 A 班班長能批 A 班假單，B 班班長能批 B 班假單，化為程式碼大概長這樣：</p>
if</span> account_s.role</span> ==</span> 'TEAM-LEADER'</span>:</span></span>
    if</span> account_s.team_id</span> ==</span> application_form.account.team_id:</span></span>
        return</span> True</span></span></code></pre>
類似的案例還有很多，像是作者 A 的貼文不能給 B 修改，但是網站編輯能修改所有作者的文，並且發佈權也在編輯手上。</p>
像這樣零零碎碎的規則，想用 if</code> 硬幹到底很有可能出錯，更好的方式是拿 Vakt 這類專門的規則引擎</a>來替我們運算到底是 pass 還是 out。</p>

繼續閱讀</a>
</p>



存取控制與 Oso
2024-08-12T00:00:00+00:00

Oso</a>（西班牙文的「熊」）是跨語言、跨框架的存取控制服務，它也有開源套件，本文主要介紹它的開源套件。</p>
在進入 Oso 前，先簡單認識一下存取控制。</p>
存取控制</h2>
「存取控制」英文叫 access control，市場上有許多不同的存取控制模型，他們的縮寫大多是 xAC，是 xxx access control 的意思。</p>
存取控制是多人系統必備的要素之一，例如常見的 WordPress，它內建了幾個預先定義好的角色：</p>
</p>
如圖所見，每個角色的能執行的權限不同，而每個帳號必定要賦予一個角色，形成「帳號—角色」這樣的關係，每個角色能執行的項目不同，例如編輯、管理員才能刪除文章，但除了這種系統面的權限外，每篇文章也有自身的權限，例如Ａ作者不能改Ｂ作者的文章。</p>
像 WordPress 這樣，以角色為基礎的存取控制模型，我們稱為「RBAC（role-based access control）</a>」。</p>
RBAC 的概念是以角色為中心的，也就是批假單的權限是綁在店長這個角色身上，而不是綁在王小臻身上，王小臻之所以能批假單，是因為她被賦予了店長的角色。</p>
除了 RBAC 外，視系統的應用場景和複雜度不同還有其他的 xAC，未來有遇到再說，畫面先交還給棚內的 Oso。</p>
Oso 簡介</h2>
一般要做一個 RBAC 機制，有可能自幹，但秉持著不要重新發明輪子的原則，還是交給專業的來吧！</p>
快速帶過 Oso 的特點：</p>

跨平台，Python、Rust、Node.js、Ruby、Go、Java，這算跨很大了吧。</li>
Oso 開發了一種專門用於制定安全政策的語言 Polar，加上 Oso 本身又是跨平台的，因此 Oso 這層存取控制可以與系統語言、框架本身作一定程度的分離</strong>，避免炒出義大利麵。</li>
角色與權限應用的對象可以細至「資源」，可以做到像 WP 那樣Ａ不能改Ｂ的文章。</li>
背後有商業化服務，不用擔心哪天作者跑路或被腰斬。</strong>（請不要舉冨樫當反例謝謝）</li>
</ul>

繼續閱讀</a>
</p>



從 pyee 認識觀察者模式
2024-06-24T00:00:00+00:00
這個站成立這麼久，終於出現一篇談設計模式的文了，代表我的人生進階了嗎？（沒有。）</p>
最近遇到一個需求，當某類物件狀態發生變化時，要有三四個模組被通知到，並且各自做出反應。</p>
講得更具體一點，一個多管道社群貼文發布系統，它的核心功能是，一則訊息在系統內發出後，要發到 Twitter、Facebook、Instagram 等外部社群，當不採取觀察者模式時，程式碼大概會長這樣：</p>
# twitter.py</span></span>
def</span> publish_to_twitter</span>(post_content:</span> str</span>):</span> ...</span></span>
</span>
</span>
# facebook.py</span></span>
def</span> publish_to_facebook</span>(post_content:</span> str</span>):</span> ...</span></span>
</span>
</span>
# instagram.py</span></span>
def</span> publish_to_instagram</span>(post_content:</span> str</span>):</span> ...</span></span>
</span>
</span>
# main.py</span></span>
@router.post</span>(</span>'/posts/publish'</span>)</span></span>
def</span> publish</span>(post_content:</span> str</span>):</span></span>
    publish_to_twitter(post_content)</span></span>
    publish_to_facebook(post_content)</span></span>
    publish_to_instagram(post_content)</span></span></code></pre>
然而隨著社群型態的豐富，或者隨著業務需求擴展，要覆蓋的社群越來越多，例如 Mastodon、Threads、Plurk、LinkedIn、MeWe、Gab 等等，為了滿這些需求，上面的 publish_to_xxx()</code> 也得越來越長，另外，除了發貼文外，也還有其他行為，像是偷改貼文、偷刪貼文等等，這些都是社群小編普遍需要的功能，也因此，除了好長的 publish_to_xxx()</code> 外，還有好長的 update_to_xxx()</code>、delete_from_xxx()</code>，每個動作下面接的函式都又冗又長，這種時候，就可考慮採用 pyee 與觀察者模式讓應用內的模組解耦，使模組間的邊界更清晰。</p>
pyee</h2>
pyee</a> 的「ee」表示 event emitter，名字與特性都取自 Node.js 的 event emitter 模組，顧名思義，它的主要特性就是事件發送與處理，下面我們邊用邊認識 pyee。</p>
延續上面的案例，採用 pyee 後，上面的程式碼變這樣：</p>
# event.py</span></span>
from</span> pyee</span> import</span> EventEmitter</span></span>
ee</span> =</span> EventEmitter()</span></span>
</span>
@ee.on</span>(</span>'error'</span>)</span></span>
def</span> on_error</span>(</span>*</span>args,</span> **</span>kwargs):</span></span>
    logger.error({</span>'event'</span>:</span> 'error'</span>,</span> 'args'</span>: args,</span> 'kwargs'</span>: kwargs})</span></span>
</span>
</span>
# mastodon.py</span></span>
from</span> event</span> import</span> ee</span></span>
@ee.on</span>(</span>'publishing'</span>)</span></span>
def</span> publish_to_mastodon</span>(post_content:</span> str</span>,</span> *</span>args,</span> **</span>kwargs):</span> ...</span></span>
</span>
</span>
# threads.py</span></span>
from</span> event</span> import</span> ee</span></span>
@ee.on</span>(</span>'publishing'</span>)</span></span>
def</span> publish_to_threads</span>(post_content:</span> str</span>,</span> *</span>args,</span> **</span>kwargs):</span> ...</span></span>
</span>
</span>
# xxx.py</span></span>
from</span> event</span> import</span> ee</span></span>
@ee.on</span>(</span>'publishing'</span>)</span></span>
def</span> publish_to_xxx</span>(post_content:</span> str</span>,</span> *</span>args,</span> **</span>kwargs):</span> ...</span></span>
</span>
</span>
# main.py</span></span>
from</span> event</span> import</span> ee</span></span>
@router.post</span>(</span>'/posts/publish'</span>)</span></span>
def</span> publish</span>(post_content:</span> str</span>):</span></span>
    ee.emit(</span>'publishing'</span>,</span> post_content</span>=</span>post_content)</span></span></code></pre>

我們先在 event.py 建立一個 EventEmitter</code> 實例 ee</code>，它是事件發布與事件處理函式的主角。</li>
然後我們在各個社群模組中透過裝飾器 @ee.on('publishing')</code> 註冊當 publishing 事件發生時，各模組的處理函式。</li>
在我們自己的 API 端點，收到客戶端的發布請求後，透過 ee</code> 發射 publishing 事件，如此先前註冊的那些處理函式就會逐個執行。</li>
另外 event.py 還有個 error 事件觀察者，這個 error 事件是事件處理器發生例外時，pyee 自己會發出的事件</li>
</ul>
在 pyee 的設計裡，一個事件可以有多個處理器，它們是依序被呼叫的，當一個事件的處理器發生沒捕捉的例外，也沒有在 error 處理器這邊處理的話，那這個事件的後續其它處理器也就此中斷了。</p>
上面的範例都是傳統的同步函式，而 pyee 也有異步的 pyee.asyncio.AsyncIOEventEmitter</code> 可以使用，如果事件處理器是帶有 async</code> 前綴的異步函式，那就得用 AsyncIOEventEmitter</code> 才能正確工作囉，而即便是異步，事件處理函式依然是依序被呼叫的，所以前面的規則依然適用。</p>
pyee 本身還有提供一些管理 API 為我們所用，參照下面程式碼：</p>
from</span> pyee.asyncio</span> import</span> AsyncIOEventEmitter</span></span>
ee</span> =</span> EventEmitter()</span></span>
</span>
# 列出所有觀察者觀察的事件</span></span>
ee.event_names()</span> # ['publishing', 'updating', 'deletion', ...]</span></span>
</span>
# 列出一個事件的觀察者</span></span>
ee.listeners(</span>'publishing'</span>)</span> # [mastodon.publish_to_mastodon, ...]</span></span></code></pre>
在 pyee 的加持下，就算未來有更多新興社群，主程式也都不需要再改，它一律發出同樣的 publishing 事件，各個社群只要自行向 ee</code> 註冊自己的事件處理器就好，如此主程式與那些社群串接模組就解除了依賴與耦合，這樣他們各自的邊界是不是更清晰了呢。</p>
模組邊界清晰對多人開發的好處是顯而易見的，負責處理主要邏輯的同事和負責串接 Mastodon 的同事再也不會互相改到彼此的模組，滿足了我輩資訊人莫名對解耦的追求。</p>
觀察者模式</h2>
回頭談觀察者模式，在上面的例子中，那些被 @ee.on()</code> 裝飾器註冊的函式我們稱為觀察者，他們會觀察 event emitter 發出的事件，如果是他們所關心的事件，他們就會接手處理，所以我們也可以叫他們事件處理器，從底層的觀點看，其實這都是 EventEmitter</code> 在背後幫我們呼叫那些處理器工作，所謂觀察者是從高層次的觀點給的命名，其實函式還是函式，哪會觀察什麼東西。</p>
前面我們以 pyee 與 publishing 事件舉例觀察者模式的應用，同樣的模式也可以套用在其他事件上，像是 updating、deletion，想得更廣一點，其他應用也有它可以發揮的地方，例如：</p>

WMS 系統的發料單的行為與狀態變化事件，像是 created、approved、picked、issued 等等。</li>
MES 系統的工單行為與狀態變化事件，像是 created、approved、scheduled、in-progress、finishing 等等。</li>
充電系統的行為與狀態變化事件，像是 available、preparing、charging、suspended、finishing、reserved、unavailable、faulted 等等。</li>
</ul>
這些狀態變化可能來自用戶請求、程式邏輯，或來自狀態機，總之狀態變更只要牽涉到其他模組需要做出對應的動作，這種時候觀察者模式就是我們的好朋友。</p>
其它有點像又不一樣的設計模式</h2>
觀察者模式適用的場景在應用內，隨場景不同，還可以考慮其他類似的設計模式：</p>

發布－訂閱模式（pub / sub pattern），相較於觀察者模式，發布－訂閱模式會依賴一個獨立的訊息代理器（message broker），例如 MQTT 就是此模式下的典型協議，多個服務間不直接通信，而是各自對訊息代理器發布或訂閱關注的主題（topic），如此也解耦了服務間的依賴，但相對的每個服務都依賴於訊息代理器，也就是說訊息代理器本身最好是高可用的，這意味系統複雜度與成本的提升。</li>
調度器模式（dispatcher pattern），在觀察者模式中，event emitter 只負責針對事件呼叫處理器，職責相對單純，而調度器模式中的調度器的職責較重，它主動針對事件做處理與呼叫，它所呼叫的事件處理器並不像觀察者模式中需要先註冊自己關注的事件，哪個事件該怎麼處理、該派給誰處理的職責都交給調度器主理。</li>
Hook 模式，此模式下應用內會預先定義好幾個 hook 點，其他模組可以向系統註冊自己的 hook callback 函式，當應用跑到 hook 點時，會去跑已註冊的 hook callback 函式，然後再回到主程式繼續後面的計算，例如可以事先定義一個名為 save_post</code> 的 hook 點，當儲存貼文時，其他的 save_post</code> hook callback 函式會被呼叫，跑一些自己的邏輯，然後再回到主程式，hook 模式大多用於外掛、擴展機制，例如 WordPress、pytest、pluggy</a> 都是以 hook 為基礎給第三方發展外掛。</li>
</ul>


初探 OpenTelemetry 與 APM
2024-04-01T00:00:00+00:00
這篇介紹 OpenTelemetry 的概念與應用，首先來認識一下這字「telemetry」，華文翻為遙測或遠測，維基百科有很簡短的解釋：</p>

遠測是指傳感器在測量現場收集測量對象的數據後，數據通過無線傳輸（例如無線電、超聲波或紅外線）、電話或計算機網絡、簡訊和 GSM 等各種方式傳送至遠距離的接收設備以供監測人員監測。</p>
</blockquote>
簡單說就是監測，OpenTelemetry 是一套公定的監測標準，也是一套框架，用於監測應用、系統的性能指標。以粒度來看，它小到可以監測系統內每個函式的反應時間，大到可以監測一台實體或虛擬機的資源使用率，以往在跑負載測試</a>時，我們是從外部視角去檢視應用在負載下的性能表現，但難以深入應用內部找到更具體的性能瓶頸，而 OpenTelemetry 搭配 APM 就能更好的知道自身應用具體是塞車在哪個端點，或者哪個函式。</p>
OpenTelemetry 是一套公定標準，許多廠商以這個標準為基礎開發產品，這類產品統稱為 APM，全稱 applicatoin performance monitoring / applicatoin performance management，這類產品除了主要的性能監測外，大多還有額外的附加功能，例如通知、儀表板等，市場上 APM 產品有開源的也有閉源的，因為本篇沒有業者贊助，就不特別幫他們打廣告了，開源的選擇看來看去比較有名的（或者說 SEO 做得比較好的）有二：</p>

SigNoz</a></li>
Uptrace</a></li>
</ul>
個人是選用 SigNoz，理由很簡單，裝起來用看看沒什麼問題就繼續用下去，也懶得再折騰其他，雖然產品選擇眾多，但以 OpenTelemetry 為基礎的 APM 的概念都是相同的。</p>
花式架構</h2>
由於微服務模式興起，OpenTelemetry 為了要能適用於大單體與微服務，OpenTelemetry 本身也變成能翻玩成各種花式架構的形式，一種最簡單的形式如下：</p>
---
displayMode: compact
---
flowchart TB
    app["App"]
    apm["APM"]

    app -- "OTLP" --> apm
</pre>
我們手上的 app 直接把監測資訊打給 APM，這裡的 OTLP 是 OpenTelemetry Protocol 的縮寫，我們無須深究 OTLP 技術細節（除非你的產品就是 APM），許多語言或框架都有現成的 OpenTelemetry 整合套件可以直接使用，這部份後面會再提到。</p>
在更實際的情境中，除了應用層的監控，我們也會想監控主機層的資源耗用狀況，為此我們需要一個專門的 collector，於是架構變成這樣：</p>
---
displayMode: compact
---
flowchart TB
    app["App"]
    collector["OTel Collector"]
    apm["APM"]

    subgraph machine["Machine"]
        app
        collector
    end

    app -- "OTLP" --> collector -- "OTLP" --> apm
</pre>
Collector 是一個獨立的程式，它會蒐集自己機身上以及別人打給它的監測資料，然後轉發出去，</p>
Collector 是可以共用的，假設有另外一個服務跑在別人家的 serverless 平台上，我們只關心自家服務的性能，不關心底層資源的話，也可以把服務監測資訊打到另一個 collector，由一個 collector 統包，轉發給 APM：</p>
---
displayMode: compact
---
flowchart TB
    app["App"]
    collector["OTel Collector"]
    apm["APM"]


    subgraph machine["Machine"]
        app
        collector
    end

    service["Service"]

    subgraph serverless["Serverless"]
        service
    end


    app -- "OTLP" --> collector
    service -- "OTLP" --> collector
    collector -- "OTLP" --> apm
</pre>
至此我們認識了 OpenTelemetry 的架構以及三個主要角色：我們自己的 app、現成的 APM 產品、現成的 collector，接著我們先把現成的 APM 和 collector 裝起來，最後再把自家 app 裝上監測器。</p>
SigNoz APM</h2>
SigNoz 是以 OpenTelemetry 為基礎的 APM，它可以以 Docker 容器或 K8s Helm Chart 的形式架設，這裡用簡單的 Docker 容器形式。</p>
準備一台裝好 Docker 的機器，把 SigNoz Git 抓下來：</p>
git</span> clone</span> -b</span> main https://github.com/SigNoz/signoz.git</span></span></code></pre>
它裡面有安裝腳本：</p>
./signoz/deploy/install.sh</span></span></code></pre>
跑起來，它會抓映像，跑容器，一波進度條跑完，SigNoz 應該就跑起來了。</p>
假設這台機器的 IP 是 192.168.16.14，那麼 SigNoz 的網頁入口就在 http://192.168.16.14:3301，打開網頁，依照畫面指示建立一個帳號，至此 SigNoz 就裝好了。</p>
上面的安裝腳本也附帶跑了一款範例應用 HotROD</a>，透過這款範例應用以及它的監測資料，我們可以自由探索體驗一下 SigNoz 的功能。</p>
在 SigNoz 的設定頁可以設定資料保存週期，可以依自己的儲存空間量與資料產生量來決定。</p>
等到後面我們自己的應用裝設好監測，HotROD 就可以無情地拋棄了，要關掉 HotROD 也很簡單，找到 SigNoz Docker Compose 檔案，在 deploy/docker/clickhouse-setup/docker-compose.yaml，把裡面的 services.hotrod 與 services.load-hotrod 區塊註解掉，然後再跑一次安裝腳本就好：</p>
./signoz/deploy/install.sh</span></span></code></pre>OpenTelemetry Collector</h2>
在 OpenTelemetry 體系內，Collector 負責接收、處理、匯出資料。</p>
Collector 安裝形式也是多元的，這裡我們以系統套件方式安裝，打包好的 OpenTelemetry Collector 系統套件可以在它的 GitHub 專案頁面</a>下載，裡面可以看到它的包分為兩大類：</p>

以 otecol 開頭，沒有 contrib 字樣</strong>。</li>
otecol-contrib 開頭，有 contrib 字樣</strong>。</li>
</ul>
兩者的差異在有 contrib</strong> 字樣的有另外包入一些附加元件，大部份情況下我們都選用帶 contrib 字樣的套件。</p>
假設另一台跑 app 和 OpenTelemetry Collector 的機器是 Ubuntu，就下載 otelcol-contrib_x.y.z_linux_amd64.deb，抓完把它裝起來。</p>
裝完之後，OpenTelemetry Collector 會成為一個系統服務，配置檔在 /etc/otelcol-contrib/config.yaml。</p>
OpenTelemetry Collector 的配置也非常花式，甚至有點像天書，幸好 SigNoz 有提供現成的範本可以抄，把 SigNoz 提供的 Collector 配置範本</a>抓下來，配置項目頗多，目前我們先關心如何把 Collector 收到的資料丟給 APM，找到以下區段，填入 APM 機台 IP：</p>
exporters</span>:</span></span>
  otlp</span>:</span></span>
    endpoint</span>:</span> "<IP of machine hosting SigNoz>:4317"</span></span>
    tls</span>:</span></span>
      insecure</span>:</span> true</span></span></code></pre>
這個 exporters</code> 區段顧名思義用於配置與輸出資料有關的項目，OpenTelemetry Collector 企圖作為資料的統包仲介，因此它被設計成模組化、可擴充的，由幾塊元件構成：</p>

receiver：收資料</li>
processor：處理資料</li>
exporter：輸出資料</li>
connector：接收與輸出資料</li>
extension：不經手資料的其它擴充功能</li>
</ul>
這些元件的性質大概認識就好，有需要再深入了解，它們都是可以被程式化擴充或配置的，前面裝的帶有 contrib 字樣的套件就是幫我們包好許多子元件模組的大禮包。</p>
回頭看配置檔的 receivers</code> 區段：</p>
receivers</span>:</span></span>
  otlp</span>:</span></span>
    protocols</span>:</span></span>
      grpc</span>:</span></span>
        endpoint</span>:</span> 0.0.0.0:4317</span></span>
      http</span>:</span></span>
        endpoint</span>:</span> 0.0.0.0:4318</span></span>
  hostmetrics</span>:</span></span>
    collection_interval</span>:</span> 30s</span></span>
    scrapers</span>:</span></span>
      cpu</span>: {}</span></span>
      disk</span>: {}</span></span>
      load</span>: {}</span></span>
      filesystem</span>: {}</span></span>
      memory</span>: {}</span></span>
      network</span>: {}</span></span>
      paging</span>: {}</span></span>
      process</span>:</span></span>
        mute_process_name_error</span>:</span> true</span></span>
        mute_process_exe_error</span>:</span> true</span></span>
        mute_process_io_error</span>:</span> true</span></span>
      processes</span>: {}</span></span>
  prometheus</span>:</span></span>
    config</span>:</span></span>
      global</span>:</span></span>
        scrape_interval</span>:</span> 30s</span></span>
      scrape_configs</span>:</span></span>
        -</span> job_name</span>:</span> otel-collector-binary</span></span>
          static_configs</span>:</span></span>
            -</span> targets</span>: [</span>'localhost:8888'</span>]</span></span></code></pre>
可以看到，這裡配置了三種收資料的機制：</p>

其一為 OTLP</strong>，讓此 Collector 監聽 4317 與 4318 埠，外部可以透過 gRPC 或 HTTP 打入 OTLP 資料。</li>
其二為 hostmetrics</strong>，此乃 Collector 所在機台的硬體資源資料。</li>
其三為 Prometheus</strong> 資料，Prometheus 是另一套應用監控標準，這裡 Collector 每隔三十秒會向 localhost:8888 請求數據指標（metric），這個 localhost:8888 是誰呢？就是 Collector 自己，它會在 8888 埠輸出自己的數據指標，自己跟自己要數據，而且微妙的是走的是 Prometheus，而非自己的 OTLP。</li>
</ul>
注：Prometheus 源自希臘神話，涵義為先見之明者，被用於監測機制的名字應該是取其洞察的意涵。相較於 OpenTelemetry，Prometheus 更著重於 metric，而 OpenTelemetry 著重於 trace，但兩者確有重疊，後面也會再提到什麼是 metric 與 trace。</p>
回到配置檔主題，把改好的配置檔放到 /etc/otelcol-contrib/config.yaml，再重啟 otelcol-contrib 服務，Collector 應該就會把資料打給 APM 了。</p>
在監測 app 前，我們先利用上面的 Host Metrics 來做機台資源儀表板。</p>
Host Metrics 儀表板</h2>

</p>
</figure>
Host Metrics</a> 為 Collector 的 receiver 模組之一，它會蒐集 Collector 所在機器的硬體資源使用狀況，前面我們配置了 CPU、記憶體等指標，SigNoz 可以根據這些數據制定一張儀表板，讓我們的 IT 戰情室看起來很厲害的感覺。</p>
登入 SigNoz，到 Dashboard，右上角選 New Dashboard -> Import JSON，把 SigNoz 提供的 Host Metrics dashboard JSON</a> 貼上去，收工。</p>
這份 JSON 的結構主要由 layout 區塊與 widgets 區塊構成，layout 區塊定義的面板都有一個 UUID，widgets 定義的圖表再指定對應的 UUID，SigNoz 的佈局引擎就會根據 UUID 的對應關係排出版面與圖表，widgets 的資料來自 PromQL</a> 的查詢結果，也支援 ClickHouse SQL</a> 查詢，或者也可以從 SigNoz web UI 下查詢，然後保存成儀表板。</p>
我們把貼上去的 JSON 存檔，應該就可以看到這個 Host Metrics 儀表板了，這樣就有個看起來很厲害的儀表板了，可以在老婆老闆同事面前帥一波，手寫查詢語句的部份以後有需要再深入。</p>
真正要讓儀表版發揮功能，還要搭配 alert，例如當 CPU 衝到 90% 就通知特別冷卻戰術行動小組（S.C.S.O.F.），這時候看儀表板才有意義，不然誰會一直盯著螢幕看呢，除非你在電廠</a>、行車調度中心</a>、太空中心</a>、操盤室</a>，或 NCIS 多重威脅預警中心</a>。</p>
App 監測</h2>
架設完 APM 與 Collector，現在可以把我們的 app 裝上監測器了。</p>
OpenTelemetry 已經備有多種語言與框架的監測套件，視語言或框架不同，監測器裝設方式也有不同，這裡以 Python 的 FastAPI 為例。</p>
要監測 Python app，得先裝幾個套件：</p>

opentelemetry-distro</a>，這是大禮包，內有 OpenTelemetry API、SDK、監測器等工具。</li>
opentelemetry-exporter-otlp</a>，就是 Python 的 OTLP exporter 囉。</li>
</ul>
要完整安裝大禮包，得執行它附帶的安裝工具：</p>
opentelemetry-bootstrap</span> --action=install</span></span></code></pre>
它會幫我們下載與安裝各個套件，這很方便，但如果在 CI 環境也想加上監測的話，也要在 CI 的配置檔執行這行指令，或是包進容器映像內。</p>
對於 app 的開發環境與生產環境，啟動監測的方法略有不同，下面分開說明。</p>
開發環境</h3>
開發環境下，啟動 Python app 的方式通常是跑一行指令，假設這個 app 的啟動腳本是 start-dev.py，原本的啟動命令為：</p>
python</span> ./start-dev.py</span></span></code></pre>
要監測它，把啟動命令改為：</p>
OTEL_RESOURCE_ATTRIBUTES</span>=</span>service.</span>name</span>=</span>mocha-backend-developemnt,deployment.</span>environment</span>=</span>development</span></span>
OTEL_EXPORTER_OTLP_ENDPOINT</span>=</span>http://localhost:4317</span></span>
OTEL_EXPORTER_OTLP_PROTOCOL</span>=</span>grpc</span></span>
</span>
opentelemetry-instrument</span> python ./start-dev.py</span></span></code></pre>
第一行宣告一些關於 app 的屬性，格式為 key1=value1,key2=value2</code>，完整的屬性清單在這裡</a>，這邊定義了服務名、部署環境等，他們的 value 的值可以自行訂定，能清楚識別就好，前面說到 APM 可以接收多個 app 或服務的監測資料，在查詢資料時會用到這些屬性來對資料做篩選與層別。</p>
第二行是 Collector 的位址，在上面的架構圖裡，我們把 Collector 與 app 裝在同一台機器，所以就是 localhost 囉。</p>
最後一行的 opentelemetry-instrument</code> 會根據前面設的環境變數發送監測資料給 Collector。</p>
App 跑起來之後，玩一下，讓它產生點資料，等半分鐘，視角轉回 SigNoz，在 SigNoz 的 Service 與 Traces 應該可以見到 app 產生的監測資料，確認資料有成功收到。</p>
生產環境</h3>
像上面這樣以 opentelemetry-instrument 與命令列來啟動 Python app 的方式只適用於開發環境，如果是生產環境，那啟動一款 Python web app 的方式就有各種花式可能，其中一種典型的形式是 systemd 叫起 Gunicorn，Gunicorn 叫起 Uvicorn worker 與 Python ASGI web app。</p>
根據文件</a>，我們要在 Gunicorn fork 行程之後才執行監測程式，這裡的 fork 是 Unix 系作業系統中一種建立行程（process）副本的機制，Gunicorn 作為 Python app server，啟動多 worker 的底層機制就是利用 fork 達成的，總之我們得在 Gunicorn 的配置檔中的一個 hook 端點 post_fork()</code> 來執行監測程式：</p>
# gunicorn.conf.py</span></span>
</span>
from</span> gunicorn.arbiter</span> import</span> Arbiter</span></span>
from</span> gunicorn.workers.base</span> import</span> Worker</span></span>
</span>
from</span> opentelemetry</span> import</span> trace</span></span>
from</span> opentelemetry.exporter.otlp.proto.grpc.trace_exporter</span> import</span> OTLPSpanExporter</span></span>
from</span> opentelemetry.sdk</span> import</span> resources</span></span>
from</span> opentelemetry.sdk.trace</span> import</span> TracerProvider</span></span>
from</span> opentelemetry.sdk.trace.export</span> import</span> BatchSpanProcessor</span></span>
</span>
</span>
def</span> post_fork</span>(server: Arbiter, worker: Worker):</span></span>
    server.log.info(</span>f</span>'Worker spawned (pid: </span>{</span>worker.pid</span>}</span>)'</span>)</span></span>
</span>
    resource</span> =</span> resources.Resource.create({</span></span>
            resources.</span>DEPLOYMENT_ENVIRONMENT</span>:</span> 'staging'</span>,</span></span>
            resources.</span>SERVICE_INSTANCE_ID</span>:</span> 'uone_staging'</span>,</span></span>
            resources.</span>SERVICE_NAME</span>:</span> 'uone-backend-staging'</span>,</span></span>
    })</span></span>
</span>
    span_processor</span> =</span> BatchSpanProcessor(OTLPSpanExporter(</span>'http://localhost:4317'</span>))</span></span>
    tracer_provider</span> =</span> TracerProvider(</span>resource</span>=</span>resource)</span></span>
    tracer_provider.add_span_processor(span_processor)</span></span>
    trace.set_tracer_provider(tracer_provider)</span></span></code></pre>
這裡主要做兩件事：</p>

建立 resource，大多是一些與前面相同的 app 屬性，改為以程式碼的形式表達罷了，讓 APM 得以篩選或層別我們關注的資料。</li>
設定 tracer：

這裡牽涉到一個叫做 batch span processor 的東西，batch 是批次，processor 是處理器，那 span 是什麼？後面會再談到。</li>
Span processor 又牽涉到一個 OTLP span exporter 物件，同樣的，我們先知道它是個 OTLP 資料匯出器就好，後面再來談 span 是什麼。這裡填入 localhost，因為在前面的架構中，OpenTelemetry Collector 與 app 是裝在同一台機器內。</li>
</ul>
</li>
</ul>
實際上，要從 app 直接打給 SigNoz 也可以，因為 SigNoz 也跑了個 Collector 來接受別人打給它的監測資料，我們把前面的架構圖 APM 的方塊再展開：</p>
---
displayMode: compact
---
flowchart TB
    app["App"]
    ap_machine_collector["OTel Collector"]

    apm_collector["OTel Collector"]

    subgraph ap_machine["AP Machine"]
        app
        ap_machine_collector
    end

    subgraph apm["APM"]
        apm_collector
    end

    app -- "OTLP" --> ap_machine_collector -- "OTLP" --> apm_collector
</pre>
就可以明白 APM 也理所當然裡面有個 Collector。</p>
另外，在 app 內部，也要呼叫監測程式，以 FastAPI 為例：</p>
from</span> fastapi</span> import</span> FastAPI, Request</span></span>
from</span> opentelemetry.instrumentation.fastapi</span> import</span> FastAPIInstrumentor</span></span>
</span>
fastapi_app</span> =</span> FastAPI()</span></span>
FastAPIInstrumentor.instrument_app(fastapi_app)</span></span>
</span>
@app.get</span>(</span>'/foobar'</span>)</span></span>
async def</span> foobar</span>():</span></span>
    return</span> {</span>'message'</span>:</span> 'hello world'</span>}</span></span></code></pre>
重點在多加了一句 FastAPIInstrumentor.instrument_app()</code>，其它都是 FastAPI 原本的東西。</p>
相較於開發環境，生產環境的監測麻煩一點，不過也還好，這些都做完之後，跑個測試，上個新版，重啟服務，進入 app 玩一下，等個半分鐘，進入 SigNoz 看看有沒有 trace 資料進來吧。</p>
監測資料</h2>
對於 OpenTelemetry 的監測資料，前面我們僅概略的知道有什麼 trace、metric，又有 span 什麼的，在 OpenTelemetry 的概念裡，它支援三類監測資料，分別是 trace、metric、log，而 span 則是 trace 類資料裡的一種概念，為了避免越說越迷糊，下面逐一展開，從最簡單的 log 開始。</p>
Log</h3>
雖然本文在此之前都未提及，但 OpenTelemetry 也支援收發 log，而 APM 也兼具 log server 的角色，以 Python 為例，OpenTelemetry 套件提供了與 Python 原生 logging</a> 模組整合的 logging handler，只要把它配置一下，就如同其它的 logging handler 一樣，調用 Logger 物件的 addHander()</code> 方法，把 OpenTelemetry logging handler 餵入即可，參考以下範例：</p>
import</span> logging</span></span>
</span>
from</span> opentelemetry._logs</span> import</span> set_logger_provider</span></span>
from</span> opentelemetry.exporter.otlp.proto.grpc._log_exporter</span> import</span> OTLPLogExporter</span></span>
from</span> opentelemetry.sdk._logs</span> import</span> LoggingHandler, LoggerProvider</span></span>
from</span> opentelemetry.sdk._logs.export</span> import</span> BatchLogRecordProcessor</span></span>
from</span> opentelemetry.sdk</span> import</span> resources</span></span>
</span>
resource</span> =</span> resource</span> =</span> resources.Resource.create({</span></span>
    resources.</span>DEPLOYMENT_ENVIRONMENT</span>:</span> 'staging'</span>,</span></span>
    resources.</span>SERVICE_INSTANCE_ID</span>:</span> 'uone_staging'</span>,</span></span>
    resources.</span>SERVICE_NAME</span>:</span> 'uone-backend-staging'</span>,</span></span>
})</span></span>
</span>
logger_provider</span> =</span> LoggerProvider(resource)</span></span>
set_logger_provider(logger_provider)</span></span>
log_record_processor</span> =</span> BatchLogRecordProcessor(</span></span>
  OTLPLogExporter(</span>'http://localhost:4317'</span>,</span> insecure</span>=</span>True</span>)</span></span>
)</span></span>
logger_provider.add_log_record_processor(log_record_processor)</span></span>
handler</span> =</span> LoggingHandler(</span>logger_provider</span>=</span>logger_provider)</span></span>
</span>
# Attach OTLP handler to root logger</span></span>
logging.getLogger().addHandler(handler)</span></span>
</span>
# Log directly</span></span>
logging.info(</span>"Jackdaws love my big sphinx of quartz."</span>)</span></span></code></pre>
這裡和前面設定 trace 有八成像，同樣的 resource、類似的 processor、類似的 set logger provider，主要差別在最後要記得呼叫 addHandler()</code>。</p>
Metric</h3>
Metric 一般翻為指標或數據指標，總之就是一系列量值，例如前面 Host Metrics 見過的記憶體使用率、CPU 使用率等等，除了像這些由既有模組制定好的 metric 外，我們也可以制定自己關心的 metric，例如登入錯誤的次數等等，再搭配儀表板與警示就可以即時通知人員介入處理，更多說明可以參考 OpenTelemetry 文件</a>。</p>
Trace</h3>
Trace 指的是一次請求的鏈路軌跡，一個 trace 由帶有父子關係的 span 構成，例如一個公開的 API 端點 /foobar，它的處理函式 foobar()</code> 裡面呼叫了 baz()</code>，那就會形成由一組巢狀 span 構成的 trace，其中 root span 為 foobar()</code> 的監測資料，sub-span 為 baz()</code> 的監測資料，監測資料內容包括處理時間、客戶端資訊、app 端資訊等，APM 方面會以端點為單位幫我們統計平均回應時間等資訊。</p>
我們進入 SigNoz 的 Services 內頁，可以看到一些統計數據，包括 Latency、Rate、Apdex</a>、Key Operations、Error Percentage 等：</p>

</p>
</figure>
這幾項資料可以讓我們從較大的視角得知當前服務的狀態，如果要更深入看端點的反應，可以點入 Key Operation 清單中的端點，檢視單一端點的統計數據：</p>

</p>
</figure>
還可以再深入到單一請求的 trace，去檢視主要的性能瓶頸發生在哪個 span：</p>
</p>
具體要怎麼運用這些監測，就看各人的需求啦。</p>
結語</h2>
本文介紹了 OpenTelemetry 及以其為基礎的 APM SigNoz，透過這套標準與工具，我們得以從應用內部的視角即時的監控它的性能，本文著重於用最簡短的方式介紹 OpenTelemetry 概念與監測機制建置，OpenTelemetry 博大精深，Collector、trace、metric、log 都足以獨立為一篇文章，有興趣的讀者可以自行深入囉！個人是認為 OpenTelemetry 的文件太多太雜又太分散，對新手來說實在很難入門，希望這邊文章有幫助到不得其門而入的你。</p>
另外，也有些 APM 產品是不走 OpenTelemetry 的，畢竟這類「標準」很多，有 OpenTelemetry、StatsD</a>、Prometheus 等等，扮演 data collector 的同類工具也很多，有 OpenTelemetry Collector、Fluentd、Fluent Bit、Datadog Vector 等等，彼此都互有重疊、或有兼容、各有特色，很容易落入選擇障礙，逐套嘗試顯然不現實，在下一個大而全的新輪子被重新發明之前，選用以 OpenTelemetry 為基礎的 APM 看起來是最佳解。</p>

六小編 Editor Leon

Fluent Bit 收集 Log

怎麼算有小數點的錢？

浮點誤差</h2> 先看實際問題：</p>

如何在 macOS 掛載 ext4

Xcode command line tools</h2> 一行安裝：</p>

pkg-config</h2> pkg-config 是編譯期間的相依套件管理工具，前面我們已經備好 FUSE-T 的 pkg-config 配置以及源碼，但還需要安裝 pkg-config 工具本身，為了避免落入編譯輪迴地獄，這裡我們用速成方式一行搞定：</p>

重新認識異步

協程與 event loop</h2> 如果我們直接跑那個 async 定義的 main()</code>，Python 會告訴我們此函式它生成一個 coroutine（協程）物件，並且因為沒有 asyncio 模組幫忙把它丟給 event loop，此時函式不會被執行：</p>

前端權限檢查 CASL

權限檢查利器 Vakt

存取控制與 Oso

從 pyee 認識觀察者模式

其它有點像又不一樣的設計模式</h2> 觀察者模式適用的場景在應用內，隨場景不同，還可以考慮其他類似的設計模式：</p>

初探 OpenTelemetry 與 APM