使用oauth
Splat-轻量级错误跟踪器
Splat是一个简单的错误跟踪服务,灵感来自GlitchTip。它为需要快速、可靠错误监控的应用程序提供了Sentry的轻量级替代方案。
默认情况下,此应用程序没有身份验证,但支持OIDC。
它有一个(很棒的)MCP端点。您需要设置一个环境变量 MCP_AUTH_TOKEN 为了使用它。终点是/mcp。
其中很大一部分是用GLM 4.6和Sonnet 4.5编写的。这在一定程度上是在大量写服务中广泛使用SQLite的经验。它在我的用例中表现得足够好。
我只在Rails中使用过Splat,但没有理由它不适用于其他系统。很乐意接受拉取请求以实现更广泛的兼容性。
如果您正在寻找其他Sentry克隆,请查看Glitchtip、Bugsink和Telebugs。
概述
以Ruby的splat操作符和令人满意的虫子挤压声命名,Splat通过一个简单的API端点接受Sentry-compatible错误事件和事务数据,异步处理它们,并在一个干净、快速的web界面中显示它们。
主要特点
- ✅ 哨兵协议兼容 -Sentry客户端SDK的插入式替换
- ✅ 单租户设计 -设置简单,无用户管理开销
- ✅ 快速摄入 -几秒钟内UI中出现错误
- ✅ 性能监控 -具有轻量级指标的交易数据
- ✅ 端点影响排名 -Surface控制器按总花费时间(平均值×计数)加上p95进行排名,因此您可以优化实际回报的地方
- ✅ N+1查询检测 -矿山
measurements.query_analysis从事务跨度分析器中,按N+1流行率对端点进行排名,公开专用工作列表和MCP工具 - ✅ 发布跟踪 -用首次/最后一次发布的版本标记问题,覆盖在问题火花线上部署标记,以便回归一目了然
- ✅ 跨度瀑布 -存储在DuckLake中的每笔交易跨度树(柱状、压缩),并在交易详细信息页面上呈现为分层时间线
- ✅ OLTP+OLAP存储 -SQLite用于摄取和OLTP,DuckLake(DuckDB+拼花)用于长期保留的分析
- ✅ MCP集成 -通过Claude和AI助手查询错误
- ✅ 最小依赖性 -Rails+SQLite+DuckDB+实体队列
- ✅ 自动清理 -可配置的数据保留期(默认90天)
为什么选择Splat?
当您需要错误跟踪时:
- 您的代码助手可以从以下位置获取问题和堆栈跟踪
- 在几秒钟内显示错误
- 一次就能理解和修改
- Rails 8/Ruby 3.4.6/SQLite(OLTP)+DuckLake(OLAP)+Solid堆栈(队列/缓存/电缆)
截图
1.项目仪表板
2.项目详细视图
3.问题清单
4.使用堆栈跟踪发布详细信息
5.活动详情
6.性能监控
入门指南
先决条件
- Ruby 3.4.6+
- 轨道8+
- SQLite3
安装```bash
git clone
cd splat
bundle install
bin/rails db:prepare
bin/dev
### 配置
#### 邮件通知
在创建或重新打开问题时配置电子邮件通知的SMTP设置:```bash
# Required settings
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USER_NAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
# Optional settings (with defaults shown)
SMTP_DOMAIN=localhost
SMTP_AUTHENTICATION=plain
SMTP_STARTTLS_AUTO=true
SPLAT_HOST=splat.example.com
SPLAT_INTERNAL_HOST=100.x.x.x:3030 # Your Tailscale IP maybe? Used for displaying alternate DSN
# For local development with self-signed certificates, use:
SMTP_OPENSSL_VERIFY_MODE=none
# Email recipients
SPLAT_ADMIN_EMAILS=admin@example.com,dev-team@example.com
SPLAT_EMAIL_FROM=noreply@splat.com
电子邮件通知控件```bash
Enable email notifications in development
SPLAT_EMAIL_NOTIFICATIONS=true
In production, emails are sent by default
## 部署
### Docker Compose```yaml
x-common-variables: &common-variables
RAILS_ENV: production
SECRET_KEY_BASE: ${SECRET_KEY_BASE}
SPLAT_HOST: ${SPLAT_HOST}
SPLAT_ADMIN_EMAILS: ${SPLAT_ADMIN_EMAILS}
SPLAT_EMAIL_FROM: ${SPLAT_EMAIL_FROM}
SMTP_ADDRESS: ${SMTP_ADDRESS}
SMTP_PORT: ${SMTP_PORT}
SMTP_USER_NAME: ${SMTP_USER_NAME}
SMTP_PASSWORD: ${SMTP_PASSWORD}
# MCP Authentication Token
MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
services:
splat:
image: reg.tbdb.info/splat:latest
environment:
<<: *common-variables
MISSION_CONTROL_USERNAME: ${MISSION_CONTROL_USERNAME}
MISSION_CONTROL_PASSWORD: ${MISSION_CONTROL_PASSWORD}
volumes:
- /storage/splat/storage:/rails/storage
- /storage/splat/logs/web:/rails/log
ports:
- "${HOST_IP}:3030:3000"
restart: unless-stopped
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "5"
jobs:
image: reg.tbdb.info/splat:latest
environment:
<<: *common-variables
SOLID_QUEUE_THREADS: 3
SOLID_QUEUE_PROCESSES: 1
volumes:
- /storage/splat/storage:/rails/storage
- /storage/splat/logs/jobs:/rails/log
command: bundle exec bin/jobs
restart: unless-stopped
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "3"
认证
- 无:任何人都可以访问splat-确保它在内部/VPN内运行
- 基本身份验证:使用您的Web服务器实现基本身份验证,避免保护/api/和/mcp/端点,因为它们已经过身份验证
- OIDC:设置
基本认证
假设Caddy服务器将流量转发到Splat。
以下配置使用基本身份验证,但允许自由访问 /api/ 和 /mcp/ 端点。```
splat.booko.info {
encode zstd gzip
Handle /api/ and /mcp/ routes without basic auth (both use token auth)
handle /api/ /mcp {
reverse_proxy * {
to http://:3030
}
}
Handle all other routes with basic auth
handle {
basicauth {
}
reverse_proxy * {
to http://:3030
}
}
log {
output file /var/log/caddy/splat.log
}
}
使用生成基本身份验证哈希 `docker compose exec -it caddy caddy hash-password`
### 开放式身份认证
Splat支持OIDC```
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_DISCOVERY_URL=
SPLAT_ALLOWED_USERS="Comma seperated list of email addresses allowed access Splat"
SPLAT_ALLOWED_DOMAINS="Comma seperated list of email domains allowed access Splat"
# Optional
OIDC_PROVIDER_NAME=
OIDC_REQUIRE_PKCE=
演出
Splat已经在处理真实世界流量的生产环境中进行了测试,并取得了出色的结果。
生产指标
持续负载:约1550笔交易/分钟(约26 tx/s)
- Web容器:1.07 GB RAM,约19%CPU
- 作业容器:340 MB RAM,约20%CPU
- 队列深度:0(无积压)
- 没有数据库锁或争用
总资源:约1.4 GB RAM,约0.8个CPU内核 对于两个容器的组合。
吞吐量:约220万笔/天
SQLite性能
以每秒26笔交易的速度持续 数据库中约95万笔交易(4.7GB):
- ✅ 没有SQLITE_BUSY错误
- ✅ 无写入冲突
- ✅ CPU随负载线性扩展
- ✅ 稳定的内存使用率(web容器的内存使用量稳定在1GB左右)
- ✅ 随着吞吐量的增加,内存保持稳定(测试为14-26 tx/s)
- ✅ 数据库大小对摄取性能没有影响(到目前为止)
Rails 8.1的SQLite优化(WAL模式、连接池)有效地处理了写繁重的工作负载。
存储架构:OLTP+OLAP
Splat将每个事件和交易存储在两个地方,每个地方都根据其擅长的地方进行选择:
- SQLite(OLTP) --摄取的真实来源、按id查找、状态更改和最近的firehose视图。快速、嵌入式、无运营开销。SQLite的保留可以是积极的(例如14-30天),而不会丢失分析历史。
- 鸭湖(OLAP) --每个事件/事务都被镜像写入本地磁盘或S3上由DuckDB管理的拼花地板存储。从DuckLake读取所有时间窗口聚合数据——端点统计数据、百分位数细分、响应时间图、“按影响划分的顶级端点”表,甚至项目仪表板的24小时计数。对于这些查询,拼花地板上的列扫描比行扫描快得多,保留时间可以独立设置,比SQLite长(例如,以低存储成本保存数月的历史)。
这两个存储区有单独的保留作业,因此您可以保留数周的OLTP详细信息和数月的OLAP历史记录,而不会使任何一个存储区膨胀。
端点影响排名
性能仪表板按以下方式对端点进行排名 花费的时间 (avg_duration × count)而不是平均持续时间。50毫秒的终点达到10000×/天比2秒的终点达到5×/天花费更多的总时间-按影响分类告诉您优化的实际回报。同一张表还将P95放在旁边,因此尾部较重的端点不会被较低的平均值所掩盖。
Span存储和SQL规范化
每笔交易的跨度树都存储在DuckLake(柱状拼花地板)中,并在交易详细信息页面上呈现为瀑布。跨度是交易量的10-100倍,但DuckLake的每列字典+RLE压缩——结合一次摄取时间——使存储易于管理:
- 摄取时的SQL规范化: span描述如下
SELECT * FROM users WHERE id = 42 AND email = 'alice@example.com'被重写为SELECT * FROM users WHERE id = ? AND email = ?之前 正在写入磁盘。参数化表单字典每行编码约2个字节,而不是500+。 - 隐私奖励: 因为文字永远不会到达磁盘,所以WHERE子句中的用户ID、电子邮件地址、INSERT中的名称和URL路径中的令牌都会自动编辑。我们可以给你看 模式 这是一个深思熟虑的权衡,也是一个有记录的承诺,而不是意外。
- 盖和保持: 每笔交易的跨度上限为1000(超出部分被丢弃,交易被标记),默认情况下保留30天(可与交易分开配置,因为跨度量要高得多)。
维护
数据保留和清理
Splat会自动清理旧数据以管理数据库大小并保持性能。
默认保留期
- 事件/问题:90天(可通过配置
SPLAT_MAX_EVENT_LIFE_DAYS) - 交易:90天(可通过配置
SPLAT_MAX_TRANSACTION_EVENT_LIFE_DAYS) - 文件:90天(可通过配置
SPLAT_MAX_FILE_LIFE_DAYS)
清理过程
- 日程:每天凌晨2:00 UTC通过Solid Queue定期作业
- 行动:
- 删除超过保留期的事件
- 删除超过保留期的交易
- 删除空问题(没有相关事件的问题)
- 将清理统计数据记录到Rails记录器
配置
使用环境变量覆盖默认保留期:```bash
Keep events for 30 days instead of 90
SPLAT_MAX_EVENT_LIFE_DAYS=30
Keep transactions for 60 days
SPLAT_MAX_TRANSACTION_EVENT_LIFE_DAYS=60
Keep files for 180 days
SPLAT_MAX_FILE_LIFE_DAYS=180
#### 手动清理
要手动运行清理,请执行以下操作:```bash
# Run cleanup with default settings
bin/rails runner "CleanupEventsJob.new.perform"
# Run cleanup with custom retention periods
SPLAT_MAX_EVENT_LIFE_DAYS=30 bin/rails runner "CleanupEventsJob.new.perform"
监控
检查Rails日志中的清理活动:```bash
tail -f log/production.log | grep "Cleanup"
日志输出示例:```
Started cleanup: events=90d, transactions=90d, files=90d
Deleted 1,234 old events
Deleted 567 old transactions
Deleted 89 empty issues
Cleanup completed successfully
监控
Splat提供了一个 /_health 用于监视服务状态和队列深度的端点。
健康端点```bash
GET /_health
答复:```json
{
"status": "ok",
"timestamp": "2025-10-23T12:34:56Z",
"queue_depth": 0,
"queue_status": "healthy",
"event_count": 1234,
"issue_count": 56,
"transaction_count": 5678,
"transactions_per_second": 1.23,
"transactions_per_minute": 73.5
}
响应字段:
status:整体系统健康状况(ok或degraded)queue_status:队列运行状况(healthy,warning,或critical)queue_depth:待处理的后台作业数量timestamp:当前服务器时间(ISO 8601)event_count:跟踪的错误事件总数issue_count:未决问题数量transaction_count:绩效交易总额transactions_per_second:最后一分钟的费率transactions_per_minute:过去一小时的费率
阈值的环境变量:```bash
Optional - defaults shown
QUEUE_WARNING_THRESHOLD=50 # queue_status becomes "warning"
QUEUE_CRITICAL_THRESHOLD=100 # queue_status becomes "critical", status becomes "degraded"
### 正常运行时间Kuma设置
**监视器配置:**
- **监视器类型**:HTTP-JSON查询
- **统一资源定位符**: `https://splat.yourdomain.com/_health`
- **预期状态代码**: 200
- **检查间隔**:60秒(或您的偏好)
**选项1:监视队列状态(推荐)**
- **JSON路径**: `$.queue_status`
- **期望值**: `healthy`
- **警报时间**:值不等于预期值
- **结果**:当队列处于“警告”或“危急”状态时发出警报
**选项2:监控整体状态**
- **JSON路径**: `$.status`
- **期望值**: `ok`
- **警报时间**:值不等于预期值
- **结果**:仅在系统“降级”时发出警报(临界队列深度)
**通知设置:**
配置Uptime Kuma以通过以下方式发送警报:
- 电子邮件
- Slack
- 网络钩子
- 或支持的90多种通知服务中的任何一种
**监测指南:**
- **正常队列深度**:0-10个作业(即时处理)
- **警告级别**:50-99个作业(排队)
- **临界水平**:100+个作业(队列积压)
**当queue_status为“警告”时:**
- 作业正在处理中,但速度低于摄入速度
- 检查Solid Queue工作程序状态
- 如果持续,考虑扩大员工规模
**当queue_status为“临界”时:**
- 大量积压,数据延迟
- 需要立即调查
- 检查工作人员崩溃或资源限制
## 备份
Splat使用SQLite数据库。推荐两种备份策略:
**文学流** -连续复制到S3兼容存储
- 实时备份,延迟约10-30秒
- 支持AWS S3、Backblaze B2、Cloudflare R2、MinIO
- 时间点恢复
**SQLite 3证书** -高效的增量备份
- 创建实时数据库的逐字节克隆
- 数据库使用时工作
- 增量传输比完整副本小
### 备份什么
- `storage/production.sqlite3` -事件、问题、交易(关键)
- `storage/production_queue.sqlite3` -后台工作(推荐)
- `storage/production_cache.sqlite3` -性能计数器(可选)
## 模型上下文协议(MCP)集成
Splat公开了一个MCP服务器,允许Claude和其他AI助手直接查询错误跟踪和性能数据。由于Splat没有身份验证系统,我们将使用环境设置值作为身份验证令牌。
### 设置
**1.生成身份验证令牌:**```bash
# Using OpenSSL
openssl rand -hex 32
# Or using Ruby
ruby -r securerandom -e 'puts SecureRandom.hex(32)'
2.添加到您的环境中:```bash
.env
MCP_AUTH_TOKEN=your-generated-token-here
**3.配置克劳德桌面:**
**注:** Claude Desktop目前仅支持 `stdio` 传输(不是HTTP)。要将Splat的MCP服务器与Claude Desktop一起使用,您需要创建一个代理脚本。
在以下位置创建文件 `~/splat-mcp-proxy.sh`:```bash
#!/bin/bash
# Proxy for Splat MCP over stdio -> HTTP
# Replace TOKEN with your actual MCP_AUTH_TOKEN
while IFS= read -r line; do
echo "$line" | curl -s -X POST http://localhost:3030/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-d @-
done
使其可执行:```bash
chmod +x ~/splat-mcp-proxy.sh
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"splat": {
"command": "/Users/YOUR_USERNAME/splat-mcp-proxy.sh",
"transport": {
"type": "stdio"
}
}
}
}
替代方案:使用Claude Code(支持HTTP):
您可以使用以下命令行:
`claude mcp添加--传输http协议http://localhost:3030/mcp--header“授权:在此处携带您生成的令牌”
Claude Code(VS Code扩展)支持HTTP传输。在您的工作区中,您可以直接连接:```json
{
"mcpServers": {
"splat": {
"url": "http://localhost:3030/mcp",
"transport": {
"type": "http",
"headers": {
"Authorization": "Bearer your-generated-token-here"
}
}
}
}
}
**4.重新启动克劳德桌面或VS代码**
### 可用的MCP工具
**问题管理:**
- `list_recent_issues` -按状态列出最近的问题
- `search_issues` -按关键字、异常类型或状态搜索
- `get_issue` -获取堆栈跟踪的详细问题
- `get_issue_events` -列出问题的事件发生情况
- `get_event` -获取完整的事件详细信息(请求ID、面包屑、上下文)
- `resolve_issue` / `ignore_issue` / `reopen_issue` -生命周期转换
**性能监控:**
- `get_transaction_stats` -总体百分位数加上按总时间排名的顶级终点(平均值×计数)
- `get_endpoint_summary` -具有最快/最慢样本请求的每个端点百分位数(总体+DB+视图)
- `get_endpoint_timeseries` -在一个时间范围内,一个端点的分组计数+p50/p95/p99——用于发现回归(“p95在14:00部署后跳了吗?”)
- `find_n_plus_one_endpoints` -按N+1流行率(受影响事务的百分比,每个请求的平均/最大查询数)对端点进行排名,以便您快速找到最严重的违规者
- `search_slow_transactions` -查找缓慢的个人请求
- `get_transactions_by_endpoint` -列出一个端点的最近事务
- `compare_endpoint_performance` -发布或时间戳前后的百分位数比较
- `get_transaction` -获取详细的交易明细
### 用法示例
配置后,您可以询问Claude:
- “在Splat中列出最近未解决的问题”
- “搜索生产中的NoMethodError问题”
- “booko应用程序在哪里消磨时间?”→ 影响排名靠前的端点
- “哪些端点有N+1查询问题?”→ 排名工作列表
- “显示过去7天内UsersController#Show的p95,每小时一次”
- “比较AlertsController#指数在v1.42.0版本前后的性能”
## 环境变量的完整列表```
RAILS_ENV: production
SECRET_KEY_BASE : generate with `openssl rand -hex 64`
HOST_IP: ip address to bind to
PORT: 3000
SPLAT_DOMAIN: https://splat.example.com # Change this to your domain
FROM_EMAIL: splat@splat.example.com # Change this to your email
SOLID_QUEUE_THREADS: 3
SOLID_QUEUE_PROCESSES: 1
MCP(模型上下文协议)```
MCP_AUTH_TOKEN: Generate with openssl rand -hex 32
### 数据保留```
SPLAT_MAX_EVENT_LIFE_DAYS=30
SPLAT_MAX_TRANSACTION_EVENT_LIFE_DAYS=60
SPLAT_MAX_FILE_LIFE_DAYS=180
任务控制```
Optionally set these if you'd like to access /jobs to view the SolidQueue management system
MISSION_CONTROL_USERNAME
MISSION_CONTROL_PASSWORD
## OIDC身份验证设置
Splat支持OpenID Connect(OIDC)身份验证,并具有自动发现URL配置。这将用正确的用户身份验证替换基本的身份验证设置。
### 快速开始使用发现URL
首选方法是使用OIDC发现URL-只需设置3个环境变量:```bash
# Required for OIDC authentication (app automatically adds .well-known path)
OIDC_DISCOVERY_URL=https://your-provider.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_PROVIDER_NAME=Your Provider Name # Optional: Display name for login button
重要:使用回调URL配置OIDC提供程序: https://your-splat-domain.com/auth/callback
提供商特定示例
谷歌```bash
OIDC_DISCOVERY_URL=https://accounts.google.com/.well-known/openid_configuration
OIDC_CLIENT_ID=your-google-client-id
OIDC_CLIENT_SECRET=your-google-client-secret
OIDC_PROVIDER_NAME=Google
**八 :**```bash
OIDC_DISCOVERY_URL=https://your-domain.okta.com/.well-known/openid_configuration
OIDC_CLIENT_ID=your-okta-client-id
OIDC_CLIENT_SECRET=your-okta-client-secret
OIDC_PROVIDER_NAME=Okta
身份验证0:```bash
OIDC_DISCOVERY_URL=https://your-domain.auth0.com/.well-known/openid_configuration
OIDC_CLIENT_ID=your-auth0-client-id
OIDC_CLIENT_SECRET=your-auth0-client-secret
OIDC_PROVIDER_NAME=Auth0
**Microsoft Azure AD:**```bash
OIDC_DISCOVERY_URL=https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid_configuration
OIDC_CLIENT_ID=your-azure-client-id
OIDC_CLIENT_SECRET=your-azure-client-secret
OIDC_PROVIDER_NAME=Microsoft
手动端点配置
如果您的提供商不支持发现URL,请单独配置端点:```bash
Required OIDC settings
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_AUTH_ENDPOINT=https://your-provider.com/oauth/authorize
OIDC_TOKEN_ENDPOINT=https://your-provider.com/oauth/token
OIDC_USERINFO_ENDPOINT=https://your-provider.com/oauth/userinfo
OIDC_JWKS_ENDPOINT=https://your-provider.com/.well-known/jwks.json
OIDC_PROVIDER_NAME=Your Provider
### 运作原理
1. **发现**:应用程序会自动从提供商的发现URL中获取OIDC配置
1. **认证**:用户将被重定向到您的OIDC提供商进行登录
1. **令牌存储**:JWT令牌经过加密并存储在仅支持HTTP的安全Cookie中
1. **自动刷新**:令牌在需要时自动刷新(到期前5分钟)
1. **会话迁移**:现有会话会自动迁移到加密Cookie
### 安全功能
- **加密Cookie**:JWT令牌使用Rails消息验证器进行加密
- **仅HTTP Cookie**:无法通过JavaScript访问令牌
- **SameSite=严格**:防止CSRF攻击
- **JWT验证**:可选令牌签名验证
- **自动清理**:注销或到期时清除的令牌
### 电子邮件发送设置```
https://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration
https://guides.rubyonrails.org/configuring.html#configuring-action-mailer
SMTP_ADDRESS - default 'localhost'
SMTP_PORT - default 587
SMTP_DOMAIN' - default 'localhost' Some providers require it match a verified domain.
SMTP_USER_NAME' - default nil
SMTP_PASSWORD' - default nil
SMTP_AUTHENTICATION' - default 'plain'
SMTP_STARTTLS_AUTO' - default 'true'
SMTP_OPENSSL_VERIFY_MODE - default'none').to_sym
发展
服务
- 实心队列:后台作业处理(
bin/jobs) - 固态缓存:内存缓存
- 实心电缆:实时更新(可选)
电子邮件预览
查看电子邮件模板 http://localhost:3000/rails/mailers
