diff --git a/docs/advanced/tracing.md b/docs/advanced/tracing.md index 318809587..46b9c884a 100644 --- a/docs/advanced/tracing.md +++ b/docs/advanced/tracing.md @@ -1,20 +1,25 @@ # 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 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 +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]. 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. +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. -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. +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: + +```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 @@ -22,23 +27,18 @@ 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](../overrides/public/tracing.png) +![Grafana showing a trace for the /api/v1/instance endpoint](../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 diff --git a/docs/configuration/general.md b/docs/configuration/general.md index 7cd230baa..3443bed35 100644 --- a/docs/configuration/general.md +++ b/docs/configuration/general.md @@ -107,16 +107,14 @@ account-domain: "" # Default: "https" protocol: "https" -# String. Address to bind the GoToSocial HTTP server to. -# This can be an IPv4 address, an IPv6 address, or a hostname. -# +# String. Address to bind the GoToSocial server to. +# This can be an IPv4 address or an IPv6 address (surrounded in square brackets), or a hostname. # The default value will bind to all interfaces, which makes the server -# accessible by other machines. For most setups you won't need to change this. -# However, if you are using GoToSocial in a reverse proxy setup with the proxy -# running on the same machine, you may want to set this to "localhost" or equivalent, -# so that the proxy definitely can't be bypassed. -# -# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "::1", "2001:db8::fed1"] +# accessible by other machines. For most setups there is no need to change this. +# If you are using GoToSocial in a reverse proxy setup with the proxy running on +# the same machine, you will want to set this to "localhost" or an equivalent, +# so that the proxy can't be bypassed. +# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "[::]", "[2001:db8::fed1]"] # Default: "0.0.0.0" bind-address: "0.0.0.0" diff --git a/example/config.yaml b/example/config.yaml index 25bb09068..9eaa560fe 100644 --- a/example/config.yaml +++ b/example/config.yaml @@ -117,16 +117,14 @@ account-domain: "" # Default: "https" protocol: "https" -# String. Address to bind the GoToSocial HTTP server to. -# This can be an IPv4 address, an IPv6 address, or a hostname. -# +# String. Address to bind the GoToSocial server to. +# This can be an IPv4 address or an IPv6 address (surrounded in square brackets), or a hostname. # The default value will bind to all interfaces, which makes the server -# accessible by other machines. For most setups you won't need to change this. -# However, if you are using GoToSocial in a reverse proxy setup with the proxy -# running on the same machine, you may want to set this to "localhost" or equivalent, -# so that the proxy definitely can't be bypassed. -# -# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "::1", "2001:db8::fed1"] +# accessible by other machines. For most setups there is no need to change this. +# If you are using GoToSocial in a reverse proxy setup with the proxy running on +# the same machine, you will want to set this to "localhost" or an equivalent, +# so that the proxy can't be bypassed. +# Examples: ["0.0.0.0", "172.128.0.16", "localhost", "[::]", "[2001:db8::fed1]"] # Default: "0.0.0.0" bind-address: "0.0.0.0"