Skip to content
This repository has been archived by the owner on Aug 14, 2024. It is now read-only.

fix(environment): restructure subheadings and clarify ingest setup #1330

Merged
merged 8 commits into from
Jul 9, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
restructure docs and clarify ingest setup
  • Loading branch information
mifu67 committed Jul 9, 2024
commit 0799ad70218644a595c9b9a1566eb645e9a273f8
119 changes: 57 additions & 62 deletions src/docs/environment/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,55 @@ You can create other users with `sentry createuser`.
displayed correctly.
</Alert>

### Frontend Only & Backend Only

Please refer to [Frontend Development Server](/frontend/development-server/) and [Backend Development Server](/backend/development-server/) for alternative ways to bring up the Sentry UI.

### Enabling HTTPS

You may wish to run the development server in HTTPS mode. This can be done by generating and installing local certificates.

We will be using [mkcert](https://github.com/FiloSottile/mkcert) to create and install a locally-trusted, development certificate. The following will install `mkcert` and then create and install the local certificates.

```shell
brew install mkcert
brew install nss # if you use Firefox
yarn mkcert-localhost
```

Running `sentry devserver` will automatically use HTTPS when the certificates have been installed.


### Ingestion Pipeline (Relay)

Some services are not run in all situations. Among those are <Link to="/services/relay/">Relay</Link> and the ingest workers.

<b>If you need to ingest errors, but don't require metrics ingestion: </b> Set `SENTRY_USE_RELAY=True` in `~/.sentry/sentry.conf.py`. If `sentry devservices` is currently up, make sure to restart it after you make the change. This will launch Relay as part of the `devserver` workflow.

Additionally, you can explicitly control this during `devserver` usage with the `--ingest` and `--no-ingest` flags. The `sentry devservices` command will not update Relay automatically in that case, to do this manually run:

```shell
sentry devservices up --skip-only-if relay
sentry devserver --workers --ingest
```

<b>If you want to enable the entire metrics ingestion pipeline:</b> You need to add the following to your config at `~/.sentry/sentry.conf.py`:

```python
SENTRY_USE_RELAY = True
SENTRY_USE_METRICS_DEV = True
SENTRY_EVENTSTREAM = "sentry.eventstream.kafka.KafkaEventStream"
SENTRY_FEATURES['organizations:metrics-extraction'] = True # Enables session metrics
SENTRY_FEATURES['organizations:transaction-metrics-extraction'] = True # Enables transaction metrics
```

After enabling `KafkaEventStream` the `snuba` service has to be reset to pick up the new configuration:

```shell
sentry devservices rm snuba
sentry devservices up snuba
```

## Running siloed instances

By default `sentry devserver` will run a monolith mode application server. You can also run ``devserver`` with siloed application instances. Before you do, you need to <Link to="/database-migrations/#cloning-a-monolith-database">create split silo databases</Link>.
Expand All @@ -72,24 +121,20 @@ In the above setup your local environment will use org slug domains, and send re

### Ngrok and siloed servers

To combine ngrok and local development servers you’ll need to reserve multiple domains in ngrok, and create a configuration file for ngrok:
To combine ngrok and local development servers you’ll need to reserve two domains in ngrok, and create a configuration file for ngrok:

```yaml
version: '2'
authtoken: <YOUR-NGROK-AUTHTOKEN>
tunnels:
acme-org:
proto: http
hostname: acme.<yourname>.ngrok.dev
addr: 8000
control-silo:
proto: http
hostname: <yourname>.ngrok.dev
hostname: $yourname.ngrok.dev
host_header: 'rewrite'
addr: 8000
region-silo:
proto: http
hostname: us.<yourname>.ngrok.dev
hostname: us.$yourname.ngrok.dev
addr: 8010
host_header: 'rewrite'
```
Expand All @@ -98,16 +143,16 @@ Then run all the required servers

```shell
# Run a control silo with ngrok
sentry devserver --silo=control --ngrok <yourname>.ngrok.dev
sentry devserver --silo=control --ngrok $yourname.ngrok.dev

# Run a region silo without ngrok
sentry devserver --silo=region --ngrok <yourname>.ngrok.dev
sentry devserver --silo=region --ngrok $yourname.ngrok.dev

# Run ngrok
ngrok start --all --config regions.yml
```

This setup will result in both the region and control servers responding to different domains. The multi-region setup with ngrok also enables customer-domains and you'll need ngrok domains for each organization you plan on using. In this configuration, CORS will work similar to production. For ngrok setup with non-siloed development server see <Link to="/backend/development-server/">developement server</Link>.
This setup will result in both the region and control servers responding to different domains, and CORS will work similar to production.

### Siloed Django Shell

Expand Down Expand Up @@ -152,60 +197,10 @@ environment, you can create `getsentry/conf/settings/devlocal.py` and put the
configuration option overrides there. This module will be automatically imported
by `dev.py` if it exists.


### Frontend Only & Backend Only

Please refer to [Frontend Development Server](/frontend/development-server/) and [Backend Development Server](/backend/development-server/) for alternative ways to bring up the Sentry UI.

### Enabling HTTPS

You may wish to run the development server in HTTPS mode. This can be done by generating and installing local certificates.

We will be using [mkcert](https://github.com/FiloSottile/mkcert) to create and install a locally-trusted, development certificate. The following will install `mkcert` and then create and install the local certificates.

```shell
brew install mkcert
brew install nss # if you use Firefox
yarn mkcert-localhost
```

Running `sentry devserver` will automatically use HTTPS when the certificates have been installed.


### Ingestion Pipeline (Relay)

Some services are not run in all situations. Among those are <Link to="/services/relay/">Relay</Link> and the ingest workers. If you need
a more production-like environment in development, you can set `SENTRY_USE_RELAY=True` in `~/.sentry/sentry.conf.py`. If `sentry devservices` is currently up ,make sure to restart it after you make the change. This will launch Relay
as part of the `devserver` workflow.

Additionally, you can explicitly control this during `devserver` usage with the `--ingest` and `--no-ingest` flags. The `sentry devservices`
command will not update Relay automatically in that case, to do this manually run:

```shell
sentry devservices up --skip-only-if relay
sentry devserver --workers --ingest
To enable the ingest workers, follow the steps described <Link to="###Ingestion Pipeline (Relay)">here</Link> and run ```shell
getsentry devserver --workers --ingest
```

If you want to enable the entire metrics ingestion pipeline, you need to add the following to your config at `~/.sentry/sentry.conf.py`:

```python
SENTRY_USE_RELAY = True
SENTRY_USE_METRICS_DEV = True
SENTRY_EVENTSTREAM = "sentry.eventstream.kafka.KafkaEventStream"
SENTRY_FEATURES['organizations:metrics-extraction'] = True # Enables session metrics
SENTRY_FEATURES['organizations:transaction-metrics-extraction'] = True # Enables transaction metrics
```

After enabling `KafkaEventStream` the `snuba` service has to be reset to pick up the new configuration:

```shell
sentry devservices rm snuba
sentry devservices up snuba
```


## Troubleshooting

You might also be interested in <Link to="/continuous-integration/#troubleshooting-ci">troubleshooting CI</Link>.

---
Expand Down