add docs for traces (#206)

Co-authored-by: Rob Dominguez <[email protected]>
hasura · Nov 17, 2023 · cf55d1c · cf55d1c
1 parent 96d35bb
commit cf55d1c
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 0 deletions.
diff --git a/docs/observability/_category_.json b/docs/observability/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Observability",
+  "position": 9,
+  "customProps": {
+    "sidebar_pathname": "observability"
+  }
+}
diff --git a/docs/observability/overview.mdx b/docs/observability/overview.mdx
@@ -0,0 +1,68 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+description: Hasura offers observability tools that help you monitor and debug your GraphQL API.
+keywords:
+  - hasura
+  - graphql
+  - observability
+  - traces
+  - tracing
+  - metrics
+  - monitoring
+  - debugging
+  - errors
+  - performance
+  - opentelemetry
+  - otel
+hide_table_of_contents: true
+---
+
+import VersionedLink from "@site/src/components/VersionedLink";
+
+# Observability
+
+<div className="overview-header">
+  <div className="overview-text">
+    <p>
+      Out of the box, Hasura DDN comes with a set of tools that help you monitor and debug your GraphQL API. With
+      observability, you can check on the performance of your GraphQL API, debug errors, and get insights into your
+      GraphQL API usage.
+    </p>
+    <h4>Quick Links</h4>
+    <ul>
+      <li>
+        <VersionedLink to="/observability/traces/">Check out traces.</VersionedLink>
+      </li>
+    </ul>
+  </div>
+</div>
+
+<!--
+## Using Observability
+
+<div className="overview-gallery">
+  <VersionedLink to="/graphql-api/queries/filters/index/">
+    <div className="card">
+      <h3>Filter query results</h3>
+      <p>
+        Learn how to filter query results using <code>where</code> arguments.
+      </p>
+    </div>
+  </VersionedLink>
+  <VersionedLink to="/graphql-api/queries/sorting/">
+    <div className="card">
+      <h3>Sort query results</h3>
+      <p>
+        Learn how to sort query results using the <code>order_by</code> argument.
+      </p>
+    </div>
+  </VersionedLink>
+  <VersionedLink to="/graphql-api/queries/nested-queries/">
+    <div className="card">
+      <h3>Make nested queries across types</h3>
+      <p>Learn how to make complex nested queries across different types in your GraphQL API.</p>
+    </div>
+  </VersionedLink>
+</div>
+-->
diff --git a/docs/observability/traces.mdx b/docs/observability/traces.mdx
@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+sidebar_label: Traces
+description: Traces via OpenTelemetry allow you to track and map user requests across various services or components.
+keywords:
+  - hasura
+  - graphql
+  - observability
+  - traces
+  - tracing
+  - monitoring
+  - debugging
+  - errors
+  - performance
+  - opentelemetry
+  - otel
+seoFrontMatterUpdated: true
+---
+
+# Traces
+
+## Introduction
+
+[Distributed traces](https://opentelemetry.io/docs/concepts/signals/traces/) track and map journeys of user requests
+across various services or components.
+
+Traces are typically used to diagnose or debug which part of your application could potentially be responsible for a
+failure or error state and to monitor the performance of end-user interactions with your application.
+
+Traces are generated by instrumenting application code. Hasura DDN instruments all API queries with the OpenTelemetry
+format and supports tracing out of the box. **This means that you don't have to set up your own OpenTelemetry
+collector.** Simply head to the `Operations` dashboard for a project's Console and you'll see traces for all your API
+requests.
+
+## Spans
+
+Every request to your GraphQL API will have a unique `trace-id` associated with it and may have the following spans:
+
+- `/graphql`
+  - `handle_authentication`
+    - `execute_authentication`
+  - `handle_request`
+    - `execute_query`
+      - `execute`
+        - `execute_ndc_query`
+          - `Execute Query`
+        - `execute_ndc_mutation`
+
+| Span name                | Description                                                                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/graphql`               | The root span for every request to your GraphQL API.                                                                                                                                        |
+| `handle_authentication`  | The span responsible for handling authentication before the request is executed by the engine.                                                                                              |
+| `execute_authentication` | The span responsible for executing authentication, either using JWTs or via a Webhook.                                                                                                      |
+| `handle_request`         | The span responsible for handling a GraphQL request after it is successfully authenticated by the engine.                                                                                   |
+| `execute_query`          | The top-level span for executing a GraphQL query.                                                                                                                                           |
+| `execute`                | The span responsible for executing each query in your GraphQL request. This span has an attribute `usage_counts` which describes all the models that were used as a part of this operation. |
+| `execute_ndc_query`      | The span responsible for executing a single ndc query. This span has an attribute `field` which describes the schema type that was executed.                                                |
+| `Execute Query`          | The span responsible for executing the generated query on the data source.                                                                                                                  |
+| `execute_ndc_mutation`   | The span responsible for executing a single ndc mutation. This span has an attribute `field` which describes the field that was executed.                                                   |
+
+:::info What are spans?
+
+Spans represent the basic unit of work in a distributed system. They describe the operation that an individual component
+of the system is doing, such as the time taken to execute a function or a request.
+
+:::