本文檔描述了一種我們希望最終對用戶隱藏的配置格式。該頁面仍然存在的唯一原因是當前 Relay 接受這種格式以替代常規數據清理設置。

以下文檔探討了 Relay 使用和執行的高級數據清理配置的語法和語義。有時，這也稱為 PII 清理。

一個基本的例子

假設您有一條異常消息，不幸的是，其中包含不應該存在的 IP 地址。你會寫：

{ 
  "applications": { 
    "$string": ["@ip:replace"] 
  } 
} 

它讀作 “替換所有字符串中的所有 IP 地址”，或 "將 @ip:replace 應用于所有 $string 字段"。

@ip:replace 稱為規則，$string 稱為選擇器。

• https://develop.sentry.dev/pii/selectors/

內置規則

默認存在以下規則：

• @ip:replace 和 @ip:hash 用于替換 IP 地址。
• @imei:replace 和 @imei:hash 用于替換 IMEI。
• @mac:replace、@mac:mask 和 @mac:hash 用于匹配 MAC 地址。
• @email:mask、@email:replace 和 @email:hash 用于匹配 email 地址。
• @creditcard:mask、@creditcard:replace 和 @creditcard:hash 用于匹配信用卡號碼。
• @userpath:replace 和 @userpath:hash 用于匹配本地路徑(例如 C:/Users/foo/)。
• @password:remove 用于刪除密碼。在這種情況下，我們對字段的 key 進行 pattern 匹配，無論它是否包含 password、credentials 或類似的字符串。
• @anything:remove、@anything:replace 和 @anything:hash 用于刪除、替換或 hash 任何值。它本質上等同于通配符正則表達式，但它也比字符串匹配得多。

編寫自己的規則

規則一般由兩部分組成：

• 規則類型 描述要匹配的內容。有關詳盡列表，請參閱PII 規則類型。
  • https://develop.sentry.dev/pii/types/
• 規則編輯方法 描述了如何處理匹配。有關列表，請參閱PII 編輯方法。
  • https://develop.sentry.dev/pii/methods/

每個頁面都帶有示例。通過將這些示例粘貼到 Piinguin 的 “PII 配置” 列并單擊字段以獲取建議來嘗試這些示例。

• https://getsentry.github.io/piinguin/

交互式編輯

解決此問題的最簡單方法是，如果您已經擁有來自某個 SDK 的原始 JSON payload。轉到我們的 PII 配置編輯器 Piinguin，然后：

• 粘貼到原始事件中
• 點擊你想要消除的數據
• 粘貼其他有效負載并查看它們是否正常，如有必要，請轉到步驟 2。

在對配置進行迭代后，將其粘貼回位于 .relay/projects/ .json 的項目配置中

例如：

{ 
  "publicKeys": [ 
    { 
      "publicKey": "___PUBLIC_KEY___", 
      "isEnabled": true 
    } 
  ], 
  "config": { 
    "allowedDomains": ["*"], 
    "piiConfig": { 
      "rules": { 
        "device_id": { 
          "type": "pattern", 
          "pattern": "d/[a-f0-9]{12}", 
          "redaction": { 
            "method": "hash" 
          } 
        } 
      }, 
      "applications": { 
        "freeform": ["device_id"] 
      } 
    } 
  } 
} 

PII 規則類型

pattern

