碼上歡樂
相關內容    簡體    繁體

Sentry 開發者貢獻指南 - SDK 開發(性能監控)

本文轉載自   查看原文   2021-12-24 17:57   728 

內容整理於官方開發文檔

系列

性能監控指南

本文檔介紹了 SDK 應如何通過分布式跟蹤添加對性能監控的支持。

這應該提供 SDK 需要實現的 API 的概述，而不強制要求內部實現細節。

參考實現：

SDK 配置

通過設置兩個新的 SDK 配置選項之一來啟用跟蹤，tracesSampleRate 和 tracesSampler。如果未設置，則兩者都默認為 undefined，從而選擇如何加入跟蹤。

tracesSampleRate

這應該是介於 0.0 和 1.0（含）之間的 float/double，表示任何給定 transaction 將被發送到 Sentry 的百分比機會。
因此，0.0 是 0% 的機會（不會發送），而 1.0 是 100% 的機會（都將發送）。
此 rate 同樣適用於所有 transaction；
換句話說，每個 transaction 都應該有相同的隨機機會以 sampled = true 結束，等於 tracesSampleRate。

tracesSampler

這應該是一個 callback，在 transaction 開始時調用，它將被賦予一個 samplingContext 對象，並且應該返回一個介於 0.0 和 1.0 之間的采樣率_對於所討論的 transaction_。
此采樣率的行為方式應與上面的 tracesSampleRate 相同，不同之處在於它僅適用於新創建的 transaction，因此可以以不同的 rate 對不同的 transaction 進行采樣。
返回 0.0 應該強制刪除 transaction（設置為 sampled = false），返回 1.0 應該強制發送 transaction（設置 sampled = true）。

可選地，tracesSampler callback 也可以返回一個布爾值來強制進行采樣決策（false 等同於 0.0，true 等同於 1.0）。
如果返回兩種不同的數據類型在實現語言中不是一個選項，則可以安全地省略這種可能性。

maxSpans

由於 transaction payload 在攝取端強制執行最大大小，因此 SDK 應限制附加到事務的 span 數。
這類似於如何限制面包屑和其他任意大小的列表以防止意外誤用。
如果在達到最大值后添加新的 span，SDK 應刪除 span 並理想地使用內部日志記錄來幫助調試。

maxSpans 應該作為一個內部的、不可配置的、默認為 1000 的常量來實現。如果在給定的平台中有理由，它可能會變得可配置。

maxSpans 限制還可以幫助避免永遠不會完成的 transaction（在 span 打開時保持 transaction 打開的平台中），防止 OOM 錯誤，並通常避免降低應用程序性能。

Event 變更

在撰寫本文時，transaction 是作為 Event 模型的擴展實現的。

Transaction 的顯着特征是 type: "transaction"。

除此之外，Event 獲得了新的字段：spans、contexts.TraceContext。

新的 Span 和 Transaction 類

在內存中，span 構建了一個定時操作的概念樹(conceptual tree)。
我們稱整個 span tree 為 transaction。
有時我們使用術語 "transaction" 來指代作為整棵樹的 span tree，有時特指樹的 root span。

通過網絡，transaction 被序列化為 JSON 作為增強的 Event，並作為 envelope 發送。
不同的 envelope 類型用於優化攝取（因此我們可以以不同於其他事件的方式路由 “transaction events”，主要是 “error events”）。

在 Sentry UI 中，您可以使用 Discover 查看所有類型的事件，並使用 Issues 和 Performance 部分分別深入研究 errors 和 transactions。
面向用戶的跟蹤文檔解釋了更多產品級別的概念。

Span 類將每個單獨的 span 存儲在 trace 中。

Transaction 類就像一個 span，有幾個主要區別：

  • Transaction 有 name，span 沒有。
  • 在 span 上調用 finish 方法會記錄 span 的結束時間戳。對於 transaction，finish 方法另外向 Sentry 發送一個事件。

