本文档描述了一种我们希望最终对用户隐藏的配置格式。该页面仍然存在的唯一原因是当前 Relay 接受这种格式以替代常规数据清理设置。
以下文档探讨了 Relay 使用和执行的高级数据清理配置的语法和语义。有时,这也称为 PII 清理。
一个基本的例子
假设您有一条异常消息,不幸的是,其中包含不应该存在的 IP 地址。你会写:
{
"applications": {
"$string": ["@ip:replace"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
它读作 “替换所有字符串中的所有 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/
例如:
{
"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"]
}
}
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
- 16.
- 17.
- 18.
- 19.
- 20.
- 21.
- 22.
- 23.
- 24.
- 25.
PII 规则类型
pattern
{
"rules": {
"hash_device_id": {
"type": "pattern",
"pattern": "d/[a-f0-9]{12}",
"redaction": {
"method": "hash"
}
}
},
"applications": {
"$string": ["hash_device_id"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
imei
: 匹配 IMEI 或 IMEISV。
{
"rules": {
"hash_imei": {
"type": "imei",
"redaction": {
"method": "hash"
}
}
},
"applications": {
"$string": ["hash_imei"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
mac
: 匹配一个 MAC 地址。
{
"rules": {
"hash_mac": {
"type": "mac",
"redaction": {
"method": "hash"
}
}
},
"applications": {
"$string": ["hash_mac"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
:ip
匹配任何 IP 地址。
{
"rules": {
"hash_ip": {
"type": "ip",
"redaction": {
"method": "hash"
}
}
},
"applications": {
"$string": ["hash_ip"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
creditcard
: 匹配信用卡号。
{
"rules": {
"hash_cc": {
"type": "creditcard",
"redaction": {
"method": "hash"
}
}
},
"applications": {
"$string": ["hash_cc"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
userpath
: 匹配本地路径(例如C:/Users/foo/)。
{
"rules": {
"hash_userpath": {
"type": "userpath",
"redaction": {
"method": "hash"
}
}
},
"applications": {
"$string": ["hash_userpath"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
anything
: 匹配任何值。这基本上等同于通配符正则表达式。
例如,要删除所有字符串:
{
"rules": {
"remove_everything": {
"type": "anything",
"redaction": {
"method": "remove"
}
}
},
"applications": {
"$string": ["remove_everything"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
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"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
- 16.
- 17.
- 18.
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"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
- 15.
PII 编辑方法
remove
: 删除整个字段。Relay 可以选择将其设置为 null 或完全删除它。
{
"rules": {
"remove_ip": {
"type": "ip",
"redaction": {
"method": "remove"
}
}
},
"applications": {
"$string": ["remove_ip"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
replace
: 用 static string 替换 key。
{
"rules": {
"replace_ip": {
"type": "ip",
"redaction": {
"method": "replace",
"text": [censored]"
}
}
},
"applications": {
"$string": ["replace_ip"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
- 14.
mask
: 用 "masking(掩码)" 字符 * 替换匹配字符串的每个字符。与 replace 相比,它保留了原始字符串的长度。
{
"rules": {
"mask_ip": {
"type": "ip",
"redaction": {
"method": "mask"
}
}
},
"applications": {
"$string": ["mask_ip"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
hash
: 用它自己的 hash 版本替换字符串。相等的字符串将产生相同的 hash 值,因此,例如,如果您决定对用户 ID 进行散列处理而不是替换或删除它,您仍将获得受影响用户的准确计数。
{
"rules": {
"hash_ip": {
"type": "ip",
"redaction": {
"method": "hash"
}
}
}
"applications": {
"$string": ["mask_ip"]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
PII 选择器
选择器允许您将规则限制在事件的某些部分。这对于按变量/字段名称从事件中无条件删除某些数据很有用,但也可用于对真实数据进行保守的测试规则。
数据清理始终适用于原始事件负载。请记住,UI 中的某些字段在 JSON schema 中的调用方式可能不同。在查看事件时,应该始终存在一个名为 "JSON" 的链接,可让您查看数据清理器看到的内容。
例如,在 UI 中称为 "Additional Data" 的内容在事件负载中称为 extra。要删除名为 foo 的特定 key,您可以编写:
[Remove] [Anything] from [extra.foo]
- 1.
另一个例子。Sentry 知道两种错误消息:异常消息和顶级日志消息。以下是由 SDK 发送的此类事件负载(可从 UI 下载)的示例:
{
"logentry": {
"formatted": "Failed to roll out the dinglebop"
},
"exceptions": {
"values": [
{
"type": "ZeroDivisionError",
"value": "integer division or modulo by zero"
}
]
}
}
- 1.
- 2.
- 3.
- 4.
- 5.
- 6.
- 7.
- 8.
- 9.
- 10.
- 11.
- 12.
- 13.
由于 "error message" 取自 exception 的 value, 而 "message" 取自 logentry,因此我们必须编写以下内容以将两者从事件中删除:
[Remove] [Anything] from [exception.value]
[Remove] [Anything] from [logentry.formatted]
- 1.
- 2.
布尔逻辑
您可以使用布尔逻辑组合选择器。
- 以 ! 为前缀来反转选择器。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]
- 1.
- 删除所有帧局部变量:
[Remove] [Anything] from [$frame.vars]
- 1.
转义特殊字符
如果要匹配的对象 key 包含空格或特殊字符,可以使用引号将其转义:
[Remove] [Anything] from [extra.'my special value']
- 1.
这与 附加数据 中的 key my special value 相匹配。
要在引号内转义 '(单引号),请将其替换为 ''(两个引号):
[Remove] [Anything] from [extra.'my special '' value']
- 1.
这与 附加数据 中的key my special ' value 值相匹配。