本文转载自微信公众号「黑客下午茶」，作者少 。请联系黑客下午茶微信官方账号转载本文。
探索 Snuba 数据模型
为了构建 Snuba 查询的第一步是知道你应该查询哪个数据集，你应该选择哪些实体和每个实体 schema 是什么。
请参考 数据集和实体的介绍Snuba 数据模型部分。
- https://getsentry.github.io/snuba/architecture/datamodel.html
在这个模块中可以找到数据集。每个数据集都是引用实体的类别。
- https://github.com/getsentry/snuba/blob/master/snuba/datasets/factory.py
通过 ，可以使用系统中的实体列表snuba entity 命令发现：
会返回如下内容：
一旦我们找到了我们感兴趣的实体，我们就需要知道在实体上声明的 schema 和 relationship。同样的命令描述了一个实体：
会返回：
它提供列表及其类型以及与数据模型中定义的其他实体的关系。
准备对 Snuba 的查询
Snuba 查询语言称为 SnQL。它记录在 SnQL 查询语言部分。所以本节不重复。
- https://getsentry.github.io/snuba/language/snql.html
有一个 python sdk 可用于建筑 Snuba 查询可用于任何 Python 客户端，包括 Sentry。snuba-sdk。
- https://github.com/getsentry/snuba-sdk
查询表示为 Query 对象，如:
更多关于如何构建查询的详细信息，请参见 sdk 文档。
- https://getsentry.github.io/snuba-sdk/
一旦查询对象准备就绪，就可以发送到 Snuba。
使用 Sentry 向 Snuba 发送查询
查询 Snuba 通过 最常见的用例Sentry。本节说明如何在 Sentry 代码库中构建查询并发送到 Snuba。
Sentry 导入上述 Snuba sdk。这是构建 Snuba 查询推荐方法。
一旦创建Query 对象，Sentry 提供的 Snuba client api 可用于将查询发送至 Snuba。
api 在这个模块中。负责缓存、重试和批量查询。
- https://github.com/getsentry/sentry/blob/master/src/sentry/utils/snuba.py#L667
该方法返回字典，包括响应中的数据和其他元数据：
data 部分是列表，每行字典。meta 包含响应中包含的列表，其数据类型为 Clickhouse 推断。
通过 Web UI 发送测试查询
Snuba 有最小的 可用于发送查询Web UI。 可在本地运行Snuba，通过 http://localhost:1218/[DATASET NAME]/snql 访问 Web UI。
应该在 query 属性中提供 SnQL 查询，响应结构与上一节讨论相同。
通过 curl 发送查询
Web UI 仅将 payload 作为 POST 发送。因此，使用 curl 或任何其他 HTTP 客户端可以实现相同的结果。
请求和响应格式
请求格式可以看到请求格式：
- query 包含字符串形式SnQL 查询。
- dataset 是数据集的名称(如果还没有)url 中指定。
- debug 使 Snuba 在响应中提供详细的统计信息，包括 Clickhouse 查询。
- consistent 强制 Clickhouse 查询以单线程模式执行，如果 Clickhouse 表被复制，它将被迫 Snuba 总是命中同一个节点。它可以保证顺序的一致性，因为它是消费者默认写入的节点。这是通过设置为 in_order 负载平衡 Clickhouse 实现属性。
- https://clickhouse.tech/docs/en/operations/settings/settings/#load_balancing-in_order
- turbo 为 TURBO_SAMPLE_RATE Snuba 设置中定义的查询设置采样率。它还可以防止 Snuba 将 FINAL 模式应用于 Clickhouse 查询，防止更换后正确结果。
Snuba 可使用 4 http code 回应。200 表示查询成功。如果查询不能正确验证，则为 400。500 通常意味着 Clickhouse 相关问题(从加班到连接)，尽管 Snuba 仍然无法提前识别一些无效查询。Snuba 有内部速率限制器，所以 429 也是可能的返回码。
成功查询的响应格式与上述讨论相同。完整版本如下( debug 模式下)
timing 部分包括查询时间戳和持续时间。有趣的是，持续时间分为几个阶段：marks_ms。
sql 元素是 Clickhouse 查询。
stats 字典包含以下 key
- clickhouse_table 是 snuba 查询处理过程中选择的表。
- final 表示 Snuba 是否决定向 Clickhouse 发送 FINAL 查询，这将迫使 Clickhouse 立即应用相关合并(Merge Tree)。细节
- https://clickhouse.tech/docs/en/sql-reference/statements/select/from/#select-from-final
- sample 是应用的采样率。
- project_rate 查询时 Snuba 每秒收到的特定项目的请求数。
- project_concurrent 是查询过程中涉及特定项目的并发查询数。
- global_rate 与 project_rate 是一样的，但不专注于一个项目。
- global_concurrent 与 project_concurrent 是一样的，但不专注于一个项目。
- query_id 是此查询的唯一标识符。
查询验证问题通常采用以下格式：
Clickhouse 错误会有类似的结构。type 字段将显示 clickhouse，该消息将包含关于异常的详细信息。相反，在 Clickhouse 在错误的情况下，实际执行了查询，因此有所有的时间和统计信息来描述成功的查询。