Sentry 监控 - Search 搜索查询实战

系列

公众号：黑客下午茶

语法
- 使用 OR 和 AND
- 同一个 Key 上的多个值
- 显式 Tag 语法
- 高级
  - 排除
  - 通配符(*)
可搜索的属性
- Issue 属性
- Event 属性
- 自定义 Tag
已保存搜索
- 推荐搜索
- 固定搜索
  - 更改固定搜索
  - 固定推荐搜索
- 组织范围内保存的搜索
  - 创建组织范围的已保存搜索
  - 删除组织范围内已保存的搜索

语法

搜索查询是使用 key:value 模式构建的，最后是可选的原始搜索。每个 key:value 都是一个 token，可选的原始搜索本身就是一个 token。key:value 对 tokens 被视为 issue 或 event 属性。可选的原始搜索被视为单个 token 并搜索事件标题/消息(title/message)。

例如：

is:resolved user.username:"Jane Doe" server:web-8 example error

在上面的例子中，有三个 key（is:, user.username:, server:），但是有四个 token：

is:resolved
user.username:"Jane Doe"
server:web-8
example error

Token is:resolved 和 user.username:"Jane Doe" 是标准搜索 token，因为两者都使用保留关键字。有关适当的关键字用法，请参阅 Issue 属性和 Event 属性。token server:web-8 指向 Sentry SDK 发送的自定义 tag。

token 示例错误使用可选的原始搜索并作为 issue 搜索查询的一部分传递（使用类似于 SQL 的 CONTAINS 匹配）。使用可选的原始搜索时，您可以提供一个字符串，查询将使用整个字符串。

使用 `OR` 和 `AND`

OR 和 AND 搜索条件仅适用于 Discover、Performance 和 Metric Alerts。

Token 之间使用 OR 和 AND，并使用括号 () 对条件进行分组。AND 也可用于非聚合(non-aggregate)和聚合(aggregate)之间。但是，OR 不能。

非聚合基于特定标签或属性过滤数据。例如，user.username:jane 是一个非聚合字段。
在数字尺度(numerical scales)上聚合过滤数据。例如，count() 是一个聚合函数，而 count():>100 是一个聚合过滤器。

使用 OR 条件的一些示例：

# 一个有效的 `OR` 查询

browser:Chrome OR browser:Opera

# 一个无效的 `OR` 查询

user.username:janedoe OR count():>100

此外，查询优先于 OR 之前的 AND。例如，“x AND y OR z” 与 “(x AND y) OR z” 相同。括号可用于更改分组。例如，“x AND (y OR z)”。

同一个 `Key` 上的多个值

您可以通过将值放在列表中来搜索同一 key 的多个值。例如，“x:[value1, value2]” 将找到与 “x:value1 OR x:value2” 相同的结果。执行此操作时，搜索将返回与任何搜索词匹配的问题/事件(issue/event)。

使用值列表搜索相同 key 的示例：

release:[12.0, 13.0]

目前，您不能对关键字 is 使用这种类型的搜索。

显式 `Tag` 语法

我们建议您永远不要使用保留关键字（例如 project_id）作为 tag。但如果这样做，则必须使用以下语法进行搜索：

tags[project_id]:tag_value

高级

排除

默认情况下，搜索词使用 AND 运算符；也就是说，它们返回与所有搜索词匹配的问题/事件(issues/events)的交集。

要改变这一点，您可以使用否定运算符 ! 排除搜索参数。

is:unresolved !user.email:example@customer.com

在上面的示例中，搜索查询返回所有未解决且未影响电子邮件地址为 example@customer.com 的用户的 Issues。

通配符(`*`)

搜索支持通配符 * 作为特定字符和字符串的占位符。

browser:"Safari 11*"

在上面的示例中，搜索查询将匹配 browser 值，例如 “Safari 11.0.2”、“Safari 11.0.3” 等。

