Docs: update o11y section (#884)

docs/graphql-api/errors.mdx

@@ -80,7 +80,7 @@ However as a Hasura supergraph author, you have access to details of most intern
 - [Data connector](/data-sources/overview.mdx) interactions:
   - These are useful in debugging connection or interface errors with your data connectors.
 
-The details are available through [traces](/observability/traces.mdx). It is recommended to review all error spans
+The details are available through [traces](/observability/built-in/traces). It is recommended to review all error spans
 within the trace to obtain details of the internal error.
 
 If the trace still does not reveal the details of the error, it may originate from Hasura internals. In such cases,

docs/observability/built-in/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Built-in features",
+  "position": 2
+}

docs/observability/explain/_category_.json → docs/observability/built-in/explain/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Query Plan",
-  "position": 2
+  "position": 4
 }

docs/observability/explain/api-reference.mdx → docs/observability/built-in/explain/api-reference.mdx

@@ -33,11 +33,11 @@ All requests are `POST` requests to the `/v1/explain` endpoint.
 
 ### Request
 
-The request expects the exact same payload as the GraphQL API (including authentication related headers).
+The request expects the exact same payload as the GraphQL API (including authentication-related headers).
 
-- `query`: the GraphQL query to be analyzed
-- `variables` (optional): the variables used in the GraphQL query
-- `operationName` (optional): the name of the GraphQL operation
+- `query`: the GraphQL query to be analyzed.
+- `variables` (optional): the variables used in the GraphQL query.
+- `operationName` (optional): the name of the GraphQL operation.
 
 ```http
 POST /v1/explain HTTP/1.1
@@ -69,7 +69,7 @@ Content-Type: application/json
 
 ### Response
 
-The response for a query is the engine' plans for executing the GraphQL query:
+The response for a query is the engine's plans for executing the GraphQL query:
 
 ```none
 {
@@ -184,7 +184,7 @@ A Parallel represents a parallel execution of steps. It has the following struct
 
 #### NDCExplain
 
-The `NDCExplain` contains the explanation of the query execution from the DataConnector point of view. It has the
+The `NDCExplain` contains the explanation of the query execution from the DataConnector's point of view. It has the
 following structure:
 
 ```none
@@ -196,9 +196,9 @@ following structure:
 
 The `NDCExplain` can be of the following types:
 
-1. `response`: The data-connector supports explaining query and has given a valid response.
-2. `error`: The data-connector has raised some error while explaining the query.
-3. `notSupported`: The data-connector doesn't support explaining ndc queries.
+1. `response`: The data connector supports explaining query and has given a valid response.
+2. `error`: The data connector has raised some error while explaining the query.
+3. `notSupported`: The data connector doesn't support explaining NDC queries.
 
 ## Example
 

docs/observability/explain/index.mdx → docs/observability/built-in/explain/index.mdx

@@ -29,7 +29,7 @@ import Thumbnail from "@site/src/components/Thumbnail";
 
 # Hasura Query Plan
 
-The Hasura v3 engine can output the GraphQL execution plan for a given query via the "explain" API.
+The Hasura DDN engine can output the GraphQL execution plan for a given query via the "explain" API.
 
 The execution plan output is represented as a tree of type [ExplainStep](#explainstep). You can also visualize the query
 plan, SQL plan, and SQL query used for each execution by clicking the `Explain query` button in your GraphiQL's request
@@ -180,7 +180,7 @@ query MyQuery {
 
 <Thumbnail src="/img/o11y/v0.1.1_console_explain-plan.png" alt="Explain plan example" width="700px" />
 
-Now, from [the explain plan](/observability/explain/api-reference#example), we can understand that:
+Now, from [the explain plan](/observability/built-in/explain/api-reference#example), we can understand that:
 
 - There are three sequential steps:
   - Make a selection on the `users` model

docs/observability/built-in/index.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+description: ""
+keywords:
+  - hasura ddn
+  - api observability
+  - metrics
+  - traces
+  - logs
+  - tools
+---
+
+# Built-in Features

docs/observability/metrics.mdx → docs/observability/built-in/metrics.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 2
 sidebar_label: Metrics
 description:
   "Learn how to leverage metrics to track user requests across various services in the Hasura Data Delivery Network.
@@ -27,9 +27,9 @@ import Thumbnail from "@site/src/components/Thumbnail";
 
 ## Introduction
 
-Hasura Data Delivery Network comes with a set of metrics that help you monitor and debug performance of your GraphQL
-API. Simply head to the `Performance` tab from `Insights` panel for a project's Console, and you'll see performance metrics
-for all your API requests.
+Hasura DDN ships with a set of metrics that help you monitor and debug performance of your GraphQL API. Simply head to
+the `Performance` tab from `Insights` panel for a project's console, and you'll see performance metrics for all your API
+requests.
 
 From the performance page, metrics can be viewed for either an entire project or a single build.
 

docs/observability/model-analytics/_category_.json → docs/observability/built-in/model-analytics/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Analytics",
-  "position": 5
+  "position": 3
 }

docs/observability/model-analytics/field.mdx → docs/observability/built-in/model-analytics/field.mdx

@@ -35,7 +35,7 @@ By tracking the frequency and context of field queries, you can make informed de
 optimization, and data governance.
 
 Field analytics can be accessed via the `Analytics` tab within the `Explorer` panel for any specific model or command,
-allowing users to view data for either the project API or of a particular build.
+allowing you to view data for either the project API or of a particular build.
 
 <Thumbnail src="/img/model-analytics/field-analytics.png" alt="Field Analytics" width="1000px" />
 
@@ -52,8 +52,8 @@ allowing users to view data for either the project API or of a particular build.
   and enhance the overall performance of their APIs.
 
 Field analytics provides API producers with the detailed insights necessary to manage and optimize their API offerings
-effectively. By leveraging these insights, organizations can make informed decisions that enhance API performance,
-ensure compliance, and deliver better value to their users.
+effectively. By leveraging these insights, you can make informed decisions that enhance API performance, ensure
+compliance, and deliver better value to your users.
 
 ## Field Summary
 
@@ -66,9 +66,7 @@ architecture.
 
 ### Access Mode
 
-The Access Mode provides a breakdown of the different ways in which fields are accessed within your API. This provides a
-very unique insight into the kind of access of your fields: `direct queries`, usage `via relationships`, and usage
-`as arguments`.
+The Access Mode provides a breakdown of the different ways in which fields are accessed within your API.
 
 ```graphql
 query ProductHomePage {
@@ -132,17 +130,15 @@ requests made.
 ### Table columns
 
 - **Field Name:** The name of the field within the model.
-- **Access Mode:** The mode in which the field is accessed, such as direct queries, usage via relationships, or usage as
-  arguments.
+- **Access Mode:** The mode in which the field is accessed.
 - **Number of Requests:** The total number of requests made for this field.
 
 ### Field details
 
 Clicking on the field name in the table opens a sidebar modal that provides in-depth details about the selected field.
 The Field Detail section provides a comprehensive analysis of a specific field within a model. This section is designed
 to offer in-depth insights into field usage, including request patterns, the operations accessing the field, and the
-context of these accesses. Such detailed visibility aids in understanding the behavior and importance of individual
-fields in your API.
+context of these accesses.
 
 <Thumbnail src="/img/model-analytics/field-detail.png" alt="Field Analytics" width="1000px" />
 

docs/observability/model-analytics/index.mdx → docs/observability/built-in/model-analytics/index.mdx

@@ -26,11 +26,12 @@ meets the needs of your users effectively.
 
 :::info Feature Availability
 
-This feature is available from DDN Base Plan onwards with the retention period of 1 month.
+This feature is available from [DDN Base Plan](https://hasura.io/pricing) onwards with the retention period of one
+month.
 
 :::
 
 ## Next steps
 
-- Check out [operation-level analytics](/observability/model-analytics/operation.mdx).
-- Check out [field-level analytics](/observability/model-analytics/field.mdx).
+- Check out [operation-level analytics](/observability/built-in/model-analytics/operation.mdx).
+- Check out [field-level analytics](/observability/built-in/model-analytics/field.mdx).

docs/observability/model-analytics/operation.mdx → docs/observability/built-in/model-analytics/operation.mdx

@@ -37,16 +37,15 @@ command, allowing users to view data for either the project API or of a particul
 ## Model Requests
 
 The Model Requests section provides a visual representation of the number of requests per day made on a particular
-model. Such insights help in pinpointing peak, and low usage periods and understanding how the model's usage varies over
-time.
+model. Such insights help in pinpointing peak and low usage periods and in understanding how the model's usage varies
+over time.
 
 <Thumbnail src="/img/model-analytics/model-request-graph.png" alt="Operation Analytics" width="1000px" />
 
 ## Operation Summary
 
 The Operation Summary section provides an overview of the operations with the highest and lowest request counts. This
-information is crucial for understanding which queries or mutations are most frequently or least frequently access the
-model.
+information is crucial for understanding which queries or mutations most or least frequently access a model.
 
 <Thumbnail src="/img/model-analytics/operation-summary.png" alt="Operation Analytics" width="1000px" />
 

docs/observability/platform-dashboard.mdx → docs/observability/built-in/platform-dashboard.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 5
 sidebar_label: Platform Dashboard
 description:
   "The Platform Dashboard is a comprehensive reporting tool designed to provide insights into the performance, security,
@@ -25,21 +25,22 @@ import Thumbnail from "@site/src/components/Thumbnail";
 
 # Platform Dashboard
 
-Go to the `Platform Report` tab in the `Insights` panel for your project to view the new platform metrics. This
-dashboard provides a visual overview of key metrics across four main categories, offering a comprehensive assessment of
-the Data Delivery Network platform:
+## Introduction
+
+Go to the `Platform Report` tab in the `Insights` panel for your project to view platform metrics. This dashboard
+provides a visual overview of key metrics across four main categories, offering a comprehensive assessment of your API.
 
 ## Security and Governance
 
 :::tip Available on
 
-Security and Governance metrics are available on DDN Free plans and up.
+Security and Governance metrics are available on [DDN Free plans](https://hasura.io/docs) and up.
 
 :::
 
 The Security and Governance dashboard provides comprehensive insights into three key areas:
 
-### Authentication Status
+### Authentication status
 
 Quickly identify and resolve authentication configuration issues:
 
@@ -53,7 +54,7 @@ Quickly identify and resolve authentication configuration issues:
   width="1000"
 />
 
-### Permission Analysis
+### Permission analysis
 
 Monitor and manage permissions across your supergraph:
 
@@ -80,7 +81,7 @@ Monitor and manage permissions across your supergraph:
   width="1000"
 />
 
-### Documentation Coverage
+### Documentation coverage
 
 Track and improve API documentation:
 
@@ -101,7 +102,7 @@ Track and improve API documentation:
   width="1000"
 />
 
-## API Reliability
+## API reliability
 
 :::tip Available on
 
@@ -120,25 +121,25 @@ Monitor your API's health with:
   width="1000"
 />
 
-## API Usage Trends
+## API usage trends
 
 :::tip Available on
 
 API Usage Trends metrics are available on DDN Base plans and up.
 
 :::
 
-### Requests per Day
+### Requests per day
 
 <Thumbnail src="/img/get-started/dashboard_request_trend.png" alt="x" width="1000" />
 
-### Deprecated Metadata
+### Deprecated metadata
 
 Deprecated Features: List of deprecated objects.
 
 <Thumbnail src="/img/get-started/dashboard_usage.png" alt="x" width="1000" />
 
-## Developer Productivity
+## Developer productivity
 
 :::tip Available on
 
@@ -148,13 +149,13 @@ Basic metrics available on DDN Base plans and up. Advanced team analytics availa
 
 Track team collaboration and access patterns:
 
-### Project Access Distribution
+### Project access distribution
 
 - Visual breakdown of user roles (Owner, Admin, Read-only)
 - Total user count
 - Available on DDN Base plans
 
-### Subgraph Access Distribution
+### Subgraph access distribution
 
 - Per-subgraph collaboration metrics
 - Admin and read-only user distribution

docs/observability/traces.mdx → docs/observability/built-in/traces.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 1
 sidebar_label: Traces
 description:
   "Learn how to leverage OpenTelemetry traces to track user requests across various services in the Hasura Data Delivery
@@ -36,8 +36,8 @@ points.
 
 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 `Query Tracing` tab from `Insights` panel for a project's Console, and you'll see traces for
-all your API requests.
+collector.** Simply head to the `Query Tracing` tab from `Insights` panel for a project's Console, and you'll see traces
+for all your API requests.
 
 :::info Accessing traces
 
@@ -114,7 +114,7 @@ are exported separately from the connector and are handled automatically if the
 However, self-hosted connectors need to configure the variables below or connector traces will not be visible on the DDN
 console:
 
-- `OTEL_EXPORTER_OTLP_ENDPOINT`: https://gateway.otlp.hasura.io:443
+- `OTEL_EXPORTER_OTLP_ENDPOINT`: `https://gateway.otlp.hasura.io:443`
 - `OTEL_EXPORTER_OTLP_HEADERS`: `Authorization=pat <personal-access-token>`
 
 The trace ID is propagated through [B3 (Zipkin) headers][B3 propagation], and must be extracted accordingly to ensure

docs/observability/overview.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-sidebar_label: Overview
+sidebar_label: Basics
 description:
   "Explore Hasura's observability tools that optimize the monitoring and debugging of your GraphQL API. Learn about
   performance check, error debugging, and gaining insights into the use of your GraphQL API for increased productivity
@@ -16,25 +16,19 @@ keywords:
   - graphql metrics
   - api tracing
   - hasura tools
-hide_table_of_contents: true
 seoFrontMatterUpdated: true
 ---
 
-import { OverviewTopSectionIconNoVideo } from "@site/src/components/OverviewTopSectionIconNoVideo";
-import { OverviewPlainCard } from "@site/src/components/OverviewPlainCard";
-import Icon from "@site/static/icons/eye.svg";
+# Basics
 
-# Observability
+## Built-in features
 
-## Introduction
-
-Out of the box, Hasura DDN comes with a powerful 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.
+Hasura DDN prevents the need of adding additional observability tools to your application stack. Instead, you can use
+our suite of built-in tools to monitor your API and diagnose any issues along your data pipeline.
 
 ## Find out more
 
-- [Query plan](/observability/explain/index.mdx)
-- [Metrics](/observability/metrics.mdx)
-- [Traces](/observability/traces.mdx)
-- [Analytics](/observability/model-analytics/index.mdx)
+- [Traces](/observability/built-in/traces.mdx)
+- [Metrics](/observability/built-in/metrics.mdx)
+- [Analytics](/observability/built-in/model-analytics/index.mdx)
+- [Query plan](/observability/built-in/explain/index.mdx)