From 902c0da62fa326f4865da646bb1b41e3d1d06e0b Mon Sep 17 00:00:00 2001 From: Rob Dominguez Date: Wed, 12 Feb 2025 11:57:35 -0800 Subject: [PATCH] Docs: update o11y section (#884) --- docs/graphql-api/errors.mdx | 2 +- docs/observability/built-in/_category_.json | 4 +++ .../{ => built-in}/explain/_category_.json | 2 +- .../{ => built-in}/explain/api-reference.mdx | 18 +++++------ .../{ => built-in}/explain/index.mdx | 4 +-- docs/observability/built-in/index.mdx | 13 ++++++++ docs/observability/{ => built-in}/metrics.mdx | 8 ++--- .../model-analytics/_category_.json | 2 +- .../{ => built-in}/model-analytics/field.mdx | 16 ++++------ .../{ => built-in}/model-analytics/index.mdx | 7 +++-- .../model-analytics/operation.mdx | 7 ++--- .../{ => built-in}/platform-dashboard.mdx | 31 ++++++++++--------- docs/observability/{ => built-in}/traces.mdx | 8 ++--- docs/observability/overview.mdx | 24 ++++++-------- 14 files changed, 77 insertions(+), 69 deletions(-) create mode 100644 docs/observability/built-in/_category_.json rename docs/observability/{ => built-in}/explain/_category_.json (64%) rename docs/observability/{ => built-in}/explain/api-reference.mdx (97%) rename docs/observability/{ => built-in}/explain/index.mdx (96%) create mode 100644 docs/observability/built-in/index.mdx rename docs/observability/{ => built-in}/metrics.mdx (84%) rename docs/observability/{ => built-in}/model-analytics/_category_.json (63%) rename docs/observability/{ => built-in}/model-analytics/field.mdx (90%) rename docs/observability/{ => built-in}/model-analytics/index.mdx (76%) rename docs/observability/{ => built-in}/model-analytics/operation.mdx (94%) rename docs/observability/{ => built-in}/platform-dashboard.mdx (87%) rename docs/observability/{ => built-in}/traces.mdx (97%) diff --git a/docs/graphql-api/errors.mdx b/docs/graphql-api/errors.mdx index d2cac6299..6bfc1d006 100644 --- a/docs/graphql-api/errors.mdx +++ b/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, diff --git a/docs/observability/built-in/_category_.json b/docs/observability/built-in/_category_.json new file mode 100644 index 000000000..59f53935f --- /dev/null +++ b/docs/observability/built-in/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Built-in features", + "position": 2 +} diff --git a/docs/observability/explain/_category_.json b/docs/observability/built-in/explain/_category_.json similarity index 64% rename from docs/observability/explain/_category_.json rename to docs/observability/built-in/explain/_category_.json index 9816d8b39..8573fb3fa 100644 --- a/docs/observability/explain/_category_.json +++ b/docs/observability/built-in/explain/_category_.json @@ -1,4 +1,4 @@ { "label": "Query Plan", - "position": 2 + "position": 4 } diff --git a/docs/observability/explain/api-reference.mdx b/docs/observability/built-in/explain/api-reference.mdx similarity index 97% rename from docs/observability/explain/api-reference.mdx rename to docs/observability/built-in/explain/api-reference.mdx index dd73b61b6..51d78836d 100644 --- a/docs/observability/explain/api-reference.mdx +++ b/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 diff --git a/docs/observability/explain/index.mdx b/docs/observability/built-in/explain/index.mdx similarity index 96% rename from docs/observability/explain/index.mdx rename to docs/observability/built-in/explain/index.mdx index 0e2651022..efb27b55b 100644 --- a/docs/observability/explain/index.mdx +++ b/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 { -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 diff --git a/docs/observability/built-in/index.mdx b/docs/observability/built-in/index.mdx new file mode 100644 index 000000000..d462a7877 --- /dev/null +++ b/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 diff --git a/docs/observability/metrics.mdx b/docs/observability/built-in/metrics.mdx similarity index 84% rename from docs/observability/metrics.mdx rename to docs/observability/built-in/metrics.mdx index 75f2ef0f2..c58bbf029 100644 --- a/docs/observability/metrics.mdx +++ b/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. diff --git a/docs/observability/model-analytics/_category_.json b/docs/observability/built-in/model-analytics/_category_.json similarity index 63% rename from docs/observability/model-analytics/_category_.json rename to docs/observability/built-in/model-analytics/_category_.json index 01aa107c8..6f870295b 100644 --- a/docs/observability/model-analytics/_category_.json +++ b/docs/observability/built-in/model-analytics/_category_.json @@ -1,4 +1,4 @@ { "label": "Analytics", - "position": 5 + "position": 3 } diff --git a/docs/observability/model-analytics/field.mdx b/docs/observability/built-in/model-analytics/field.mdx similarity index 90% rename from docs/observability/model-analytics/field.mdx rename to docs/observability/built-in/model-analytics/field.mdx index 681b1ae43..925a4d541 100644 --- a/docs/observability/model-analytics/field.mdx +++ b/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. @@ -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,8 +130,7 @@ 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 @@ -141,8 +138,7 @@ requests made. 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. diff --git a/docs/observability/model-analytics/index.mdx b/docs/observability/built-in/model-analytics/index.mdx similarity index 76% rename from docs/observability/model-analytics/index.mdx rename to docs/observability/built-in/model-analytics/index.mdx index 13b4f6ee8..49ee8ddb2 100644 --- a/docs/observability/model-analytics/index.mdx +++ b/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). diff --git a/docs/observability/model-analytics/operation.mdx b/docs/observability/built-in/model-analytics/operation.mdx similarity index 94% rename from docs/observability/model-analytics/operation.mdx rename to docs/observability/built-in/model-analytics/operation.mdx index 4482bf67d..a21ed94b7 100644 --- a/docs/observability/model-analytics/operation.mdx +++ b/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. ## 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. diff --git a/docs/observability/platform-dashboard.mdx b/docs/observability/built-in/platform-dashboard.mdx similarity index 87% rename from docs/observability/platform-dashboard.mdx rename to docs/observability/built-in/platform-dashboard.mdx index c8ce01b60..f46e71c40 100644 --- a/docs/observability/platform-dashboard.mdx +++ b/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,7 +121,7 @@ Monitor your API's health with: width="1000" /> -## API Usage Trends +## API usage trends :::tip Available on @@ -128,17 +129,17 @@ API Usage Trends metrics are available on DDN Base plans and up. ::: -### Requests per Day +### Requests per day -### Deprecated Metadata +### Deprecated metadata Deprecated Features: List of deprecated objects. -## 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 diff --git a/docs/observability/traces.mdx b/docs/observability/built-in/traces.mdx similarity index 97% rename from docs/observability/traces.mdx rename to docs/observability/built-in/traces.mdx index 42f4abf6f..d2b844a0e 100644 --- a/docs/observability/traces.mdx +++ b/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 ` The trace ID is propagated through [B3 (Zipkin) headers][B3 propagation], and must be extracted accordingly to ensure diff --git a/docs/observability/overview.mdx b/docs/observability/overview.mdx index 233b9fc9c..c40a7d8a7 100644 --- a/docs/observability/overview.mdx +++ b/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)