add support of metrics

CHANGELOG.md

@@ -60,12 +60,19 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
   ```yaml
   plugins:
-  apollo.telemetry:
-    metrics:
-      exporter:
-        prometheus:
-          endpoint: "/metrics"
-  ```
+    apollo.telemetry:
+      metrics:
+        exporter:
+          prometheus:
+            # By setting this endpoint you enable the prometheus exporter
+            # All our endpoints exposed by plugins are namespaced by the name of the plugin
+            # Then to access to this prometheus endpoint, the full url path will be `/plugins/apollo.telemetry/metrics`
+            endpoint: "/metrics"
+    ```
+
+- **Add experimental support of `custom_endpoint` method in `Plugin` trait** ([#738](https://github.com/apollographql/router/pull/738))
+
+  The `custom_endpoint` method lets you declare a new endpoint exposed for your plugin. For now it's only accessible for official `apollo.` plugins and for `experimental.`. The return type of this method is a Tower [`Service`]().
 
 ## 🐛 Fixes
 - **Trim the query to better detect an empty query** ([PR #738](https://github.com/apollographql/router/pull/738))

docs/source/configuration/header-propagation.mdx

@@ -9,18 +9,18 @@ You define header rules in your [YAML configuration file](./overview/#configurat
 
 ```yaml title="router.yaml"
 # ...other configuration...
-
-headers:
-  all: # Header rules for all subgraphs
-    - propagate:
-        matching: ^upstream-header-.*
-    - remove:
-        named: "x-legacy-account-id"
-  subgraphs:
-    products: # Header rules for just the products subgraph
-    - insert:
-        name: "router-subgraph-name"
-        value: "products"
+plugins:
+  apollo.headers:
+    all: # Header rules for all subgraphs
+      - propagate:
+          matching: ^upstream-header-.*
+      - remove:
+          named: "x-legacy-account-id"
+    subgraphs:
+      products: # Header rules for just the products subgraph
+      - insert:
+          name: "router-subgraph-name"
+          value: "products"
 
 ```
 
@@ -81,37 +81,38 @@ Enables you to add custom headers to requests going to a specific subgraph. Thes
 Here's a complete example showing all the possible configuration options in use:
 
 ```yaml title="router.yaml"
-headers:
-  # Header rules for all subgraphs
-  all:
-  # Propagate matching headers
-  - propagate:
-      matching: ^upstream-header-.*
-  # Propagate matching headers
-  - propagate:
-      named: "some-header"
-      default: "default-value"
-      rename: "destination-header"
-  # Remove the "x-legacy-account-id" header
-  - remove:
-      named: "x-legacy-account-id"
-  # Remove matching headers
-  - remove:
-      matching: ^x-deprecated-.*
-  # Insert the 'my-company' header
-  - insert:
-      name: "my-company"
-      value: "acme"
-  # Subgraph-specific header rules
-  subgraphs:
-    products:
-      # Calls to the products subgraph have the "router-subgraph-name" header set to `products`.
-      - insert:
-          name: "router-subgraph-name"
-          value: "products"
-    accounts:
-      # Calls to the accounts subgraph have the "router-subgraph-name" header set to `accounts`.
-      - insert:
-          name: "router-subgraph-name"
-          value: "accounts"
+plugins:
+  apollo.headers:
+    # Header rules for all subgraphs
+    all:
+    # Propagate matching headers
+    - propagate:
+        matching: ^upstream-header-.*
+    # Propagate matching headers
+    - propagate:
+        named: "some-header"
+        default: "default-value"
+        rename: "destination-header"
+    # Remove the "x-legacy-account-id" header
+    - remove:
+        named: "x-legacy-account-id"
+    # Remove matching headers
+    - remove:
+        matching: ^x-deprecated-.*
+    # Insert the 'my-company' header
+    - insert:
+        name: "my-company"
+        value: "acme"
+    # Subgraph-specific header rules
+    subgraphs:
+      products:
+        # Calls to the products subgraph have the "router-subgraph-name" header set to `products`.
+        - insert:
+            name: "router-subgraph-name"
+            value: "products"
+      accounts:
+        # Calls to the accounts subgraph have the "router-subgraph-name" header set to `accounts`.
+        - insert:
+            name: "router-subgraph-name"
+            value: "accounts"
 ```

docs/source/configuration/opentelemetry.mdx

@@ -7,14 +7,14 @@ import { Link } from "gatsby";
 
 The Apollo Router supports [OpenTelemetry](https://opentelemetry.io/), with exporters for:
 
-* [Jaeger](https://www.jaegertracing.io/)
-* [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md) over HTTP or gRPC.
+- [Jaeger](https://www.jaegertracing.io/)
+- [OpenTelemetry Protocol (OTLP)](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md) over HTTP or gRPC.
 
 The Apollo Router generates spans that include the various phases of serving a request and associated dependencies. This is useful for showing how response time is affected by:
 
-* Sub-request response times
-* Query shape (sub-request dependencies)
-* Apollo Router post-processing
+- Sub-request response times
+- Query shape (sub-request dependencies)
+- Apollo Router post-processing
 
 Span data is sent to a collector such as [Jaeger](https://www.jaegertracing.io/), which can assemble spans into a gantt chart for analysis.
 
@@ -28,26 +28,27 @@ If you're using OpenTelemetry throughout your systems and just want to view in [
 
 ```yaml title="router.yaml"
 # ...other configuration...