Transaction 類可能繼承自 Span，但這是一個實現細節。
從語義上講，transaction 既表示 span tree 的 top-level span，也表示向 Sentry 報告的單位。

  • Span 接口

    • 創建 Span 時，將 startTimestamp 設置為當前時間
    • SpanContext 是 Span 的屬性集合（可以是一個實現細節）。如果可能，SpanContext 應該是不可變的。
    • Span 應該有一個方法 startChild，它使用當前 span 的 id 作為新 span 的 parentSpanId 創建一個新的 span，並將當前 span 的 sampled 值復制到新 span 的 sampled 屬性
    • startChild 方法應遵守 maxSpans 限制，一旦達到限制，SDK 不應為給定的 transaction 創建新的子 span。
    • Span 應該有一個名為 toSentryTrace 的方法，它返回一個字符串，該字符串可以作為名為 sentry-trace 的 header 發送。
    • Span 應該有一個名為 iterHeaders（適應平台的命名約定）的方法，它返回一個可迭代的或 header 名稱和值的映射。這是一個包含 return {"sentry-trace": toSentryTrace()} 的薄 wrapper。 請參閱 continueFromHeaders 以了解為什么存在這種情況，並且在編寫集成(integration)時應該首選。

  • Transaction 接口

    • 一個 Transaction 內部包含一個子 Span 的平面列表（不是樹結構）
    • Transaction 還有一個 setName 方法來設置 transaction 的名稱
    • Transaction 在創建時收到一個 TransactionContext（新屬性與 SpanContext 是 name）
    • 由於 Transaction 繼承了 Span，因此它具有所有 Span 可用的函數並且可以像 Span 一樣進行交互
    • 一個 transaction 要么被采樣（sampled = true），要么被取消采樣（sampled = false），一個在 transaction 的生命周期中被繼承或設置一次的決定，並且在任何一種情況下都會傳播給所有的 children。不應將未抽樣的 transaction 發送給 Sentry。
    • TransactionContext 應該有一個叫做 fromSentryTrace 的 static/ctor 方法，它用從 sentry-trace header值接收的數據預填充一個 TransactionContext
    • TransactionContext 應該有一個名為 continueFromHeaders(headerMap) 的 static/ctor 方法，它現在實際上只是一個圍繞 fromSentryTrace(headerMap.get("sentry-trace")) 的薄 wrapper。integration/framework-sdk 的作者應該更喜歡 fromSentryTrace，因為它隱藏了核心 sdk 中更深層次使用的確切 header 名稱，並為將來使用其他 header（來自 W3C）留下了機會，而無需更改所有集成。

  • Span.finish()

    • 只需將 endTimestamp 設置為當前時間（在 payload timestamp 中）

  • Transaction.finish()

    • super.finish() (在 Span 上調用 finish)
    • 僅當 sampled == true 時才將其發送給 Sentry
    • 一個 Transaction 需要被包裹在一個 Envelope 中並發送到 Envelope Endpoint
    • Transport 應該為 Transactions/Events 使用相同的內部隊列
    • Transport 應該實現基於類別的速率限制 →
    • Transport 應該處理在內部將 Transaction 包裝在 Envelope 中

采樣

每個 transaction 都有一個 “抽樣決策”，即一個布爾值，指示是否應該將其發送給 Sentry。
這應該在 transaction 的生命周期內只設置一次，並且應該存儲在內部的 sampled 布爾值中。

transaction 可以通過多種方式結束抽樣決策(sampling decision)：

  • 根據 tracesSampleRate 中設置的靜態采樣率隨機采樣
  • 根據 tracesSampler 返回的動態采樣率進行隨機采樣
  • tracesSampler 返回的絕對決策（100% 概率或 0% 概率）
  • 如果 transaction 有父級，繼承其父級的抽樣決策
  • 傳遞給 startTransaction 的絕對決策

當其中一個以上發揮作用的可能性時，應適用以下優先規則：

  1. 如果將抽樣決策傳遞給 startTransaction (startTransaction({name: "my transaction", sampled: true}))，則將使用該決策，而不管其他任何事情。
  2. 如果定義了 tracesSampler，則將使用其決策。它可以選擇保留或忽略任何父采樣決策，或使用采樣上下文數據做出自己的決策或為 transaction 選擇采樣率。
  3. 如果未定義 tracesSampler，但存在父采樣決策，則將使用父采樣決策。
  4. 如果沒有定義 tracesSampler 並且沒有父采樣決策，則將使用 tracesSampleRate。

Transaction 應僅通過 tracesSampleRate 或 tracesSampler 進行采樣。sampleRate 配置用於 error 事件，不應應用於 transaction。

采樣上下文

