feat: improve tracing documentation (#1630)

* feat(dt): add otel as a supported provider Signed-off-by: iverly <[email protected]> * feat(dt): make less hydra-specific Signed-off-by: iverly <[email protected]> * feat(dt): add more complex example Signed-off-by: iverly <[email protected]> --------- Signed-off-by: iverly <[email protected]>
ory · Jan 22, 2024 · 52d0435 · 52d0435
1 parent a8d15ef
commit 52d0435
Show file tree

Hide file tree

Showing 2 changed files with 33 additions and 4 deletions.
diff --git a/docs/self-hosted/_static/complex_trace.png b/docs/self-hosted/_static/complex_trace.png
diff --git a/docs/self-hosted/operations/01_tracing.md b/docs/self-hosted/operations/01_tracing.md
@@ -11,6 +11,7 @@ understanding your deployment of Ory better.
 
 You have the option to use a tracing backend or follow existing traces. Ory supports the following tracing backends:
 
+- [OpenTelemetry](https://github.com/open-telemetry)
 - [Jaeger](https://github.com/jaegertracing/jaeger)
 - [Elastic APM](https://github.com/elastic/apm)
 - [Datadog](https://github.com/DataDog)
@@ -49,9 +50,9 @@ missing/wrong, please [create an issue](https://github.com/ory/docs/issues).
 
 ### Local setup
 
-The [provided docker-compose file](https://github.com/ory/hydra/blob/master/quickstart-tracing.yml) in the project repository has
-tracing configuration which you can use to play around with - just uncomment the desired tracing provider. We will use Jaeger as
-an example.
+The [provided docker-compose file](https://github.com/ory/hydra/blob/master/quickstart-tracing.yml) in the Hydra repository (other
+ory services have the same docker-compose file) has tracing configuration which you can use to play around with - just uncomment
+the desired tracing provider. We will use Jaeger as an example.
 
 Simply run
 
@@ -82,9 +83,37 @@ To see spans around database interactions, you must be using a SQL backend, such
 
 :::
 
+There is a more complex example to show you the interactions between Kratos, Oathkeeper and Kratos to check if the user is allowed
+the access the requested resource :
+
+![Kratos Oathkeeper and Kratos exemplary trace in Jaeger UI](../_static/complex_trace.png)
+
+As previously said, you can see the interactions between the different services and SQL database interactions.
+
 ### Tracing configurations
 
-The CLI will provide you with the list of tracing configurations and their supported values. Simply run:
+You can configure tracing inside the configuration file (follow the same schema for all services) or via environment variables.
+
+There is an example of a configuration file with tracing enabled:
+
+```yaml
+tracing:
+  provider: jaeger # use any of the supported tracing providers
+  service_name: ory:kratos # if not set, the service name will be the service's name
+  providers:
+    jaeger: # per provider configuration
+      local_agent_address: jaeger:6831
+      sampling:
+        server_url: http://jaeger:5778/sampling
+```
+
+:::note
+
+Please refer to the configuration reference for the full list of options.
+
+:::
+
+The CLI will also provide you with the list of tracing configurations and their supported values. Simply run:
 
 ```
 docker exec -it hydra_hydra_1 hydra serve --help