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

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"
 

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"