如果定義，tracesSampler 回調應該傳遞一個 samplingContext 對象，該對象至少應該包括：

  • 創建 transaction 的 transactionContext
  • 一個布爾值 parentSampled，包含從父級傳遞過來的采樣決策，如果有的話
  • 來自可選的 customSamplingContext 對象的數據在手動調用時傳遞給 startTransaction

根據平台，可能包含其他默認數據。（例如，對於服務器框架，包含與 transaction 正在測量的請求相對應的 request 對象是有意義的。）

傳播

transaction 的抽樣決策應傳遞給其所有子項，包括跨服務邊界。這可以在相同服務子項的 startChild 方法中完成，並為不同服務中的子項使用 senry-trace header。

Header sentry-trace

Header 用於跟蹤傳播。SDK 使用 header 繼續跟蹤來自上游服務（傳入 HTTP 請求），並將跟蹤信息傳播到下游服務（傳出 HTTP 請求）。

sentry-trace = traceid-spanid-sampled

sampled 是可選的。所以至少，它是預期的：

sentry-trace = traceid-spanid

為了與 W3C traceparent header（沒有版本前綴）
和 Zipkin's b3 headers（考慮 64 位和 128 位的 traceId 有效）提供最小的兼容性，
sentry-trace header 應具有以 32 個十六進制字符編碼的 128 位的 traceId 以及以 16 個十六進制字符編碼的 64 位 spanId。
為了避免與 W3C traceparent header（我們的 header 相似但不相同）混淆，
我們將其簡稱為 sentry-trace。header 中沒有定義版本。

sampled 值

為簡化處理，該值由單個（可選）字符組成。可能的值為：

  - No value means defer

0 - Don't sample

1 - Sampled

與 b3 header 不同，sentry-trace header 不應該只包含一個采樣決策，沒有 traceid 或 spanid 值。有很好的理由 無論采樣決策如何，始終包含 traceid 和 spanid，這樣做也簡化了實現。

除了在 Sentry 的情況下使用 *defer 的通常原因外，
還有一個原因是下游系統使用 Sentry 捕獲 error 事件。可以在那時做出決定，對跟蹤進行采樣，以便為報告的崩潰提供跟蹤數據。

sentry-trace = sampled

這實際上對於代理將其設置為 0 並選擇退出跟蹤很有用。

Static API 變更

Sentry.startTransaction 函數應該接受兩個參數 - 傳遞給 Transaction 構造函數的 transactionContext 和一個包含要傳遞給 tracesSampler（如果已定義）的數據的可選的 customSamplingContext 對象。

它創建一個綁定到當前 hub 的 Transaction 並返回實例。
用戶與實例交互以創建子 span，因此，必須自己跟蹤它。

Hub 變更

  • 引入一個名為 traceHeaders 的方法

    • 此函數返回 header（string）sentry-trace
    • 該值應該是當前在 Scope 上的 Span 的 trace header 字符串

  • 引入一個名為 startTransaction 的方法

    • 采用與 Sentry.startTransaction 相同的兩個參數
    • 創建一個新的 Transaction 實例
    • 應按照本文檔 'Sampling' 部分中更詳細的描述實施抽樣

  • 修改名為 captureEvent 或 captureTransaction 的方法

    • 不要為 transaction 設置 lastEventId

Scope 變更

Scope 持有對當前 Span 或 Transaction 的引用。

  • Scope 引入 setSpan
    • 這可以在內部使用，來傳遞 Span / Transaction，以便集成可以將子項附加到它
    • 在 Scope（舊版）上設置 transaction 屬性應該覆蓋存儲在 Scope 中的 Transaction 的名稱，如果有的話。
      這樣，即使用戶無法直接訪問 Transaction 的實例，我們也可以讓用戶選擇更改 transaction 名稱。

與 beforeSend 和事件處理器的交互

beforeSend 回調是我們認為最重要的特殊 Event Processor。適當的事件處理器通常被認為是內部的。

Transaction 應該不通過 beforeSend。但是，它們仍然由事件處理器處理。
這是在將 transaction 作為 event 的當前實現處理的一些靈活性與為 transaction 和 span 的不同生命周期 hook 留出空間之間的折衷。