你也可以像这样组合运算符：

!message:"*Timeout"

在上面的示例中，搜索查询返回的结果没有的 message 值，如 ConnectionTimeout、ReadTimeout 等。

可搜索的属性

Sentry 的搜索为您提供了保留关键字，例如 is、user、server 和 browser，您可以使用它们来搜索 issue 和 event 的属性。您还可以创建要搜索的自定义标签。以下是所有可用问题和事件搜索词的规范列表。

`Issue` 属性

Issue 是一个或多个事件的集合。可搜索的属性包括工作流状态(workflow status)、分配(assignment)、聚合计数(aggregate counts)和年龄(age)。

以下是 Sentry 保留和已知的 issue 级的 key 和 token 列表：

Key/Token	描述
age	限制结果自 `age` 以来产生的 `issue`。语法类似于 `Unix find` 命令。支持后缀: `m -> minutes`, `h -> hours`, `d -> days`, `w -> weeks`
age:-24h	返回过去 `24` 小时内的新 `issue`。
age:+12h	返回超过 `12` 小时的 `issue`。
age:+12h age:-24h	返回超过 `12` 到 `24` 小时之前创建的 `issue`。
assigned	筛选 `issue` 分配给的用户。值可以是 `user ID`(您的 `email` 地址)、`me` 代表您自己、`me_or_none` 代表您自己或没有受理人，或者 `#team-name`。
assigned_or_suggested	过滤 `assigned` 或 `suggested` 分配问题的用户或团队。建议的受理人由匹配的`所有权规则(ownership rules)`和`可疑提交(suspect commits)`确定。值可以是 `user ID`(您的 `email` 地址)、`me` 代表您自己、`me_or_none` 代表您自己或没有受理人/建议，或者 `#team-name`。
bookmarks	过滤为 `issue` 添加书签的用户。值可以是 `user ID`(您的 `email` 地址) 或 `me` 代表您自己。
first-release	将结果限制为在给定版本中首次出现的 `issue`。与发布版本完全匹配，或 `first-release:latest` 选择最新版本。
has	将结果限制为具有任何 `tag` 值的 `issue`。
has:user	将结果限制为具有标记 `user` 值的 `issue`。
is	筛选 `issue` 的各种属性。
is:unresolved is:resolved is:ignored	根据 `issue` 的状态进行筛选。
is:assigned is:unassigned	根据是否已分配 `issue` 返回 `issue`。
is:linked is:unlinked	根据 `issue` 是否链接（到外部 `issue` 跟踪器）返回 `issue`。
lastSeen	将结果限制为自(`since`)或直到(`until`)给定时间点最后出现的问题。用法类似于 `age` token（见上文）。
lastSeen:+30d	返回 `issue` 最近一次出现在 `30` 天前或更久之前。
lastSeen:-2d	返回最近两天内出现的 `issue`。
timesSeen	将结果限制在精确地、至少或最多某些次数的 `issue` 上。完全匹配：`timesSeen:10`。上限或下限 `token`：`timesSeen:>10, timesSeen:>=10, timesSeen:<10, timesSeen:<=10`

`Event` 属性

Events 是使用 Sentry SDK 捕获的底层事件数据（read: errors 和 transactions）。

在 “Issues” 页面中搜索事件属性时，搜索将返回具有与提供的事件过滤器匹配的一个或多个事件的任何 issue。

以下是 Sentry 保留和已知的事件级(event-level) key 和 token 列表：

