Snuba 镜像文档

镜像概述

注意：该镜像已弃用。自托管Sentry镜像已从DockerHub迁移至GitHub容器 registry，新镜像地址：[***]

Snuba是Sentry的存储服务，提供对事件的快速搜索、过滤和任意字段聚合能力，依赖ClickHouse作为存储后端和Redis进行缓存。

核心功能与特性

• 与Sentry深度集成，作为事件数据存储和查询引擎
• 支持通过ClickHouse进行高效数据存储和查询
• 提供HTTP API接口，支持复杂事件查询、聚合和过滤
• 支持标签查询，包括已知标签名查询和动态标签键/值查询
• 与Redis集成，用于缓存和临时数据存储

使用场景与适用范围

适用于Sentry自托管环境，用于存储、查询和分析事件数据，尤其适合需要高效处理大量事件并进行复杂聚合分析的场景。主要供Sentry开发和运维人员使用。

使用方法与配置说明

Sentry集成配置

修改Sentry配置文件

在~/.sentry/sentry.conf.py中添加/修改以下配置：

python
SENTRY_SEARCH = 'sentry.search.snuba.EventsDatasetSnubaSearchBackend'
SENTRY_TSDB = 'sentry.tsdb.redissnuba.RedisSnubaTSDB'
SENTRY_EVENTSTREAM = 'sentry.eventstream.snuba.SnubaEventStream'

启动服务

bash
sentry devservices up

访问ClickHouse客户端

类似psql的ClickHouse命令行客户端：

bash
docker exec -it sentry_clickhouse clickhouse-client

验证数据写入

数据存储在sentry_local表中，可通过以下命令检查数据量：

sql
select count() from sentry_local;

开发环境要求（仅开发Snuba时需要）

Snuba开发需依赖以下服务：

1. ClickHouse服务器，默认通过CLICKHOUSE_HOST（默认localhost）访问
2. Redis实例，默认通过REDIS_HOST（默认localhost）的6379端口访问

快速启动依赖服务（需先配置Sentry）：

bash
sentry devservices up --exclude=snuba

安装与运行（仅开发Snuba时需要）

bash
# 创建并激活虚拟环境
mkvirtualenv snuba --python=python3.7
workon snuba

# 安装依赖
make install-python-dependencies
make install-librdkafka
make setup-git

# 启动API服务器
snuba api

API端点

Snuba默认在1218端口提供HTTP API，主要端点包括：

• /：首页
• /dashboard：查询仪表板
• /query：ClickHouse查询端点
• /config：运行时配置控制台

配置参数

配置项位于settings.py，主要包括：

• CLICKHOUSE_HOST：ClickHouse服务主机名（默认localhost）
• REDIS_HOST：Redis服务主机名（默认localhost）
• DATASET_MODE：数据集模式，"local"表示使用本地表而非分布式表

测试方法

基础测试

bash
pip install -e .
make test

与Sentry集成测试

1. 启动Snuba开发服务：

bash
workon snuba
git checkout your-snuba-branch
snuba api

2. 在另一个终端启动Sentry依赖服务：

bash
workon sentry
git checkout master
git pull
sentry devservices up --exclude=snuba

3. 运行Sentry测试：

bash
USE_SNUBA=1 make test-acceptance
USE_SNUBA=1 make test-snuba
make test-python  # 注意：当前带USE_SNUBA标志时Python测试可能无法通过

查询指南

查询Payload结构

通过/query端点提交JSON格式查询，示例：

json
{
    "project": [1, 2],
    "selected_columns": ["tags[environment]"],
    "aggregations": [
        ["max", "received", "last_seen"]
    ],
    "conditions": [
        ["tags[environment]", "=", "prod"]
    ],
    "from_date": "2011-07-01T19:54:15",
    "to_date": "2018-07-06T19:54:15",
    "granularity": 3600,
    "groupby": ["group_id", "time"],
    "having": [],
    "issues": [],
    "sample": 0.5
}

主要字段说明

• selected_columns：额外选择的列，与groupby字段不可同时使用（可能导致查询无效）
• aggregations：聚合函数数组，格式为[function, column, alias]，如["max", "received", "last_seen"]。特殊函数如count()表示为["count()", null, "item_count"]，topK类函数如["top5", "environment", "top_five_envs"]会生成topK(5)(environment) AS top_five_envs
• conditions：过滤条件数组，格式为[column_name, operation, literal]，支持操作符：>, <, >=, <=, =, !=, IN, NOT IN, IS NULL, IS NOT NULL, LIKE, NOT LIKE。条件间默认逻辑为AND，嵌套数组表示OR
• from_date/to_date：查询时间范围
• granularity：时间分桶粒度（秒），用于time虚拟列分组（如3600表示按小时分组）
• groupby：分组字段列表，支持group_id（按问题分组）和time（按时间分桶分组）
• sample：采样参数，<1表示按比例采样（如0.5表示50%），>1表示最大采样行数（如1000表示最多1000行）

特殊功能

问题分组（Groups/Issues）

使用group_id虚拟列按问题分组。由于事件可能合并到不同问题，需通过issues参数传入问题ID与事件primary_hash的映射关系，Snuba会自动展开映射进行过滤/分组。

标签查询

支持两种标签查询方式：

1. 已知标签名查询：使用tags[name]格式，如tags[environment]，自动解析为对应标签值

   json
   "conditions": [
       ["tags[environment]", "=", "prod"],
       ["tags[custom_user_tag]", "IS NOT NULL"]
   ]
   

2. 动态标签键/值查询：使用tags_key（标签名）或tags_value（标签值）虚拟列，会展开所有标签（包括非预设标签），每行对应一个标签

   json
   // 查询值为"bar"的所有标签
   "conditions": [
       ["tags_value", "=", "bar"]
   ]
   

   注意：使用tags_key或tags_value时，计数对象是标签而非事件。例如10个事件各有10个标签，count()会返回100。