動機：

  1. 面向未來：如果用戶依賴 beforeSend 進行 transaction，
    這將使最終在不破壞用戶代碼的情況下實現單個 span 攝取變得復雜。
    在撰寫本文時，transaction 作為 event 發送，但這被視為實現細節。

  2. API 兼容性：用戶擁有他們現有的 beforeSend 實現，只需要處理錯誤事件。
    我們將 transaction 作為一種新型 event 引入。
    當用戶升級到新的 SDK 版本並開始使用跟蹤時，他們的 beforeSend 將開始看到他們的代碼不打算處理的新類型。
    在 transaction 之前，他們根本不必關心不同的事件類型。
    有幾種可能的后果：破壞用戶應用程序；默默地和無意地放棄 transaction；
    transaction 事件以令人驚訝的方式修改。

  3. 就可用性而言，beforeSend 不適合刪除 transaction，就像刪除 error 一樣。
    Error 是一個時間點事件。當 error 發生時，用戶在 beforeSend 中有完整的上下文，
    並且可以在它進入 Sentry 之前修改/丟棄事件。對於交易，transaction 是不同的。
    創建 transaction，然后將它們打開一段時間，同時創建 child span 並將其附加到它。
    同時傳出的 HTTP 請求包括當前 transaction 與其他服務的采樣決策。
    在 span 和 transaction 完成后，將 transaction 放入類似 beforeSend 的鈎子中會在跟蹤中留下來自其他服務的孤立 transaction。
    同樣，在此后期將采樣決策修改為 "yes" 也會產生不一致的痕跡。

跟蹤上下文（實驗性）

為了對跟蹤進行采樣，我們需要沿着調用鏈傳遞 trace id 以及做出采樣決策所需的信息，即所謂的 跟蹤上下文(trace context)。

協議

Trace 信息作為編碼的 tracestate header 在 SDK 之間傳遞，SDK 預計會攔截和傳播這些 header。

對於向 sentry 提交的事件，trace context 作為嵌入在 Envelope header 中的 JSON 對象發送，key 為 trace。

跟蹤上下文

無論采用何種傳輸機制，trace context 都是具有以下字段的 JSON 對象：

  • trace_id (string, required) - UUID V4 編碼為不帶破折號的十六進制序列（例如771a43a4192642f0b136d5159a501700），它是一個由 32 個十六進制數字組成的序列。這必須與提交的 transaction item 的 trace id 匹配。
  • public_key (string, required) - 來自 SDK 使用的 DSN 的 Public key。它允許 Sentry 通過基於起始項目解析相同的規則集來對跨多個項目的跟蹤進行采樣。
  • release (string, optional) - 客戶端選項中指定的版本名稱，通常是：package@x.y.z+build。 這應該與 transaction event payload 的 release 屬性匹配*
  • environment - 客戶端選項中指定的 environment 名稱，例如 staging。 這應該與 transaction event payload 的 environment 屬性匹配*
  • user (object, optional) - 包含以下字段的 scope 的 user context 的子集：
    • id (string, optional) - 用戶上下文的 id 屬性。
    • segment (string, optional) - 用戶數據包中的 segment 屬性值（如果存在）。將來，該字段可能會被提升為用戶上下文的適當屬性。
  • transaction (string, optional) - 在 scope 上設置的 transaction 名稱。這應該與 transaction event payload 的 transaction 屬性匹配*

例子：

{
  "trace_id": "771a43a4192642f0b136d5159a501700",
  "public_key": "49d0f7386ad645858ae85020e393bef3",
  "release": "myapp@1.1.2",
  "environment": "production",
  "user": {
    "id": "7efa4978da177713df088f846f8c484d",
    "segment": "vip"
  },
  "transaction": "/api/0/project_details"
}

Envelope Headers(信封頭)

當通過 Envelope 向 Sentry 發送 transaction 事件時，必須在 trace 字段下的 envelope header 中設置 trace 信息。

這是一個包含 trace context 的最小 envelope header 的示例（盡管 header 不包含換行符，但在下面的示例中添加了換行符以提高可讀性）：

{
  "event_id": "12c2d058d58442709aa2eca08bf20986",
  "trace": {
    "trace_id": "771a43a4192642f0b136d5159a501700",
    "public_key": "49d0f7386ad645858ae85020e393bef3"
    // other trace attributes
  }
}

Tracestate Headers(跟蹤狀態頭)