{ 
  "rules": { 
    "hash_device_id": { 
      "type": "pattern", 
      "pattern": "d/[a-f0-9]{12}", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["hash_device_id"] 
  } 
} 

imei

: 匹配 IMEI 或 IMEISV。

{ 
  "rules": { 
    "hash_imei": { 
      "type": "imei", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["hash_imei"] 
  } 
} 

mac

: 匹配一個 MAC 地址。

{ 
  "rules": { 
    "hash_mac": { 
      "type": "mac", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["hash_mac"] 
  } 
} 

:ip

匹配任何 IP 地址。

{ 
  "rules": { 
    "hash_ip": { 
      "type": "ip", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["hash_ip"] 
  } 
} 

creditcard

: 匹配信用卡號。

{ 
  "rules": { 
    "hash_cc": { 
      "type": "creditcard", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["hash_cc"] 
  } 
} 

userpath

: 匹配本地路徑(例如C:/Users/foo/)。

{ 
  "rules": { 
    "hash_userpath": { 
      "type": "userpath", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["hash_userpath"] 
  } 
} 

anything

: 匹配任何值。這基本上等同于通配符正則表達式。

例如，要刪除所有字符串：

{ 
  "rules": { 
    "remove_everything": { 
      "type": "anything", 
      "redaction": { 
        "method": "remove" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["remove_everything"] 
  } 
} 

multiple

: 將多個規則合二為一。這是一個析取 (OR)：有問題的字段必須只匹配一個規則來匹配組合規則，而不是全部。

{ 
  "rules": { 
    "remove_ips_and_macs": { 
      "type": "multiple", 
      "rules": [ 
        "@ip", 
        "@mac" 
      ], 
      "hide_rule": false,  // Hide the inner rules when showing which rules have been applied. Defaults to false. 
      "redaction": { 
        "method": "remove" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["remove_ips_and_macs"] 
  } 
} 

alias

: 別名一個規則到另一個。這與 multiple 相同，只是您只能包裝一個規則。

{ 
  "rules": { 
    "remove_ips": { 
      "type": "multiple", 
      "rule": "@ip", 
      "hide_rule": false,  // Hide the inner rule when showing which rules have been applied. Defaults to false. 
      "redaction": { 
        "method": "remove" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["remove_ips"] 
  } 
} 

PII 編輯方法

remove

: 刪除整個字段。Relay 可以選擇將其設置為 null 或完全刪除它。

{ 
  "rules": { 
    "remove_ip": { 
      "type": "ip", 
      "redaction": { 
        "method": "remove" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["remove_ip"] 
  } 
} 

replace

 

: 用 static string 替換 key。

{ 
  "rules": { 
    "replace_ip": { 
      "type": "ip", 
      "redaction": { 
        "method": "replace", 
        "text": [censored]" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["replace_ip"] 
  } 
} 

mask

: 用 "masking(掩碼)" 字符 * 替換匹配字符串的每個字符。與 replace 相比，它保留了原始字符串的長度。

{ 
  "rules": { 
    "mask_ip": { 
      "type": "ip", 
      "redaction": { 
        "method": "mask" 
      } 
    } 
  }, 
  "applications": { 
    "$string": ["mask_ip"] 
  } 
} 

hash

: 用它自己的 hash 版本替換字符串。相等的字符串將產生相同的 hash 值，因此，例如，如果您決定對用戶 ID 進行散列處理而不是替換或刪除它，您仍將獲得受影響用戶的準確計數。

{ 
  "rules": { 
    "hash_ip": { 
      "type": "ip", 
      "redaction": { 
        "method": "hash" 
      } 
    } 
  } 
  "applications": { 
    "$string": ["mask_ip"] 
  } 
} 

PII 選擇器

選擇器允許您將規則限制在事件的某些部分。這對于按變量/字段名稱從事件中無條件刪除某些數據很有用，但也可用于對真實數據進行保守的測試規則。

數據清理始終適用于原始事件負載。請記住，UI 中的某些字段在 JSON schema 中的調用方式可能不同。在查看事件時，應該始終存在一個名為 "JSON" 的鏈接，可讓您查看數據清理器看到的內容。

例如，在 UI 中稱為 "Additional Data" 的內容在事件負載中稱為 extra。要刪除名為 foo 的特定 key，您可以編寫：

[Remove] [Anything] from [extra.foo] 

另一個例子。Sentry 知道兩種錯誤消息：異常消息和頂級日志消息。以下是由 SDK 發送的此類事件負載(可從 UI 下載)的示例：

{ 
  "logentry": { 
    "formatted": "Failed to roll out the dinglebop" 
  }, 
  "exceptions": { 
    "values": [ 
      { 
        "type": "ZeroDivisionError", 
        "value": "integer division or modulo by zero" 
      } 
    ] 
  } 
} 

由于 "error message" 取自 exception 的 value， 而 "message" 取自 logentry，因此我們必須編寫以下內容以將兩者從事件中刪除：

[Remove] [Anything] from [exception.value] 
[Remove] [Anything] from [logentry.formatted] 

布爾邏輯

您可以使用布爾邏輯組合選擇器。

• 以 ! 為前綴來反轉選擇器。foo 匹配 JSON key foo，而 !foo 匹配除 foo 之外的所有內容。
• 使用 && 構建連詞 (AND)，例如：foo && !extra.foo 以匹配 key foo，除非在 extra 內部。
• 使用 || 構建析取 (OR)，例如：foo || bar 匹配 foo 或 bar。

通配符

• ** 匹配所有子路徑，因此 foo.** 匹配 foo 中的所有 JSON 鍵。
• * 匹配單個路徑項，因此 foo.* 匹配比 foo 低一級的所有 JSON 鍵。

值類型

使用以下內容按 JSON-type 選擇子節：

• $string 匹配任何字符串值
• $number 匹配任何整數或浮點值
• $datetime 匹配事件中代表時間戳的任何字段
• $array 匹配任何 JSON 數組值
• $object 匹配任何 JSON 對象

使用以下方法選擇 schema 的已知部分：

• $exception 匹配 {"exception": {"values": [...]}} 中的單個異常實例
• $stacktrace 匹配一個堆棧跟蹤實例
• $frame 匹配一個幀
• $request 匹配事件的 HTTP 請求上下文
• $user 匹配事件的用戶上下文
• $logentry(也適用于 message 屬性)
• $thread 匹配 {"threads": {"values": [...]}} 中的單個線程實例
• $breadcrumb 匹配 {"breadcrumbs": [...]} 中的單個面包屑
• $span 匹配一個 trace span
• https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing/
• $sdk 匹配 {"sdk": ...} 中的 SDK 上下文

示例

• 刪除 event.user:

[Remove] [Anything] from [$user] 

• 刪除所有幀局部變量：

[Remove] [Anything] from [$frame.vars] 

轉義特殊字符

如果要匹配的對象 key 包含空格或特殊字符，可以使用引號將其轉義：

[Remove] [Anything] from [extra.'my special value'] 

這與 附加數據 中的 key my special value 相匹配。

要在引號內轉義 '(單引號)，請將其替換為 ''(兩個引號)：

[Remove] [Anything] from [extra.'my special '' value'] 

 

這與 附加數據 中的key my special ' value 值相匹配。