relay: Next iteration of refactoring (#2365)

Author: tonyo

src/docs/product/relay/getting-started.mdx

@@ -21,7 +21,7 @@ Releases](https://github.com/getsentry/relay/releases). A Docker image is provid
 
 To create the initial configuration, use Relay's `relay config init` command,
 which puts configuration files in the `.relay` folder under the current working
-directory. 
+directory.
 
 <Note>
 
@@ -33,6 +33,14 @@ container and copying in the files.
 </Note>
 
 ```shell {tabTitle:Run in Docker}
+# Adjust permissions for the configuration directory
+docker run --rm -it                \
+  -v $(pwd)/config/:/work/.relay/  \
+  --entrypoint bash                \
+  getsentry/relay                  \
+  -c 'chown -R relay:relay /work/.relay'
+
+# Generate the configuration
 docker run --rm -it                \
   -v $(pwd)/config/:/work/.relay/  \
   getsentry/relay                  \
@@ -66,7 +74,18 @@ _"create custom config"_ and customizing these parameters:
 Settings are recorded in `.relay/config.yml`. Note that all configuration values
 are optional and default to these settings:
 
-```yaml
+```yaml {tabTitle:Run in Docker}
+relay:
+  mode: managed
+  upstream: "https://sentry.io/"
+  host: 0.0.0.0
+  port: 3000
+  tls_port: ~
+  tls_identity_path: ~
+  tls_identity_password: ~
+```
+
+```yaml {tabTitle:Run Executable}
 relay:
   mode: managed
   upstream: "https://sentry.io/"
@@ -96,7 +115,7 @@ A typical credentials file is similar to this example:
 ```json
 {
   "secret_key": "5gkTAfwOrJ0lMy9aOAOmHKO1k6gd8ApYkAInmg5VfWk",
-  "public_key": "fQzvlvqLM2pJwLDwM_sXD2Lk5swzx-Oml4WhsOquon4",
+  "public_key": "nDJI79SbEYH9-8NEJAI7ezrgYfoIPW3Bnkg00k1z0fA",
   "id": "cde0d72e-0c4e-4550-a934-c1867d8a177c"
 }
 ```
@@ -144,10 +163,6 @@ This process registers Relay with Sentry so it is ready to send messages. See
 
 ## Running Relay
 
-You can either run the Relay binary directly or using a Docker image.
-
-### Running Relay Directly
-
 After registering Relay with Sentry, it is ready to run:
 
 ```shell {tabTitle:Run in Docker}
@@ -167,17 +182,19 @@ Under default configuration, Relay emits log output similar to:
 ```
  INFO  relay::setup > launching relay from config folder .relay
  INFO  relay::setup >   relay mode: managed
- INFO  relay::setup >   relay id: f2119bc9-9a9b-4531-826b-24e9794902f2
- INFO  relay::setup >   public key: QPBITKKtKUuEZGGbPke8iufEXAcVrEv6nmWrkRtc3l8
+ INFO  relay::setup >   relay id: cde0d72e-0c4e-4550-a934-c1867d8a177c
+ INFO  relay::setup >   public key: nDJI79SbEYH9-8NEJAI7ezrgYfoIPW3Bnkg00k1z0fA
  ...
  INFO  relay_server::actors::upstream > relay successfully registered with upstream
 ```
 
+Refer to the [Logging](/product/relay/monitoring/#logging) page for more information on how to configure Relay's logging.
+
 If you moved your config folder (for example, for security reasons), use the `--config` option to specify the location:
 
 ```shell {tabTitle:Run in Docker}
 docker run --rm -it                \
-  -v $(pwd)/config/:/work/.relay/  \
+  -v $(pwd)/config/:/etc/relay/    \
   -p 3000:3000                     \
   getsentry/relay                  \
   run --config /etc/relay/
@@ -187,66 +204,41 @@ docker run --rm -it                \
 ./relay run --config /etc/relay/
 ```
 
-## Logging
-
-Once Relay is running, you will receive `INFO` messages, such as:
-
-```
-INFO  relay::setup > launching relay from config folder .relay
-INFO  relay::setup >   relay mode: managed
-INFO  relay::setup >   relay id: f2119bc9-9a9b-4531-826b-24e9794902f2
-INFO  relay::setup >   log level: INFO
-```
-
-This example displays the default logging level, which you can modify so it displays either more or less information. For details about configuring logging please see [Logging](/product/relay/options/#logging) on the options page.
-
-## Health Checks
-
-Relay provides two URLs for checking system status:
-
-- `GET /api/relay/healthcheck/live/`: Tests if Relay is running and listening to
-  HTTP requests.
-- `GET /api/relay/healthcheck/ready/`: Tests if Relay is authenticated with the
-  upstream and operating normally.
-
-In case of success, both endpoints return a _200 OK_ response:
-
-```json
-{
-  "is_healthy": true
-}
-```
-
 ## Sending a Test Event
 
-Once Relay is running and authenticated with Sentry, send a test event.
+Once Relay is running and authenticated with Sentry, send a test event to one of the projects in your organization.
 
-Get the DSN of your project by navigating to _Project Settings > Client Keys
-(DSN)_, which looks similar to:
+Get the DSN of your project by navigating to your project settings at _Settings > Projects > {YOUR_PROJECT_NAME} > Client Keys (DSN)_, and select one of the existing DSNs, which looks similar to:
 
-```
-https://[email protected]/2244
-```
+`https://[email protected]/2345`
 
 Next, replace parts of the DSN to match the address at which Relay is reachable.
 For instance, if Relay listens at `http://localhost:3000`, change the protocol
 and host of the DSN to:
 
-```
-http://12345abcdb1e4c123490ecec89c1f199@localhost:3000/2244
-```
+<p>
+  <code>
+    <strong><i>http</i></strong>
+    ://12345abcdef10111213141516171819@
+    <strong><i>localhost:3000</i></strong>
+    /2345
+  </code>
+</p>
 
 Use the new DSN in your SDK configuration. To test this, you can send a message
-with `sentry-cli`:
+with `sentry-cli` ([installation instructions](/cli/installation/)):
 
 ```shell
-export SENTRY_DSN='http://12345abcdb1e4c123490ecec89c1f199@127.0.0.1:3000/2244'
+export SENTRY_DSN='http://12345abcdef10111213141516171819@127.0.0.1:3000/2345'
 sentry-cli send-event -m 'A test event'
 ```
 
 In a few seconds, the event should appear in the issues stream in your
 project.
 
-## Advanced Configuration
 
-<PageGrid />
+## Next Steps
+
+- **[Learn more about our Operating Guidelines](/product/relay/operating-guidelines/)**
+
+With a working Relay instance, you can both monitor and scale your Relay setup.

src/docs/product/relay/index.mdx

@@ -10,7 +10,7 @@ Sentry Relay offers enterprise-grade data security by providing a standalone ser
 
 Relay is specifically designed to:
 
-- Scrub personal information in a central place prior to sending it to Sentry, adding to the places Sentry already scrubs PII
+- Scrub personally identifiable information (PII) in a central place prior to sending it to Sentry
 - Improve event response time in regions with low bandwidth or limited connectivity
 - Act as an opaque proxy for organizations that restrict all HTTP communication to a custom domain name
 
@@ -63,6 +63,6 @@ Relay responds very quickly to requests. Installing Relay close to your infrastr
 
 By default, SDKs need to be configured with a Data Source Name (DSN) that points to `sentry.io`. If you need to restrict all HTTP communication to a custom domain name, Relay can act as an opaque proxy that reliably forwards events to Sentry.
 
-## Configuration
+## Next Steps
 
 <PageGrid />

src/docs/product/relay/metrics.mdx

@@ -0,0 +1,11 @@
+---
+title: Collected Metrics
+description: "Learn what metrics Relay produces."
+sidebar_order: 3
+redirect_from:
+  - /meta/relay/metrics/
+---
+
+Relay collects the following metrics:
+
+<RelayMetrics />

src/docs/product/relay/monitoring/collected-metrics.mdx

@@ -0,0 +1,71 @@
+---
+title: Monitoring
+description: "Configure logging, metrics, and error reporting for your Relay installation."
+sidebar_order: 3
+redirect_from:
+  - /meta/relay/logging/
+---
+## Logging
+
+Relay produces logs to the standard error stream (`stderr`), with `INFO` logging level by default.
+For example, after starting Relay you may see output such as this:
+
+```
+INFO  relay::setup > launching relay from config folder .relay
+INFO  relay::setup >   relay mode: managed
+INFO  relay::setup >   relay id: cde0d72e-0c4e-4550-a934-c1867d8a177c
+INFO  relay::setup >   log level: INFO
+```
+
+This example displays the messages with the default logging level (`INFO`), which you can modify so it displays either more or less information. For details about configuring logging please see the [Logging](/product/relay/options/#logging) section on the options page.
+
+## Error Reporting
+
+By default, Relay logs errors to the configured logger. You can enable error
+reporting to your project in Sentry in the Relay configuration file:
+
+```yaml
+sentry:
+  enabled: true
+  dsn: <your_dsn>
+```
+
+More information about available options and their meaning can be found [on the options page](/product/relay/options/#internal-error-reporting).
+
+## Health Checks
+
+Relay provides two URLs for checking system status:
+
+- `GET /api/relay/healthcheck/live/`: Tests if Relay is running and listening to
+  HTTP requests.
+- `GET /api/relay/healthcheck/ready/`: Tests if Relay is authenticated with the
+  upstream and operating normally.
+
+Both endpoints return a _200 OK_ response when successful:  
+
+```json
+{
+  "is_healthy": true
+}
+```
+
+## Metrics
+
+You can submit stats to a StatsD server by configuring the `metrics.statsd` key to an `ip:port` tuple.
+can be set to an `ip:port` tuple.
+
+### Example Configuration
+
+```yaml
+metrics:
+  # Endpoint of your StatsD server
+  statsd: 127.0.0.1:8126
+  # Prefix all metric names with this string
+  prefix: mycompany.relay
+```
+
+The options for configuring metrics reporting are documented on the [options page](/product/relay/options/#statsd-metrics).
+
+## Learn More
+
+<PageGrid />