使用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
安装
git clone
cd splat
bundle install
bin/rails db:prepare
bin/dev配置
邮件通知
在创建或重新打开问题时配置电子邮件通知的SMTP设置:
# 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电子邮件通知控件
# Enable email notifications in development
SPLAT_EMAIL_NOTIFICATIONS=true
# In production, emails are sent by default部署
Docker Compose
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:
: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记录器
配置
使用环境变量覆盖默认保留期:
# 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手动清理
要手动运行清理,请执行以下操作:
# 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日志中的清理活动:
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 用于监视服务状态和队列深度的端点。
健康端点
GET /_health答复:
{
"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:过去一小时的费率
阈值的环境变量:
# 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
- Discord 的中文翻译是“不和谐”或“纷争”。
- 网络钩子
- 或支持的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.生成身份验证令牌:
# Using OpenSSL
openssl rand -hex 32
# Or using Ruby
ruby -r securerandom -e 'puts SecureRandom.hex(32)'2.添加到您的环境中:
# .env
MCP_AUTH_TOKEN=your-generated-token-here3.配置克劳德桌面:
注: Claude Desktop目前仅支持 stdio 传输(不是HTTP)。要将Splat的MCP服务器与Claude Desktop一起使用,您需要创建一个代理脚本。
在以下位置创建文件 ~/splat-mcp-proxy.sh:
#!/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使其可执行:
chmod +x ~/splat-mcp-proxy.sh编辑 ~/Library/Application Support/Claude/claude_desktop_config.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传输。在您的工作区中,您可以直接连接:
{
"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: 1MCP(模型上下文协议)
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_PASSWORDOIDC身份验证设置
Splat支持OpenID Connect(OIDC)身份验证,并具有自动发现URL配置。这将用正确的用户身份验证替换基本的身份验证设置。
快速开始使用发现URL
首选方法是使用OIDC发现URL-只需设置3个环境变量:
# 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
提供商特定示例
谷歌
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八 :
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:
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=Auth0Microsoft Azure AD:
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,请单独配置端点:
# 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运作原理
- 发现:应用程序会自动从提供商的发现URL中获取OIDC配置
- 认证:用户将被重定向到您的OIDC提供商进行登录
- 令牌存储:JWT令牌经过加密并存储在仅支持HTTP的安全Cookie中
- 自动刷新:令牌在需要时自动刷新(到期前5分钟)
- 会话迁移:现有会话会自动迁移到加密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
