[docs] Update tracing.md with up-to-date way of doing things (#4452)

Updates tracing docs with the latest stufffff

Closes https://codeberg.org/superseriousbusiness/gotosocial/issues/4446

Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4452
Co-authored-by: tobi <tobi.smethurst@protonmail.com>
Co-committed-by: tobi <tobi.smethurst@protonmail.com>

docs/advanced/tracing.md

@@ -1,25 +1,20 @@
 # Tracing
 
-GoToSocial comes with [OpenTelemetry][otel] based tracing built-in. It's not wired through every function, but our HTTP handlers and database library will create spans. How to configure tracing is explained in the [Observability configuration reference][obs].
+GoToSocial comes with [OpenTelemetry][otel] based tracing built-in. It's not wired through every function, but our HTTP handlers and database library will create spans that may help you debug issues.
+
+## Enabling tracing
+
+To enable tracing on your instance, you must set `tracing-enabled` to `true` in your config.yaml file. Then, you must set the environment variable `OTEL_TRACES_EXPORTER` to your desired tracing format. A list of available options is available [here](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_exporter). Once you have changed your config and set the environment variable, restart your instance.
+
+If necessary, you can do further configuration of tracing using the other environment variables listed [here](https://opentelemetry.io/docs/languages/sdk-configuration/general/).
+
+## Ingesting traces
 
 In order to receive the traces, you need something to ingest them and then visualise them. There are many options available including self-hosted and commercial options.
 
-We provide an example of how to do this using [Grafana Tempo][tempo] to ingest the spans and [Grafana][grafana] to explore them. Please beware that the configuration we provide is not suitable for a production setup. It can be used safely for local development and can provide a good starting point for setting up your own tracing infrastructure.
+In [`example/tracing`][ext] we provide an example of how to do this using [Grafana Tempo][tempo] to ingest the spans and [Grafana][grafana] to explore them. You can use the files  with `docker-compose up -d` to get Tempo and Grafana running.
 
-You'll need the files in [`example/tracing`][ext]. Once you have those you can run `docker-compose up -d` to get Tempo and Grafana running. With both services running, you can add the following to your GoToSocial configuration and restart your instance:
+Please be aware that while the example configuration we provide can be used safely for local development and can provide a good starting point for setting up your own tracing infrastructure, it is not suitable for a so-called "production" setup.
-
-```yaml
-tracing-enabled: true
-tracing-transport: "grpc"
-tracing-endpoint: "localhost:4317"
-tracing-insecure-transport: true
-```
-
-[otel]: https://opentelemetry.io/
-[obs]: ../configuration/observability_and_metrics.md
-[tempo]: https://grafana.com/oss/tempo/
-[grafana]: https://grafana.com/oss/grafana/
-[ext]: https://codeberg.org/superseriousbusiness/gotosocial/tree/main/example/tracing
 
 ## Querying and visualising traces
 
@@ -27,18 +22,23 @@ Once you execute a few queries against your instance, you'll be able to find the
 
 Using TraceQL, a simple query to find all traces related to requests to `/api/v1/instance` would look like this:
 
-```
+```traceql
 {.http.route = "/api/v1/instance"}
 ```
 
 If you wanted to see all GoToSocial traces, you could instead run:
 
-```
+```traceql
 {.service.name = "GoToSocial"}
 ```
 
 Once you select a trace, a second panel will open up visualising the span. You can drill down from there, by clicking into every sub-span to see what it was doing.
 
-![Grafana showing a trace for the /api/v1/instance endpoint](../public/tracing.png)
+![Grafana showing a trace for the /api/v1/instance endpoint](../overrides/public/tracing.png)
 
 [traceql]: https://grafana.com/docs/tempo/latest/traceql/
+[otel]: https://opentelemetry.io/
+[obs]: ../configuration/observability_and_metrics.md
+[tempo]: https://grafana.com/oss/tempo/
+[grafana]: https://grafana.com/oss/grafana/
+[ext]: https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/example/tracing

docs/configuration/general.md

@@ -107,14 +107,16 @@ account-domain: ""
 # Default: "https"
 protocol: "https"
 
-# String. Address to bind the GoToSocial server to.
+# String. Address to bind the GoToSocial HTTP server to.
-# This can be an IPv4 address or an IPv6 address (surrounded in square brackets), or a hostname.
+# This can be an IPv4 address, an IPv6 address, or a hostname.
+#
 # The default value will bind to all interfaces, which makes the server
-# accessible by other machines. For most setups there is no need to change this.
+# accessible by other machines. For most setups you won't need to change this.
-# If you are using GoToSocial in a reverse proxy setup with the proxy running on
+# However, if you are using GoToSocial in a reverse proxy setup with the proxy
-# the same machine, you will want to set this to "localhost" or an equivalent,
+# running on the same machine, you may want to set this to "localhost" or equivalent,
-# so that the proxy can't be bypassed.
+# so that the proxy definitely can't be bypassed.
-# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "[::]", "[2001:db8::fed1]"]
+#
+# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "::1", "2001:db8::fed1"]
 # Default: "0.0.0.0"
 bind-address: "0.0.0.0"
 

example/config.yaml

@@ -117,14 +117,16 @@ account-domain: ""
 # Default: "https"
 protocol: "https"
 
-# String. Address to bind the GoToSocial server to.
+# String. Address to bind the GoToSocial HTTP server to.
-# This can be an IPv4 address or an IPv6 address (surrounded in square brackets), or a hostname.
+# This can be an IPv4 address, an IPv6 address, or a hostname.
+#
 # The default value will bind to all interfaces, which makes the server
-# accessible by other machines. For most setups there is no need to change this.
+# accessible by other machines. For most setups you won't need to change this.
-# If you are using GoToSocial in a reverse proxy setup with the proxy running on
+# However, if you are using GoToSocial in a reverse proxy setup with the proxy
-# the same machine, you will want to set this to "localhost" or an equivalent,
+# running on the same machine, you may want to set this to "localhost" or equivalent,
-# so that the proxy can't be bypassed.
+# so that the proxy definitely can't be bypassed.
-# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "[::]", "[2001:db8::fed1]"]
+#
+# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "::1", "2001:db8::fed1"]
 # Default: "0.0.0.0"
 bind-address: "0.0.0.0"