將跟蹤上下文傳播到其他 SDK 時，Sentry 使用 W3C tracestate header。有關如何將這些 header 傳播到其他 SDK 的更多信息，請參閱 "Trace Propagation"。

Tracestate header 包含幾個特定於供應商的不透明數據。根據 HTTP 規范，這些多個 header 值可以通過兩種方式給出，通常由 HTTP 庫和開箱即用的框架支持：

  • 用逗號連接：
    tracestate: sentry=<data>,other=<data>
  • 重復：
    tracestate: sentry=<data>
tracestate: other=<data>

要創建 tracestate header 的內容：

  1. 將完整的 trace context 序列化為 JSON，包括 trace_id。
  2. 如果字符串在平台上的表示方式不同，則將生成的 JSON 字符串編碼為 UTF-8。
  3. 使用 base64 對 UTF-8 字符串進行編碼。
  4. 去除尾隨填充字符 (=)，因為這是一個保留字符。
  5. 在前面加上 "sentry="，導致 "sentry=<base64>"。
  6. 如上所述加入 header。

通過去除尾隨填充，默認的 base64 解析器可能會檢測到不完整的 payload。選擇允許丟失 = 或允許截斷 payload 的解析模式。

例如：

{
  "trace_id": "771a43a4192642f0b136d5159a501700",
  "public_key": "49d0f7386ad645858ae85020e393bef3",
  "release": "1.1.22",
  "environment": "dev",
  "user": {
    "segment": "vip",
    "id": "7efa4978da177713df088f846f8c484d"
  }
}

將編碼為

ewogICJ0cmFjZV9pZCI6ICI3NzFhNDNhNDE5MjY0MmYwYjEzNmQ1MTU5YTUwMTcwMCIsCiAgInB1YmxpY19rZXkiOiAiNDlkMGY3Mzg2YWQ2NDU4NThhZTg1MDIwZTM5M2JlZjMiLAogICJyZWxlYXNlIjogIjEuMS4yMiIsCiAgImVudmlyb25tZW50IjogImRldiIsCiAgInVzZXIiOiB7CiAgICAic2VnbWVudCI6ICJ2aXAiLAogICAgImlkIjogIjdlZmE0OTc4ZGExNzc3MTNkZjA4OGY4NDZmOGM0ODRkIgogIH0KfQ

並導致 header

tracestate: sentry=ewogIC...IH0KfQ,other=[omitted]

（注意 header 末尾的第三方條目；新的或修改的條目總是添加到左側，因此我們將 sentry= 值放在那里。另請注意，盡管此處為了清晰起見省略了編碼值, 在真正的 header 中，將使用完整的值。）

實施指南

支持此 header 的 SDK 必須：

  • 創建新的 trace context 時使用 scope 信息
  • 為包含 transaction 的 envelope 添加帶有 trace context 的 envelope header
  • 將 tracestate HTTP header 添加到傳出的 HTTP 請求以進行傳播
  • 在適用的情況下攔截對 tracestate HTTP header 的傳入 HTTP 請求，並將它們應用到 local trace context

背景

這是性能指南涵蓋的 trace ID 傳播的擴展。
根據統一 API 跟蹤規范，Sentry SDK 通過集成向傳出請求添加 HTTP header sentry-trace。
最重要的是，此 header 包含 trace ID，它必須與 transaction event 的 trace id 以及下面的 trace context 的 trace id 匹配。

trace context 應在 W3C traceparent header 中定義的附加 tracestate header 中傳播。
請注意，我們必須保持與 W3C 規范的兼容性，而不是專有的 sentry-trace header。
除了 Sentry SDK 放置的內容之外，tracestate header 還包含供應商特定的不透明數據。

Client 選項

雖然 trace context 正在開發中，但它們應該在內部 trace_sampling 布爾值 client 選項后面進行門控。該選項默認為 false，不應在 Sentry 文檔中記錄。

根據平台命名指南，該選項應該適當地區分大小寫：

  • trace_sampling (snake case)
  • traceSampling (camel case)
  • TraceSampling (pascal case)
  • setTraceSampling (Java-style setters)

添加 Envelope Header

在以下任何一種情況下，SDK 應將 envelope header 添加到傳出 envelope 中：

  1. envelope 包含 transaction event。
  2. scope 有一個 transaction 綁定。

