[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>

1 files changed, 18 insertions, 18 deletions

diff --git a/docs/advanced/tracing.md b/docs/advanced/tracing.md
index 46b9c884a..318809587 100644
--- a/docs/advanced/tracing.md
+++ b/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.
 
-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.
+## Enabling tracing
 
-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.
+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.
 
-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:
+If necessary, you can do further configuration of tracing using the other environment variables listed [here](https://opentelemetry.io/docs/languages/sdk-configuration/general/).
 
-```yaml
-tracing-enabled: true
-tracing-transport: "grpc"
-tracing-endpoint: "localhost:4317"
-tracing-insecure-transport: true
-```
+## Ingesting traces
 
-[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
+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.
+
+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.
+
+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.
 
 ## 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