docs: add documentation for telemetry directive (#113)

* docs: add documentation for trace directive * fix lint * rename and update info * update call * update index * update telemetry * update telemetry --------- Co-authored-by: Tushar Mathur <[email protected]>
tailcallhq · Mar 7, 2024 · 14ae910 · 14ae910
1 parent 36c3c85
commit 14ae910
Show file tree

Hide file tree

Showing 3 changed files with 111 additions and 15 deletions.
diff --git a/docs/operators/call.md b/docs/operators/call.md
@@ -1,5 +1,6 @@
 ---
-title: Leveraging the @call Directive in GraphQL for Enhanced Code Reusability
+title: "@call"
+description: "Using the call directive to enhance GraphQL schemas improving code reusability."
 ---
 
 The `@call` directive in GraphQL signifies a paradigm shift towards more efficient code structuring by introducing a methodology akin to function invocations in conventional programming. This directive is pivotal for developers navigating the intricacies of elaborate GraphQL schemas, where minimizing redundancy and adhering to the DRY (Don't Repeat Yourself) principle are paramount. Consider the following schema example:

diff --git a/docs/operators/index.md b/docs/operators/index.md
@@ -1,5 +1,6 @@
 ---
 title: "Operators"
+description: "A list of all the custom operators supported by Tailcall."
 ---
 
 Tailcall DSL builds on your existing GraphQL knowledge by allowing the addition of some custom operators. These operators provide powerful compile time guarantees to ensure your API composition is tight and robust. The system automatically generates highly optimized resolver logic for your types using the operator information.
@@ -10,17 +11,18 @@ Certainly! Here's the table with hyperlinks added back to the operator names:
 
 <!-- SORT OPERATOR BY NAME -->
 
-| Operator                  | Description                                                                                                  |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [@addField](add-field.md) | Simplifies data structures and queries by adding, inlining, or flattening fields or nodes within the schema. |
-| [@cache](cache.md)        | Enables caching for the query, field or type applied to.                                                     |
-| [@call](call.md)          | Invokes a query or mutation from another query or mutation field.                                            |
-| [@const](const.md)        | Allows embedding of a constant response within the schema.                                                   |
-| [@graphQL](graphql.md)    | Resolves a field or node by a GraphQL API.                                                                   |
-| [@grpc](grpc.md)          | Resolves a field or node by a gRPC API.                                                                      |
-| [@http](http.md)          | Resolves a field or node by a REST API.                                                                      |
-| [@link](link.md)          | Imports external resources such as config files, certs, protobufs, etc in the schema.                        |
-| [@modify](modify.md)      | Enables changes to attributes of fields or nodes in the schema.                                              |
-| [@omit](omit.md)          | Excludes fields or nodes from the generated schema, making them inaccessible through the GraphQL API.        |
-| [@server](server.md)      | Provides server configurations for behavior tuning and tailcall optimization in specific use-cases.          |
-| [@upstream](upstream.md)  | Controls aspects of the upstream server connection, including timeouts and keep-alive settings.              |
+| Operator                   | Description                                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| [@addField](add-field.md)  | Simplifies data structures and queries by adding, inlining, or flattening fields or nodes within the schema. |
+| [@cache](cache.md)         | Enables caching for the query, field or type applied to.                                                     |
+| [@call](call.md)           | Invokes a query or mutation from another query or mutation field.                                            |
+| [@const](const.md)         | Allows embedding of a constant response within the schema.                                                   |
+| [@graphQL](graphql.md)     | Resolves a field or node by a GraphQL API.                                                                   |
+| [@grpc](grpc.md)           | Resolves a field or node by a gRPC API.                                                                      |
+| [@http](http.md)           | Resolves a field or node by a REST API.                                                                      |
+| [@link](link.md)           | Imports external resources such as config files, certs, protobufs, etc in the schema.                        |
+| [@modify](modify.md)       | Enables changes to attributes of fields or nodes in the schema.                                              |
+| [@omit](omit.md)           | Excludes fields or nodes from the generated schema, making them inaccessible through the GraphQL API.        |
+| [@server](server.md)       | Provides server configurations for behavior tuning and tailcall optimization in specific use-cases.          |
+| [@telemetry](telemetry.md) | Integrates with open-telemetry to provide observability of the running tailcall service.                     |
+| [@upstream](upstream.md)   | Controls aspects of the upstream server connection, including timeouts and keep-alive settings.              |
diff --git a/docs/operators/telemetry.md b/docs/operators/telemetry.md
@@ -0,0 +1,93 @@
+---
+title: "@telemetry"
+description: "Integrate observability into your Tailcall services using @telemetry directive with OpenTelemetry."
+---
+
+The `@telemetry` directive facilitates seamless integration with [OpenTelemetry](https://open-telemetry.io), enhancing the observability of your GraphQL services powered by Tailcall. By leveraging this directive, developers gain access to valuable insights into the performance and behavior of their applications.
+
+## Traces
+
+Here are the traces that are captured by the `@telemetry` directive:
+
+|      Trace Name | Description                                                                                                                                                                                        |
+| --------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|  handle_request | Captures the span for processing the HTTP request on the server side, providing foundational observability.                                                                                        |
+| field::resolver | Denotes spans for fields with defined resolvers, offering insights into field names and execution times for resolver logic.                                                                        |
+|      expr::eval | Nested within the `field::resolver` spans, these granulated spans detail the execution of expressions in resolving a field, highlighting the hierarchical execution pattern of nested expressions. |
+
+## Metrics
+
+The `@telemetry` directive also captures the following metrics:
+
+|          Metric | Description                                                                               |
+| --------------: | :---------------------------------------------------------------------------------------- |
+| cache::hit_rate | Reflects the cache hit rate for the cache powered by the [`@cache`](./cache.md) directive |
+
+## export
+
+The `export` field defines how the open-telemetry data should be exported and in which format. The following are the supported formats:
+
+## otlp
+
+Utilizes the OTLP format to export telemetry data to backend systems, supported by most modern tracing and analytics platforms. Here is an example using [honeycomb.io]:
+
+[honecomb.io]: https://www.honeycomb.io/
+
+```graphql
+schema
+  @telemetry(
+    export: {
+      otlp: {
+        url: "https://api.honeycomb.io:443"
+        headers: [
+          {key: "x-honeycomb-team", value: "{{env.HONEYCOMB_API_KEY}}"}
+          {key: "x-honeycomb-dataset", value: "tailcall"}
+        ]
+      }
+    }
+  ) {
+  query: Query
+}
+```
+
+You can configure the OTLP exporter with the following options:
+
+|   Field | Description                                                 |
+| ------: | ----------------------------------------------------------- |
+|     url | Defines the URL for the OTLP Collector.                     |
+| headers | Sets additional headers for requests to the OTLP Collector. |
+
+## prometheus
+
+Facilitates metrics export in a Prometheus compatible format, providing a dedicated endpoint for metrics.
+
+```graphql
+schema @telemetry(export: {prometheus: {path: "/metrics"}}) {
+  query: Query
+}
+```
+
+You can configure the Prometheus exporter with the following options:
+
+|  Field | Description                                                                        |
+| -----: | ---------------------------------------------------------------------------------- |
+|   path | Designates the endpoint path for Prometheus metrics, defaulting to `/metrics`.     |
+| format | Controls the format viz. **text** or **protobuf**, for sending data to Prometheus. |
+
+## stdout
+
+Outputs all telemetry data to stdout, ideal for testing or local development environments.
+
+```graphql
+schema @telemetry(export: {stdout: {pretty: true}}) {
+  query: Query
+}
+```
+
+You can configure the stdout exporter with the following options:
+
+|  Field | Description                                                          |
+| -----: | -------------------------------------------------------------------- |
+| pretty | Enables formatted output of telemetry data for enhanced readability. |
+
+By integrating the `@telemetry` directive into your GraphQL schema, you empower your development teams with critical insights into application performance, enabling proactive optimization and maintenance.