具體來說，這意味着即使沒有 transaction 的 envelope 也可以包含 trace envelope header，
從而允許 Sentry 最終對屬於 transaction 的 attachment 進行采樣。
當 envelope 包含 transaction 且 scope 有綁定 transaction 時，
SDK 應使用 envelope 的 transaction 來創建 trace envelope header。

凍結上下文

為了確保 trace 中所有 transaction 的 trace context 完全一致，一旦通過網絡發送 trace context，就不能更改 trace context，即使 scope 或 options 之后發生更改。
也就是說，一旦計算出 trace context 就不再更新。即使應用程序調用 setRelease，舊版本仍保留在 context 中。

為了彌補對 setTransaction 和 setUser 等函數的延遲調用，
可以認為 trace context 處於兩種狀態：NEW 和 SENT。
最初，context 處於 NEW 狀態並且可以修改。第一次發送后，它將變為 SENT 並且不能再更改。

我們建議 trace context 應該在第一次需要時即時計算：

  • 創建 Envelope
  • 傳播到傳出的 HTTP 請求

Trace context 必須保留，直到用戶開始新的 trace，此時 SDK 必須計算新的 trace context。

建議 SDK 記錄在 trace context 凍結時會導致 trace context 更改的屬性修改，例如 user.id，以簡化常見動態采樣陷阱的調試。

傳入上下文

與攔截來自入站 HTTP 請求的 trace ID 相同，SDK 應讀取 tracestate header 並假設 Sentry 跟蹤上下文（如果指定）。這樣的上下文立即凍結在 SENT 狀態，不應再允許修改。

平台細節

在 JavaScript 中編碼

如前所述，我們需要使用 UTF-8 字符串對 JSON trace context 進行編碼。JavaScript 內部使用 UTF16，因此我們需要做一些工作來進行轉換。

Base64 encoding and decoding in JavaScript（以及 Using Javascript's atob to decode base64 doesn't properly decode utf-8 strings）介紹了基本思想。

簡而言之，這是將 context 轉換為可以保存在 tracestate 中的 base64 字符串的函數。最后我們采用了一個更簡單的實現，但想法是一樣的：

// Compact form
function objToB64(obj) {
  const utf16Json = JSON.stringify(obj);
  const b64 = btoa(
    encodeURIComponent(utf16Json).replace(
      /%([0-9A-F]{2})/g,
      function toSolidBytes(match, p1) {
        return String.fromCharCode("0x" + p1);
      }
    )
  );
  const len = b64.length;
  if (b64[len - 2] === "=") {
    return b64.substr(0, len - 2);
  } else if (b64[len - 1] === "=") {
    return b64.substr(0, len - 1);
  }
  return b64;
}

// Commented
function objToB64(obj) {
  // object to JSON string
  const utf16Json = JSON.stringify(obj);
  // still utf16 string but with non ASCI escaped as UTF-8 numbers)
  const encodedUtf8 = encodeURIComponent(utf16Json);

  // replace the escaped code points with utf16
  // in the first 256 code points (the most wierd part)
  const b64 = btoa(
    endcodedUtf8.replace(/%([0-9A-F]{2})/g, function toSolidBytes(match, p1) {
      return String.fromCharCode("0x" + p1);
    })
  );

  // drop the '=' or '==' padding from base64
  const len = b64.length;
  if (b64[len - 2] === "=") {
    return b64.substr(0, len - 2);
  } else if (b64[len - 1] === "=") {
    return b64.substr(0, len - 1);
  }
  return b64;
}
// const test = {"x":"a-🙂-讀寫漢字 - 學中文"}
// objToB64(test)
// "eyJ4IjoiYS3wn5mCLeivu+WGmeaxieWtlyAtIOWtpuS4reaWhyJ9"

這是接受 base64 字符串（帶或不帶 '=' 填充）並返回一個對象的函數

function b64ToObj(b64) {
  utf16 = decodeURIComponent(
    atob(b64)
      .split("")
      .map(function(c) {
        return "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2);
      })
      .join("")
  );
  return JSON.parse(utf16);
}

// b64ToObj("eyJ4IjoiYS3wn5mCLeivu+WGmeaxieWtlyAtIOWtpuS4reaWhyJ9")
// {"x":"a-🙂-讀寫漢字 - 學中文"}

帶有命令行實用程序的 Base64

