chore: explain what is tracing

redis · Nov 16, 2022 · 8aa8e75 · 8aa8e75
1 parent a0a3f42
commit 8aa8e75
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 2 deletions.
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -14,4 +14,3 @@ Examples
    examples/pipeline_examples
    examples/timeseries_examples
    examples/redis-stream-example.ipynb
-   examples/opentelemetry
diff --git a/docs/images/opentelemetry/distributed-tracing.png b/docs/images/opentelemetry/distributed-tracing.png
diff --git a/docs/images/opentelemetry/tree-of-spans.png b/docs/images/opentelemetry/tree-of-spans.png
diff --git a/docs/opentelemetry.rst b/docs/opentelemetry.rst
@@ -4,10 +4,29 @@ OpenTelemetry: Monitoring Performance
 What is OpenTelemetry?
 ----------------------
 
-`OpenTelemetry <https://opentelemetry.io>`_ is an open-source observability framework for `distributed traces <https://uptrace.dev/opentelemetry/distributed-tracing.html>`_, `metrics <https://uptrace.dev/opentelemetry/metrics.html>`_, and logs.
+`OpenTelemetry <https://opentelemetry.io>`_ is an open-source observability framework for `traces <https://uptrace.dev/opentelemetry/distributed-tracing.html>`_, `metrics <https://uptrace.dev/opentelemetry/metrics.html>`_, and logs.
 
 OpenTelemetry allows developers to collect and export telemetry data in a vendor agnostic way. With OpenTelemetry, you can instrument your application once and then add or change vendors without changing the instrumentation, for example, here is a list of `popular DataDog alternatives <https://uptrace.dev/get/compare/datadog-competitors.html>`_ that support OpenTelemetry.
 
+What is tracing?
+----------------
+
+`Distributed tracing <https://uptrace.dev/opentelemetry/distributed-tracing.html>`_ allows you to see how a request progresses through different services and systems, timings of each operation, any logs and errors as they occur.
+
+In a distributed environment, tracing also helps you understand relationships and interactions between microservices. Distributed tracing gives an insight into how a particular microservice is performing and how that service affects other microservices.
+
+.. image:: images/opentelemetry/distributed-tracing.png
+  :alt: Trace
+
+Using tracing, you can break down requests into `spans <https://uptrace.dev/opentelemetry/distributed-tracing.html#spans>`_. **Span** is an operation (unit of work) your app performs handling a request, for example, a database query or a network call.
+
+**Trace** is a tree of spans that shows the path that a request makes through an app. Root span is the first span in a trace.
+
+.. image:: images/opentelemetry/tree-of-spans.png
+  :alt: Trace
+
+To learn more about tracing, see `Distributed Tracing using OpenTelemetry <https://uptrace.dev/opentelemetry/distributed-tracing.html>`_.
+
 OpenTelemetry instrumentation
 -----------------------------
 
@@ -144,3 +163,15 @@ You can also create queries with more complex expressions. For example, the foll
          projects: [1]
 
 See `Alerting and Notifications <https://uptrace.dev/get/alerting.html>`_ for details.
+
+What's next?
+------------
+
+Next, you can learn how to configure `uptrace-python <https://uptrace.dev/get/uptrace-python.html>`_ to export spans, metrics, and logs to Uptrace.
+
+You may also be interested in the following guides:
+
+- `OpenTelemetry Django <https://uptrace.dev/opentelemetry/instrumentations/python-django.html>`_
+- `OpenTelemetry Flask <https://uptrace.dev/opentelemetry/instrumentations/python-flask.html>`_
+- `OpenTelemetry FastAPI <https://uptrace.dev/opentelemetry/instrumentations/python-sqlalchemy.html>`_
+- `OpenTelemetry instrumentations <http://localhost:8081/opentelemetry/instrumentations/>`_