diff options
| -rw-r--r-- | docs/advanced/tracing.md | 36 |
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. - + [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 |