-
-telemetry:
-  # Optional if you want to enable opentracing propagation headers to your subgraphs
-  opentracing:
-    # "zipkin_b3" and "jaeger" formats are supported
-    format: "zipkin_b3"
-
-  # ...other telemetry configuration...
+plugins:
+  apollo.telemetry:
+    # Optional if you want to enable opentracing propagation headers to your subgraphs
+    opentracing:
+      # "zipkin_b3" and "jaeger" formats are supported
+      format: "zipkin_b3"
+
+    # ...other telemetry configuration...
 ```
 
 ## Using Jaeger
 
 The Apollo Router can be configured to export tracing data to Jaeger either via an agent or http collector.
 
 ```yaml title="router.yaml"
-telemetry:
-  opentelemetry:
-    jaeger:
-      # Optional: if not present, jaeger will use the default UDP agent address
-      #endpoint:
+plugins:
+  apollo.telemetry:
+    opentelemetry:
+      jaeger:
+        # Optional: if not present, jaeger will use the default UDP agent address
+        #endpoint:
         # address for the UDP agent mode
         # incomptable with collector
         # agent: "127.0.0.1:1234"
@@ -57,65 +58,12 @@ telemetry:
         # the username and password are obtained from the environment variables
         # JAEGER_USERNAME and JAEGER_PASSWORD
 
-      # Name of the service used in traces
-      # defaults to router
-      service_name: "router"
-
-      trace_config:
-        # Trace sampling: possible values are `AlwaysOn`, `AlwaysOff`, or
-        # `TraceIdRatioBased: number`. The ratio sampler takes a value between 0
-        # and 1 and decides on trace creation whether it will be recorded.
-        sampler:
-          TraceIdRatioBased: 0.42
-        max_events_per_span: 1
-        max_attributes_per_span: 2
-        max_links_per_span: 3
-        max_attributes_per_event: 4
-        max_attributes_per_link: 5
-
-        # Trace attributes accept a map of: Bool, Float, Int, String, Bool[], Float[], Int[], String[] 
-        attributes:
-          str: "a"
-          int: 1
-          float: 1.0
-          bool: true
-          str_arr:
-            - "a"
-            - "b"
-          int_arr:
-            - 1
-            - 2
-          float_arr:
-            - 1.0
-            - 2.0
-          bool_arr:
-            - true
-            - false
-```
-
-## OpenTelemetry Collector via OTLP
-
-[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) is a horizontally scalable collector that can be used to receive, process and export your telemetry data in a pluggable way.
-
-If you find that the built-in telemetry features of the Apollo Router are missing some desired functionality e.g. [exporting to Kafka](https://opentelemetry.io/docs/collector/configuration/#exporters) then it's worth considering this option.
+        # Name of the service used in traces
+        # defaults to router
+        service_name: "router"
 
-```yaml title="router.yaml"
-telemetry:
-  # Configuration to send traces and metrics to an OpenTelemetry Protocol compatible service
-  opentelemetry:
-    otlp:
-      tracing:
-        exporter:
-          # 'http' for OTLP/HTTP, 'grpc' for OTLP/gRPC
-          grpc:
-            # URL of the exporter
-            endpoint: http://example.com
-            # Possible options: 'Grpc' for GRPC protocol and 'HttpBinary' for HTTP protocol with binary protobuf
-            protocol: Grpc
-            # timmeout in seconds
-            timeout: 60
         trace_config:
-          # trace sampling: possible values are `AlwaysOn`, `AlwaysOff`, or
+          # Trace sampling: possible values are `AlwaysOn`, `AlwaysOff`, or
           # `TraceIdRatioBased: number`. The ratio sampler takes a value between 0
           # and 1 and decides on trace creation whether it will be recorded.
           sampler:
@@ -125,8 +73,8 @@ telemetry:
           max_links_per_span: 3
           max_attributes_per_event: 4
           max_attributes_per_link: 5
-          
-          # Trace attributes accept a map of: Bool, Float, Int, String, Bool[], Float[], Int[], String[] 
+
+          # Trace attributes accept a map of: Bool, Float, Int, String, Bool[], Float[], Int[], String[]
           attributes:
             str: "a"
             int: 1
@@ -145,3 +93,84 @@ telemetry:
               - true
               - false
 ```
+
+## OpenTelemetry Collector via OTLP
+
+[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) is a horizontally scalable collector that can be used to receive, process and export your telemetry data in a pluggable way.
+
+If you find that the built-in telemetry features of the Apollo Router are missing some desired functionality e.g. [exporting to Kafka](https://opentelemetry.io/docs/collector/configuration/#exporters) then it's worth considering this option.
+
+```yaml title="router.yaml"
+plugins:
+  apollo.telemetry:
+    # Metrics configuration
+    metrics:
+      exporter:
+        otlp:
+          grpc:
+            # URL of the exporter
+            endpoint: http://127.0.0.1:4317
+            # Possible options: 'Grpc' (HttpBinary is not already supported for metrics)
+            protocol: Grpc
+            # timmeout in seconds
+            timeout: 60
+    # Configuration to send traces and metrics to an OpenTelemetry Protocol compatible service
+    opentelemetry:
+      otlp:
+        tracing:
+          exporter:
+            # 'http' for OTLP/HTTP, 'grpc' for OTLP/gRPC
+            grpc:
+              # URL of the exporter
+              endpoint: http://example.com
+              # Possible options: 'Grpc' for GRPC protocol and 'HttpBinary' for HTTP protocol with binary protobuf
+              protocol: Grpc
+              # timmeout in seconds
+              timeout: 60
+          trace_config:
+            # trace sampling: possible values are `AlwaysOn`, `AlwaysOff`, or
+            # `TraceIdRatioBased: number`. The ratio sampler takes a value between 0
+            # and 1 and decides on trace creation whether it will be recorded.
+            sampler:
+              TraceIdRatioBased: 0.42
+            max_events_per_span: 1
+            max_attributes_per_span: 2
+            max_links_per_span: 3
+            max_attributes_per_event: 4
+            max_attributes_per_link: 5
+
+            # Trace attributes accept a map of: Bool, Float, Int, String, Bool[], Float[], Int[], String[]
+            attributes:
+              str: "a"
+              int: 1
+              float: 1.0
+              bool: true
+              str_arr:
+                - "a"
+                - "b"
+              int_arr:
+                - 1
+                - 2
+              float_arr:
+                - 1.0
+                - 2.0
+              bool_arr:
+                - true
+                - false
+```
+
+## Using Prometheus to collect metrics
+
+You can use [Prometheus and Grafana](https://prometheus.io/docs/visualization/grafana/) to collect metrics and visualize the router metrics.
+
+```yaml title="router.yaml"
+plugins:
+  apollo.telemetry:
+    metrics:
+      exporter:
+        prometheus:
+          # By setting this endpoint you enable the prometheus exporter
+          # All our endpoints exposed by plugins are namespaced by the name of the plugin
+          # Then to access to this prometheus endpoint, the full url path will be `/plugins/apollo.telemetry/metrics`
+          endpoint: "/metrics"
+```