docs_: sentry
This commit is contained in:
Igor Sirotin
parent
c9e2dc54bd
commit
99f9fdd045
|
|
@ -0,0 +1,110 @@
|
|||
# Description
|
||||
|
||||
This package encapsulates Sentry integration. So far:
|
||||
- only for status-go (including when running as part of desktop and mobile)
|
||||
- only for panics (no other error reporting)
|
||||
|
||||
Sentry is only enabled for users that **both**:
|
||||
1. Opted-in for metrics
|
||||
2. Use builds from our release CI
|
||||
|
||||
## 🛬 Where
|
||||
|
||||
We use self-hosted Sentry: https://sentry.infra.status.im/
|
||||
|
||||
## 🕐 When
|
||||
|
||||
### Which panics are reported:
|
||||
|
||||
- When running inside `status-desktop`/`status-mobile`:
|
||||
- during API calls in `/mobile/status.go`
|
||||
- inside all goroutines
|
||||
- When running `status-backend`:
|
||||
- any panic
|
||||
|
||||
### Which panics are NOT reported:
|
||||
|
||||
- When running inside `status-desktop`/`status-mobile`:
|
||||
- during API calls in `/services/**/api.go` \
|
||||
NOTE: These endpoints are executed through `go-ethereum`'s JSON-RPC server, which internally recovers all panics and doesn't provide any events or option to set an interceptor.
|
||||
The only way to catch these panics is to replace the JSON-RPC server implementation.
|
||||
- When running `status-go` unit tests:
|
||||
- any panic \
|
||||
NOTE: Go internally runs tests in a goroutine. The only way to catch these panics in tests is to manually `defer sentry.Recover()` in each test. This also requires a linter (similar to `lint-panics`) that checks this call is present. \
|
||||
This is not a priority right now, because:
|
||||
1. We have direct access to failed tests logs, which contain the panic stacktrace.
|
||||
2. Panics are not expected to happen. Test must be passing to be able to merge the code. So it's only possible with a flaky test.
|
||||
3. This would only apply to nightly/develop jobs, as we don't gather panic reports from PR-level jobs.
|
||||
|
||||
|
||||
## 📦 What
|
||||
|
||||
Full list can be found in `sentry.Event`.
|
||||
|
||||
Notes regarding identity-disclosing properties:
|
||||
- `ServerName` - completely removed from all events
|
||||
- `Stacktrace`:
|
||||
- No private user paths are exposed, as we only gather reports from CI-built binaries.
|
||||
- `TraceID` - so far will be unique for each event
|
||||
>Trace: A collection of spans representing the end-to-end journey of a request through your system that all share the same trace ID.
|
||||
|
||||
More details in [sentry docs](https://docs.sentry.io/product/explore/traces/#key-concepts).
|
||||
|
||||
# Configuration
|
||||
|
||||
There are 2 main tags to identify the error. The configuration is a bit complicated, but provides full information.
|
||||
|
||||
## Parameters
|
||||
|
||||
### `Environment`
|
||||
|
||||
| | |
|
||||
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Defining question | Where it is running? |
|
||||
| Set time | - `production` can only be set at build time to prevent users from hacking the environment<br>- All others can be set at runtime, because on CI we sometimes use same build for multiple environments |
|
||||
| Expected values | <table><thead><tr><th>Value</th><th>Description</th></tr></thead><tr><td>`production`</td><td>End user machine</td></tr><tr><td>~~`development`~~</td><td>Developer machine</td></tr><tr><td>~~`ci-pr`~~</td><td>PR-level CI runs</td></tr><tr><td>`ci-main`</td><td>CI runs for stable branch</td></tr><tr><td>`ci-nightly`</td><td>CI nightly jobs on stable branch</td></tr></table>`development` and `ci-pr` are dropped, because we only want to consider panics from stable code |
|
||||
|
||||
### `Context`
|
||||
|
||||
|
||||
| | |
|
||||
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Defining question | What is the executable for the library? |
|
||||
| Set time | Always at build-time |
|
||||
| Expected values | <table><thead><tr><th>Value</th><th>Running as...</th></tr></thead><tr><td>`status-desktop`</td><td>Library embedded into [status-desktop](https://github.com/status-im/status-desktop)</td></tr><tr><td>`status-mobile`</td><td>Library embedded into [status-mobile](https://github.com/status-im/status-mobile)</td></tr><tr><td>`status-backend`</td><td>Part of `cmd/status-backend`<br>Can be other `cmd/*` as well.</td></tr><tr><td>`matterbridge`</td><td>Part of [Status/Discord bridge app](https://github.com/status-im/matterbridge)</td></tr><tr><td>`status-go-tests`</td><td>Inside status-go tests</td></tr></table> |
|
||||
|
||||
|
||||
## Environment variables
|
||||
|
||||
To cover these requirements, I added these environment variables:
|
||||
|
||||
| Environment variable | Provide time | Description |
|
||||
|---------------------------------------------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `SENTRY_DSN` | - At build time with direct call to `sentry.Init`<br>- At runtime with `InitializeApplication` endpoint | [Sentry DSN](https://docs.sentry.io/concepts/key-terms/dsn-explainer/) to be used |
|
||||
| `SENTRY_CONTEXT_NAME`<br>`SENTRY_CONTEXT_VERSION` | Build time | Execution context of status-go |
|
||||
| `SENTRY_PRODUCTION` | Build time | When `true` or `1`:<br>-Defines if this is a production build<br>-Sets environment to `production`<br>-Has precedence over runtime `SENTRY_ENVIRONMENT` |
|
||||
| `SENTRY_ENVIRONMENT` | Run time | Sets the environment. Has no effect when `SENTRY_ENVIRONMENT` is set |
|
||||
|
||||
# Client integration
|
||||
|
||||
1. Set `SENTRY_CONTEXT_NAME` and `SENTRY_CONTEXT_VERSION` at status-go build time
|
||||
2. Provide `sentryDSN` to the `InitializeApplication` call.
|
||||
DSN must be kept private and will be provided by CI. Expect a `STATUS_GO_SENTRY_DSN` environment variable to be provided by CI.
|
||||
|
||||
<details>
|
||||
<summary>Why can't we consume `STATUS_GO_SENTRY_DSN` directly in status-go build?</summary>
|
||||
|
||||
In theory, we could. But this would require us to mix approaches of getting the env variable to the code.
|
||||
Right now we prefer `go:generate + go:embed` approach (e.g. https://github.com/status-im/status-go/pull/6014), but we can't do it in this case, because we must not write the DSN to a local file, which would be a bit vulnerable. And I don't want to go back to `-ldflags="-X github.com/status-im/status-go/internal/sentry.sentryDSN=$(STATUS_GO_SENTRY_DSN:v%=%)` approach.
|
||||
</details>
|
||||
|
||||
# Implementation details
|
||||
|
||||
- We recover from panics in here:
|
||||
https://github.com/status-im/status-go/blob/fcedb013166785e7def8710118086f4b650c33b1/common/utils.go#L102 https://github.com/status-im/status-go/blob/fcedb013166785e7def8710118086f4b650c33b1/mobile/callog/status_request_log.go#L69 https://github.com/status-im/status-go/blob/fcedb013166785e7def8710118086f4b650c33b1/cmd/status-backend/main.go#L40
|
||||
This covers all goroutines, because we have a linter to check that all goroutines have `defer common.LogOnPanic`.
|
||||
- Sentry is currently initialized in 2 places:
|
||||
- `InitializeApplication` - covers desktop/mobile clients
|
||||
https://github.com/status-im/status-go/blob/fcedb013166785e7def8710118086f4b650c33b1/mobile/status.go#L105-L108
|
||||
- in `status-backend` - covers functional tests:
|
||||
https://github.com/status-im/status-go/blob/fcedb013166785e7def8710118086f4b650c33b1/cmd/status-backend/main.go#L36-L39
|
||||
Loading…
Reference in New Issue