Key/Token	描述
location	将结果限制为具有匹配 `location` 的事件。
message	将结果限制为具有匹配 `message` 的事件。
environment	将结果限制为用匹配 `environment` 标记的事件。
release	将结果限制为带有匹配版本标记的事件。您可以创建一个与发布版本完全匹配的 `token`，或者 `release:latest` 选择最新的版本。
release.package release.version release.build	将结果限制为用匹配语义版本标记的事件。支持范围和通配符(`*`)。
release.stage	将结果限制为带有匹配发布阶段标记的 `release`。
transaction	将结果限制为标有 `URL template/job` 名称的事件。
geo.country_code geo.region geo.city	将结果限制为由地理区域触发的事件。
http.method http.referer http.url	根据 HTTP 请求上下文限制结果。
user.id user.email user.username user.ip	将结果限制为影响给定用户的事件。
event.timestamp	将结果限制为发生在给定时间戳的事件。该过滤器可以通过两次以提供一个范围。 2016 年 1 月 2 日发生的事件：`event.timestamp:2016-01-02` `01:00` 和 `02:00` (UTC) 之间的事件：`event.timestamp:>=2016-01-02T01:00:00 event.timestamp:<2016-01-02T02:00:00` 可以使用以下比较运算符：大于(`>`)、大于或等于(`>=`)、小于(`<`)、小于或等于(`<=`)
device.arch device.battery_level device.brand device.charging device.locale device.model_id device.name device.online device.orientation device.simulator device.uuid	将结果限制为用特定设备属性标记的事件。
os.build os.kernel_version	将结果限制为用特定操作系统属性标记的事件。
stack.abs_path stack.filename stack.function stack.module stack.package stack.stack_level stack.lineno	将结果限制为具有匹配堆栈属性的事件。对于 `Native SDK` 用户，`stack.package` 是 `stack.module` 的 `Native` 等价项。
error.type error.value error.mechanism error.handled	将结果限制为具有匹配错误属性的事件。

自定义 `Tag`

此外，您可以使用您指定为 token 的任何 tag。标签是分配给事件的各种 key/value 对，您可以稍后将它们用作细分或快速访问以查找相关事件。

大多数 SDK 通常支持通过配置 scope 来配置 tag。

标签的几种常见用途包括：

服务器的 hostname
您的平台版本（例如，iOS 5.0）
用户的 language

已保存搜索

在 Issues 的 “Saved Searches” 选项卡中，您可以访问推荐的搜索、固定您认为最有用的搜索并利用组织范围内的已保存搜索。

固定搜索

您可以固定搜索，它将成为您在 Issues 页面上看到的默认视图。固定搜索仅对您可见，并且与您的项目相关。

在搜索栏中键入搜索词。
单击该搜索旁边的图钉图标。
固定后，Sentry 会将搜索添加到 “Saved Searches” 下拉列表中。文本中的搜索标签将显示为“我的固定搜索(My Pinned Search)”。

更改固定搜索

要更改您的固定搜索：

选择您的固定搜索。取消单击图钉图标。您的默认搜索将返回到 is:unresolved。
运行另一个搜索。单击图钉图标。列为“我的固定搜索(My Pinned Search)”的查询现在将成为新的固定查询，取代原来的查询。

固定推荐搜索

您可以像固定任何其他搜索一样固定推荐的搜索。当您选择了推荐的搜索，并且推荐的搜索查询会填充搜索栏时，请将其固定。

组织范围内保存的搜索

创建组织范围的已保存搜索

Owner 和 manager 可以通过创建自定义保存搜索为其组织创建持久视图。这些保存的搜索不与特定项目相关联，而是与整个组织的所有项目（和用户）相关联。

在搜索栏中键入搜索，单击操作菜单（三个点）。选择“创建保存的搜索(Create Saved Search)”。

在打开的 modal 中，为搜索命名并设置 issues 列表的排序顺序。您还可以在此处更新查询。然后点击 “Save”。

然后该视图将成为 “Saved Search” 下拉列表的一部分。

删除组织范围内已保存的搜索

此操作仅适用于组织 owner 或 manager。

当您将鼠标悬停在自定义保存的搜索(saved search)上时，搜索名称旁边会显示垃圾桶图标。单击垃圾桶图标以从下拉列表中删除自定义保存的搜索。

公众号：黑客下午茶