GNU base64 命令行實用程序帶有一個開關來包裝編碼的字符串。
這與 tracestate header 不兼容，應該避免。
如果 base64 實現創建多行，則必須將它們連接在一起。

Span Operations(跨度操作)

Span 操作是識別 span 正在測量的操作類型的短代碼。
Span 操作是低基數屬性 - 它們應該盡可能通用，同時仍然是人類可讀和有用的。他們應該避免包含高基數數據，如 ID 和 URL。

操作應盡可能遵循 OpenTelemetry 的語義約定。

保持 SDK 和 integration 之間的類別一致很重要，因為 Sentry 在操作細分功能中使用它們。
例如，db.init 和db.query 都將被歸類為數據庫操作（db）。可以在projectoptions/defaults.py 查看默認操作細分配置。

操作列表

下表包含 SDK 和 Sentry 產品使用的操作示例。
表中的 Usage 列包含使用該操作類別的示例，但不是操作用法的硬性建議。
只要類別保持一致，SDK 開發人員就可以自由選擇最適合他們正在檢測的用例的操作和標識符。

如果未提供 span 操作，則使用 default 的值。

Browser

Category Usage Description
pageload Web 應用程序的完整頁面加載
navigation Web 應用程序中的客戶端瀏覽器 history 更改
resource 資源，根據性能資源計時
resource.script
resource.link
resource.css
resource.img
browser 瀏覽器 API 或功能的使用
browser.paint
mark performance.mark() API 的使用
measure performance.measure() API 的使用
ui
ui.animation 一個 animation
ui.render 渲染 UI 元素所需的時間
ui.update 更新 UI 元素所需的時間
JS Frameworks

JS 框架應該在 UI 組件相關的操作前加上 ui 類別。

Category Usage Description
ui.react 與 React 組件相關的 Span
ui.react.mount
ui.react.render
ui.vue 與 Vue.js 組件相關的 Span
ui.vue.mount
ui.vue.update
ui.angular 與 Angular 組件相關的 Span
ui.ember 與 EmberJS 組件相關的 Span

Web Server

Web server 相關的 span 應該盡可能遵循 OpenTelemetry 的 HTTP 和 RPC 語義約定。

Category Usage Description
http 與 http 操作相關的 Span
http.client
http.server
rpc 與遠程過程調用 (RPC) 相關的 Span
grpc gRPC 框架的使用
template
template.init
template.parse
template.render
render 渲染視圖
serialize 數據序列化
console 通過命令行訪問 Web 服務器（例如 Rails 控制台）

Web Frameworks

Category Usage Description
django
django.middleware
django.view
express
rails
rack

Database

在可能的情況下，與數據庫相關的 span 應遵循 OpenTelemetry 的 Database 語義約定。

Category Usage Description
db 對數據庫的操作
db.connection
db.transaction
db.sql.query
db.query
db.query.compile

Serverless (FAAS)

Serverless 相關的 span 應盡可能遵循 OpenTelemetry 的 FaaS 語義約定。

Category Usage Description
faas serverless function 的調用
faas.aws
faas.aws.lambda
faas.aws.request
faas.gcp

Mobile

Category Usage Description
app 關於 mobile app 的數據
app.start
app.start.warm
app.start.cold
ui 移動/桌面 UI 上的操作
ui.load
ui.action
navigation 導航到另一個屏幕
file 對文件系統的操作
file.read
file.write

Messages/Queues

Messages/Queues 跨度應盡可能遵循 OpenTelemetry 的 Messaging 語義約定。

Category Usage Description
topic
topic.send
topic.recieve
topic.process
queue
queue.process
job
job.exec
celery


免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。



猜您在找 Sentry 開發者貢獻指南 - SDK 開發(事件負載) Sentry 開發者貢獻指南 - 什么是 Scope, 什么是 Hub？ Sentry 開發者貢獻指南 - 前端(ReactJS生態) Sentry 開發者貢獻指南 - 后端服務(Python/Go/Rust/NodeJS) Sentry 開發者貢獻指南 - 前端 React Hooks 與蟲洞狀態管理模式 ZooKeeper開發者指南(五) ProtoBuf開發者指南 RocketMQ開發者指南 Chrome開發者工具不完全指南：（三、性能篇） ProtoBuf開發者指南（轉）
 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM