內容整理自官方開發文檔
系列
- 1 分鍾快速使用 Docker 上手最新版 Sentry-CLI - 創建版本
- 快速使用 Docker 上手 Sentry-CLI - 30 秒上手 Source Maps
- Sentry For React 完整接入詳解
- Sentry For Vue 完整接入詳解
- Sentry-CLI 使用詳解
- Sentry Web 性能監控 - Web Vitals
- Sentry Web 性能監控 - Metrics
- Sentry Web 性能監控 - Trends
- Sentry Web 前端監控 - 最佳實踐(官方教程)
- Sentry 后端監控 - 最佳實踐(官方教程)
- Sentry 監控 - Discover 大數據查詢分析引擎
- Sentry 監控 - Dashboards 數據可視化大屏
- Sentry 監控 - Environments 區分不同部署環境的事件數據
- Sentry 監控 - Security Policy 安全策略報告
- Sentry 監控 - Search 搜索查詢實戰
- Sentry 監控 - Alerts 告警
- Sentry 監控 - Distributed Tracing 分布式跟蹤
- Sentry 監控 - 面向全棧開發人員的分布式跟蹤 101 系列教程(一)
- Sentry 監控 - Snuba 數據中台架構簡介(Kafka+Clickhouse)
- Sentry 監控 - Snuba 數據中台架構(Data Model 簡介)
- Sentry 監控 - Snuba 數據中台架構(Query Processing 簡介)
- Sentry 官方 JavaScript SDK 簡介與調試指南
- Sentry 監控 - Snuba 數據中台架構(編寫和測試 Snuba 查詢)
- Sentry 監控 - Snuba 數據中台架構(SnQL 查詢語言簡介)
- Sentry 監控 - Snuba 數據中台本地開發環境配置實戰
自托管 Sentry
除了公開提供其源代碼外,Sentry
還提供並維護了一個最小的設置,可以為簡單的用例開箱即用。
該存儲庫還可以作為各種 Sentry
服務如何連接以進行完整設置的藍圖,這對於願意維護更大安裝的人很有用。
為簡單起見,我們為此選擇使用 Docker
和 Docker Compose
,
以及基於 bash
的安裝和升級腳本。
入門
我們的建議是下載自托管存儲庫的最新版本,
然后在此目錄中運行 ./install.sh
。
這個腳本會處理你開始需要的所有事情,包括一個 base-line
配置,
然后會告訴你運行 docker-compose up -d
來啟動 Sentry
。
Sentry
默認綁定到端口 9000
。
您應該能夠訪問 http://127.0.0.1:9000 上的登錄頁面。
配置
您很可能希望調整 Sentry
的默認配置。這些設施可用於此目的:
-
sentry/config.yml
— 包含大多數(如果不是全部)要調整的配置選項。這個文件是在安裝時從sentry/config.example.yml
生成的。該文件本身將最常見的配置選項記錄為代碼注釋。此文件中的一些常用設置包括:system.url-prefix
(我們會在安裝后立即提示您在歡迎屏幕上進行設置)mail.*
(雖然我們提供了一個基本的SMTP
服務器)GitHub
、Slack
等的集成。
-
sentry/sentry.conf.py
—包含更高級的配置。這個文件是在安裝過程中從sentry/sentry.conf.example.py
生成的。 -
環境變量—可用的
key
在.env
中定義。如果您需要覆蓋任何環境變量,請使用一些與系統相關的方法來設置環境變量。為避免Git
更改,只需創建一個名為.env.custom
的文件並在其中插入與系統相關的環境變量。為了使用它,請使用docker-compose --env-file /path/to/.env.custom up -d
。 -
Geolocation
使用自定義配置文件來符合底層技術。
注意:更改配置后,您需要通過運行
docker-compose restart web worker cron sentry-cleanup
(或僅docker-compose restart
重新啟動所有內容)來重新啟動所有 Sentry 服務。
配置特定主題
以下是與自托管相關的特定配置主題的更多信息:
自定義 CA 根
Email
地理位置
單點登錄 (SSO)
產品化
我們強烈建議在綁定到專用域或子域的 Sentry
設置前使用專用負載均衡器。
一個執行 SSL/TLS
終止的專用負載平衡器也將客戶端 IP
地址轉發為 Docker Compose
內部網絡
(因為這幾乎不可能以其他方式獲得)將為您提供最佳的 Sentry
體驗。
作為此設置的一部分,我們建議使用 HTTP
協議針對 /_health/
端點配置負載均衡器運行狀況檢查。
如果 Sentry
啟動,這將返回 200
或帶有問題列表的 500
。
請記住,所有這些設置都對所有服務使用單節點,包括 Kafka
。
對於更大的負載,您需要一台具有大量 RAM
和磁盤存儲空間的強大機器。
為了進一步擴展,您很可能會使用帶有更復雜工具(例如 Kubernetes
)的集群。
由於自托管安裝的自定義性質,我們不提供任何有關擴展的建議或指導。
自托管發布和升級
Sentry
減少了自托管的定期發布,以使其盡可能接近 sentry.io。
我們決定遵循使用 CalVer 版本控制方案的月度發布計划。
每個月的 15 號發布一個新版本,並在必要時進行后續發布。
您可以在我們自托管存儲庫的發布部分
找到最新版本。
為什么選擇 CalVer
?
- 簡而言之,這是為了讓自托管的
Sentry
與在 sentry.io 托管的實時版本接近。在我們宣布切換的博客文章中,有更多細節可供參考。 CalVer
針對持續部署進行了優化,而非長期穩定性。我們建議您定期升級,就像我們在 SaaS 環境中所做的那樣。
升級
我們鼓勵每個人定期更新他們的 Sentry
安裝以獲得最佳和最新的 Sentry
體驗。
要升級,您需要做的就是下載或檢查您想要的自托管存儲庫的版本,用該版本替換現有文件夾的內容,然后運行 ./install.sh
。
配置更新
我們可能有一些更新的配置,特別是對於新功能,因此請始終檢查 sentry 目錄下的示例配置文件,看看是否需要更新現有配置。我們盡最大努力自動化關鍵配置更新,但您應該始終在升級期間檢查您的配置。
在開始升級之前,我們關閉了所有服務,然后運行了一些數據遷移,因此預計會有一些停機時間。
有一個實驗性的 --minimize-downtime
選項可以減少升級期間的停機時間。
使用它的風險由您自己承擔,並查看它在其中實施的PR以獲取更多信息。
從早期版本升級時,您需要經歷一些困難。請閱讀下面的 難點
部分以獲取列表。
難點
我們有三個難點,您需要通過這些步驟才能獲取重大的數據庫更改:
- 如果您來自
9.1.2
之前的版本,則首先需要升級到9.1.2
並按照以下步驟操作:<your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> latest
- 如果您來自
9.1.2
,首先需要升級到21.5.0
並按照以下步驟操作:<your.sentry.version> -> 21.5.0 -> 21.6.3 -> latest
- 如果您來自
21.6.3
之前的版本,則首先需要升級到21.6.3
:<your.sentry.version> -> 21.6.3 -> latest
任何其他情況(21.6.3+
),你應該可以直接升級到最新版本。
每晚構建
我們為 Sentry 的每個新提交以及所有支持項目提供自托管存儲庫的 master 分支的每晚構建:
注意:這些構建通常是穩定的,但您可能偶爾會遇到損壞的版本,因為這些版本不能保證首先部署到 sentry.io。也不能保證您能夠干凈地升級到更高版本而不會丟失任何數據。使用每晚構建的風險自負。
自托管備份和恢復
快速備份
如果您需要一種快速備份和恢復 Sentry
實例的方法,並且不需要歷史事件數據,
則可以使用內置的 export
和 import
命令。
這些命令將保存和加載所有項目和用戶數據,但不包含任何事件數據。
備份
docker-compose run --rm -T -e SENTRY_LOG_LEVEL=CRITICAL web export > sentry/backup.json
注意:如果您省略了 -T
或 -e SENTRY_LOG_LEVEL=CRITICAL
部分,您的備份文件將混入日志行,您必須以某種方式將其刪除。
恢復
使用 export
命令備份后,恢復它的最簡單方法是將其放在主 self-hosted
存儲庫中的 sentry
目錄下,在配置文件旁邊。這個目錄會自動掛載到 /etc/sentry
,所以你可以運行以下命令來恢復你的備份:
docker-compose run --rm -T web import /etc/sentry/backup.json
如果您沒有看到任何錯誤並且進程以代碼 0
退出,那么恭喜您,您剛剛恢復了備份。
注意:我們強烈建議您在全新安裝(空數據庫但運行遷移)時在 相同版本的 Sentry 上恢復備份。否則,您很可能會遇到錯誤並可能損壞您的數據庫。
完整備份
備份和恢復 Sentry
的理想方法是備份
和恢復
它使用的所有 Docker
卷。所有保存關鍵長期數據的卷在安裝時都已定義為全局卷,並以 sentry-
為前綴:
sentry-data
sentry-postgres
sentry-redis
sentry-zookeeper
sentry-kafka
sentry-clickhouse
sentry-symbolicator
注意:只有備份和恢復這些卷才能恢復所有持久化數據。如果您還需要備份運行中的數據,我們建議備份 docker-compose
自動創建的任何特定於項目的卷,通常使用 sentry_self_hosted_sentry-
前綴。
Docker
在他們的文檔中記錄了如何備份和恢復卷。
只要可以毫無問題地讀回卷,您就可以使用不同的方法。
自托管的自定義 CA 根
從 Sentry 21.8.0
開始,如果您需要沒有來自公共信任 CA
根的 TLS
證書的 Sentry
訪問服務,現在可以輕松地將它們添加到容器中。
只需將證書添加到 Sentry
安裝根目錄內的 certificates
文件夾中,然后重新啟動容器。除了公共信任的 CA
根之外,還將使用您的自定義 CA
根。
注意:雖然您可以在每個容器中運行 update-ca-certificates
,但這將更新磁盤上系統的根包,但不會對內存中的任何副本執行任何操作。重新啟動容器將更新包並確保它被使用。
如果給定的證書有問題,容器的日志將在開始時具有 update-ca-certificates
的輸出。
具有捆綁根的依賴項
一些依賴項選擇捆綁自己的 CA
根並忽略系統 CA
根。
在已知的情況下,它們已被配置為使用系統根
。
如果某些東西似乎忽略了系統根
,請創建一個 issue,
以便對其進行跟蹤和修復。
覆蓋的捆綁根
- Python
requests
botocore
grpc
自托管 Email
注意:請記住,一旦更改設置,您就需要重新啟動所有 Sentry 服務。有關更多信息,請參閱配置部分。
出站 Email
自托管 Sentry
附帶一個由 exim4 提供支持的內置外發 SMTP server
。
默認配置設置為使用此服務器。您需要做的就是為 config.yml
中的 mail.from
設置設置一個有效地址,
並為 .env
中的 SENTRY_MAIL_HOST
設置 Sentry
實例的 FQDN。
請記住,如果您開始向公共地址發送過多電子郵件,您的新服務器可能會被標記為垃圾郵件發送者並被禁止。
如果您想使用外部 SMTP server
,您可以在 config.yml
文件中設置相關的 mail.*
設置並忽略內置的 SMTP server
。
有關每個設置的含義和作用的所有詳細信息,請參閱我們的電子郵件服務文檔
。
由於配置的分層方式,如果您通過 Web 界面更新 mail
設置,您還需要注釋掉 config.yml
中的 mail.host: 'smtp'
默認值,以便選擇所需的設置。
入站 Email
Sentry
通過 Mailgun 提供的入站 mail
支持非常有限。
您可以在我們的入站 email 服務文檔中找到有關如何進行設置的所有信息。
自托管地理定位
Sentry
可以使用 MaxMind 的免費 GeoLite2-City 數據庫來對 IP
地址進行地理定位,
為已知最終用戶 IP
地址的錯誤事件以及登錄 Sentry
安裝的用戶的會話歷史記錄提供額外的上下文。
為此,我們捆綁了 MaxMind
的 geoipupdate
工具。
為了利用服務器端 IP 地址地理定位,您必須首先將 IP 地址發送到 Sentry。
默認情況下,較新的 SDK 不會執行此操作。
要啟用服務器端 IP 地址地理定位,請注冊一個免費的 MaxMind 帳戶,
然后通過將您的 MaxMind
配置文件放在 geoip/GeoIP.conf
來告訴 Sentry
您的憑據。
AccountID 012345
LicenseKey foobarbazbuz
EditionIDs GeoLite2-City
有了這個配置文件,Sentry
的 install.sh
的后續運行將刷新 IP
地址地理定位數據庫。
下次您重新啟動自托管的 Sentry
實例(特別是 relay
和 web
服務)時,您應該會看到最新的數據。
以下是確認它是否正常工作的方法:
-
對於
relay
服務:Dashboards > Errors by Country 上應該有一些紫色。 -
對於
web
服務:User Settings > Security > Session History 應在表中的IP
地址下方顯示國家代碼和地區(例如,"US (CA)")。
啟動后不久看到 sentry_self_hosted_geoipupdate_1
容器退出是正常的,因為更新地理定位數據庫是一次性的批處理過程,而不是長時間運行的 job
。
升級
使用 GeoLite2-City.mmdb
文件的服務需要知道在哪里可以找到它。新安裝將自動設置此設置,但如果您要升級,則需要在重新啟動 Sentry
之前手動設置以下內容。
在 relay/config.yml
中(示例):
processing:
geoip_path: "/geoip/GeoLite2-City.mmdb"
在 sentry/sentry.conf.py
中(示例):
GEOIP_PATH_MMDB = '/geoip/GeoLite2-City.mmdb'
自托管單點登錄 (SSO)
Sentry
中的 SSO
以兩種方式之一處理:
- 通過處理上游代理的中間件來指示經過身份驗證的用戶
- 通過實現身份驗證管道的第三方服務
使用中間件代理 (SAML2)
從 Sentry 20.6.0
開始,自托管 Sentry
內置了對 SAML2
和某些身份驗證提供程序的支持。
對於舊版本,您需要在運行 ./install.sh
之前將以下行添加到 sentry/requirements.txt:
sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2
您可以設置它的方式與 sentry.io 相同,除了您需要為文檔中提到的 URL
使用自己實例的 url-prefix
。
有關所有詳細信息,請參閱我們的主要 SAML 文檔。
使用 OAuth 的單點登錄
注意:啟用 SSO
后,這將是登錄到自托管實例的唯一方法。如果您需要與 SSO
一起免費注冊,您可以在 GitHub PR 上對此發表評論。
Google Auth
從 Sentry 9.1 開始,自托管的 Sentry
帶有內置的 Google Auth
支持。
要啟用,您需要為您的 Google App 創建一個 client ID 和 secret,
然后將這些值分別輸入到您的 sentry/config.yaml
文件中:
auth-google.client-id: '<client id>'
auth-google.client-secret: '<client secret>'
注意:請記住,一旦更改設置,您就需要重新啟動所有 Sentry
服務。有關更多信息,請參閱配置部分。
- https://developers.google.com/identity/sign-in/web/server-side-flow#step_1_create_a_client_id_and_client_secret
- https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml
GitHub Auth
從 Sentry 10 開始,
自托管 Sentry
帶有內置的 GitHub Auth
支持。要啟用,您需要在您的組織下創建一個新的 GitHub App
並安裝它。
為 SSO & integration 創建 GitHub App
GitHub App
名稱不得包含任何空格。
如果上面的表單對您不起作用,您需要為您的 GitHub
應用程序進行以下設置:
Setting | Value |
---|---|
Homepage URL | ${urlPrefix} |
User authorization callback URL | ${urlPrefix}/auth/sso/ |
Setup URL (optional) | ${urlPrefix}/extensions/github/setup/ |
Webhook URL | ${urlPrefix}/extensions/github/webhook/ |
不要忘記將所有出現的 {'${urlPrefix}'}
替換為您自己的 url 前綴。
當提示輸入權限時,請選擇以下選項:
Permission | Setting |
---|---|
Organization permissions / members | Read-only |
User permissions / Email addresses | Read-only |
Repository administration | Read-only |
Repository contents | Read-only |
Issues | Read & write |
Pull requests | Read & write |
Repository webhooks | Read & write |
使用您的 GitHub App 信息更新您的配置
然后,您需要設置以下配置值:
GITHUB_APP_ID="<App ID>"
GITHUB_API_SECRET="<Client secret>"
GITHUB_REQUIRE_VERIFIED_EMAIL = True # Optional but recommended
# Only if you are using GitHub Enterprise
#GITHUB_BASE_DOMAIN = "git.example.com"
#GITHUB_API_DOMAIN = "api.git.example.com"
# github-app.id: <App ID>
# github-app.name: '<GitHub App name>'
# github-app.webhook-secret: '<Webhook secret>' # Use only if configured in GitHub
# github-app.client-id: '<Client ID>'
# github-app.client-secret: '<Client secret>'
# github-app.private-key: |
# -----BEGIN RSA PRIVATE KEY-----
# privatekeyprivatekeyprivatekeyprivatekey
# privatekeyprivatekeyprivatekeyprivatekey
# privatekeyprivatekeyprivatekeyprivatekey
# privatekeyprivatekeyprivatekeyprivatekey
# privatekeyprivatekeyprivatekeyprivatekey
# -----END RSA PRIVATE KEY-----
這還將為您的實例啟用 GitHub Integration
。
注意:請記住,一旦更改設置,您就需要重新啟動所有 Sentry 服務。有關更多信息,請參閱配置部分。
自定義 Provider
目前,API
被認為是不穩定的,可能會發生變化。事情可能不會有太大變化,但有一些地方需要清理。
考慮到這一點,如果您想構建自己的,請查看上面的參考實現之一。
自托管故障排除
請記住,自托管存儲庫面向中低負載,並考慮到了簡單性。
需要更大設置或有事件高峰的人們可以根據他們的特定需求和環境從這里擴展。
常見
您可以通過運行 docker-compose logs <service_name>
來查看每個服務的日志。
您可以使用 -f
標志來 "follow"
進入的日志,並使用 -t
標志作為時間戳。
如果您不傳遞任何服務名稱,您將獲得所有正在運行的服務的日志。
有關詳細信息,請參閱 logs 命令的參考。
Kafka
最有可能導致問題的事情之一是 Kafka
。最常報告的錯誤是
Exception: KafkaError{code=OFFSET_OUT_OF_RANGE,val=1,str="Broker: Offset out of range"}
這發生在 Kafka
和 consumer
不同步的地方。可能的原因有:
- 磁盤空間或內存不足
- 持續的事件峰值會導致很長的處理時間,導致
Kafka
在超過保留時間時丟棄消息 - 由於重新啟動或
suspend/resume(暫停/恢復)
循環導致的Date/time(日期/時間)
不同步問題
恢復
正確的解決方案
正確 的解決方案如下 (reported by @rmisyurev):
- 接收消費者列表:
docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --list
- 獲取群組信息:
docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers -describe
- 使用試運行(可選)觀察
offset
會發生什么:docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --dry-run
- 將
offset
設置為最新並執行:docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --execute
您可以在需要時將 snuba-consumers
替換為其他 consumer groups 或其他 topics 的 events
。
硬核選項
硬核選項 是刪除所有與 Kafka
相關的卷並重新創建它們,這將導致數據丟失。刪除這些卷后,任何掛起的數據都_將_消失。
-
停止實例:
docker-compose down --volumes
-
刪除 Kafka & Zookeeper 相關卷:
docker volume rm sentry-kafka docker volume rm sentry-zookeeper
-
再次運行安裝腳本:
./install.sh
-
啟動實例:
docker-compose up -d
減少磁盤使用
如果你想減少 Kafka
使用的磁盤空間,你需要仔細計算你攝取的數據量,你可以容忍的數據丟失量,
然后按照這個很棒的 StackOverflow 帖子或
我們社區論壇上的帖子中的建議進行操作。
- https://stackoverflow.com/a/52970982/90297
- https://forum.sentry.io/t/sentry-disk-cleanup-kafka/11337/2?u=byk
Redis
在自托管設置中,Redis
既用作事務數據存儲又用作 Celery
的工作隊列。
出於這個原因,它可能會在事件高峰期間不堪重負。
從版本 20.10.1
開始,我們對此進行了一些重大改進。
如果您仍然遇到問題,您可以考慮擴展 Redis
本身或切換到不同的 Celery broker
,例如 RabbitMQ。
Workers
如果您看到錯誤,例如
Background workers haven’t checked in recently. It seems that you have a backlog of 200 tasks. Either your workers aren’t running or you need more capacity.
您可能會從使用額外的專職工作人員中受益。
這是通過在 docker-compose.override.yml
中創建新的 worker
服務並使用 -Q queue_name
參數將它們綁定到特定隊列來實現的。 一個例子是:
worker1:
<< : *sentry_defaults
command: run worker -Q events.process_event
要查看更完整的示例,請參閱我們社區論壇上的示例解決方案。
Postgres
Postgres
用於主數據存儲,以及用於存儲 key/value
數據的 nodestore。
node_nodestore
表可以快速增長,尤其是在大量使用性能監控功能時,因為跟蹤數據存儲在該表中。
node_nodestore
表作為 cleanup
任務的一部分被清理,
但是 Postgres
可能沒有機會清理表(尤其是在重載情況下),所以即使行可能被刪除,它們仍然會占用磁盤空間。
您可以使用 pg-repack
,它通過創建一個新表並在刪除舊表之前復制數據來重新打包一個表。
您需要在清理腳本之后運行它,並注意它在創建表時,磁盤使用量會在回落之前激增。
下面是一個腳本示例:
# Only keep the last 7 days of nodestore data. We heavily use performance monitoring.
docker-compose run -T web cleanup --days 7 -m nodestore -l debug
# This ensures pg-repack exists before running as the container gets recreated on upgrades
docker-compose run -T postgres bash -c "apt update && apt install -y --no-install-recommends postgresql-9.6-repack && su postgres -c 'pg_repack -E info -t nodestore_node'"
其他
如果您仍然遇到問題,您可以隨時訪問我們的社區論壇以搜索現有主題或創建新主題並尋求幫助。
請記住,我們希望社區能夠幫助自己,並且 Sentry 員工也會在有時間時嘗試監控和回答論壇問題。
在報告問題或在論壇上提問時共享您的安裝日志、服務日志和 Sentry 版本將為您和試圖幫助您的人節省時間和精力。