Sentry 监控 - Snuba 数据中台架构(编写和测试 Snuba 查询)

系列

本指南将引导您完成编写和测试 Snuba 查询的过程。

探索 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 命令找到：

snuba entities list

会返回如下内容：

Declared Entities:

discover

errors

events

groups

groupassignee

groupedmessage

.....

一旦我们找到了我们感兴趣的实体，我们就需要了解在该实体上声明的 schema 和 relationship。相同的命令描述了一个实体：

snuba entities describe groupedmessage

会返回：

Entity groupedmessage

    Entity schema

    --------------------------------

    offset UInt64

    record_deleted UInt8

    project_id UInt64

    id UInt64

    status Nullable(UInt8)

    last_seen Nullable(DateTime)

    first_seen Nullable(DateTime)

    active_at Nullable(DateTime)

    first_release_id Nullable(UInt64)

    Relationships

    --------------------------------

        groups

        --------------------------------

        Destination: events

        Type: LEFT

            Join keys

            --------------------------------

            project_id = LEFT.project_id

            id = LEFT.group_id

它提供列的列表及其类型以及与数据模型中定义的其他实体的关系。

准备对 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 对象，如：

query = Query(

    dataset="discover",

    match=Entity("events"),

    select=[

        Column("title"),

        Function("uniq", [Column("event_id")], "uniq_events"),

    ],

    groupby=[Column("title")],

    where=[

        Condition(Column("timestamp"), Op.GT, datetime.datetime(2021, 1, 1)),

        Condition(Column("project_id"), Op.IN, Function("tuple", [1, 2, 3])),

    ],

    limit=Limit(10),

    offset=Offset(0),

    granularity=Granularity(3600),

)

有关如何构建查询的更多详细信息，请参见 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": [

        {

            "title": "very bad",

            "uniq_events": 2

        }

    ],

    "meta": [

        {

            "name": "title",

            "type": "String"

        },

        {

            "name": "uniq_events",

            "type": "UInt64"

        }

    ],

    "timing": {

        ... details ...

    }

}

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 模式下）

{

    "data": [],

    "meta": [

        {

            "name": "title",

            "type": "String"

        }

    ],

    "timing": {

        "timestamp": 1621038379,

        "duration_ms": 95,

        "marks_ms": {

            "cache_get": 1,

            "cache_set": 4,

            "execute": 39,

            "get_configs": 0,

            "prepare_query": 10,

            "rate_limit": 4,

            "validate_schema": 34

        }

    },

    "stats": {

        "clickhouse_table": "errors_local",

        "final": false,

        "referrer": "http://localhost:1218/events/snql",

        "sample": null,

        "project_rate": 0,

        "project_concurrent": 1,

        "global_rate": 0,

        "global_concurrent": 1,

        "consistent": false,

        "result_rows": 0,

        "result_cols": 1,

        "query_id": "f09f3f9e1c632f395792c6a4bfe7c4fe"

    },

    "sql": "SELECT (title AS _snuba_title) FROM errors_local PREWHERE equals((project_id AS _snuba_project_id), 1) WHERE equals(deleted, 0) AND greaterOrEquals((timestamp AS _snuba_timestamp), toDateTime('2021-05-01T00:00:00', 'Universal')) AND less(_snuba_timestamp, toDateTime('2021-05-11T00:00:00', 'Universal')) LIMIT 1000 OFFSET 0"

}

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 是此查询的唯一标识符。

查询验证问题通常采用以下格式：

{

    "error": {

        "type": "invalid_query",

        "message": "missing >= condition on column timestamp for entity events"

    }

}

Clickhouse 错误将具有类似的结构。type 字段将显示 clickhouse，该消息将包含有关异常的详细信息。与查询验证错误相反，在 Clickhouse 错误的情况下，实际执行了查询，因此存在为成功查询描述的所有时间和统计信息。