diff --git a/docs/source/config.json b/docs/source/config.json index e841d24609..66fc7aa7f9 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -128,6 +128,7 @@ "Zipkin": "/configuration/telemetry/exporters/tracing/zipkin" }, "Instrumentation": { + "Instruments" : "/configuration/telemetry/instrumentation/instruments", "Spans" : "/configuration/telemetry/instrumentation/spans", "Selectors" : "/configuration/telemetry/instrumentation/selectors", "Standard attributes": "/configuration/telemetry/instrumentation/standard-attributes", diff --git a/docs/source/configuration/telemetry/exporters/metrics/overview.mdx b/docs/source/configuration/telemetry/exporters/metrics/overview.mdx index 26918d9ef0..fad0471ff1 100644 --- a/docs/source/configuration/telemetry/exporters/metrics/overview.mdx +++ b/docs/source/configuration/telemetry/exporters/metrics/overview.mdx @@ -1,5 +1,5 @@ --- -title: Router Metrics +title: Metrics exporters subtitle: Export Apollo Router metrics description: Collect and export metrics from the Apollo Router for Prometheus, OpenTelemetry Protocol (OTLP), Datadog, and New Relic --- diff --git a/docs/source/configuration/telemetry/instrumentation/instruments.mdx b/docs/source/configuration/telemetry/instrumentation/instruments.mdx index cff1cfd7ff..6d26b18b67 100644 --- a/docs/source/configuration/telemetry/instrumentation/instruments.mdx +++ b/docs/source/configuration/telemetry/instrumentation/instruments.mdx @@ -8,25 +8,20 @@ import RouterServices from '../../../../shared/router-lifecycle-services.mdx'; -An **instrument** is used to collect data and report measurements to a metric backend. The Apollo Router supports the following metric instruments: +An _instrument_ in the router collects data and reports measurements to a metric backend. Supported instruments include standard instruments from OpenTelemetry, standard instruments for the router's request lifecycle, and custom instruments. Supported instrument kinds are counters and histograms. -* Counter -* Histogram +You can configure instruments in `router.yaml` with `telemetry.instrumentation.instruments`. -Instruments in the router are configurable in `router.yaml` as `telemetry.instruments`. +### OpenTelemetry standard instruments -### Standard instruments - -OpenTelemetry semantic conventions define several standard metric instruments that are available and configurable in the router: +OpenTelemetry specifies multiple [standard metric instruments](https://opentelemetry.io/docs/specs/semconv/http/http-metrics/) that are available in the router: * `http.server.active_requests` - The number of active requests in flight. * `http.server.request.body.size` - A histogram of request body sizes for requests handled by the router. * `http.server.request.duration` - A histogram of request durations for requests handled by the router. * `http.server.response.body.size` - A histogram of response body sizes for requests handled by the router. -For more information, see the [OpenTelemetry semantic conventions for HTTP metrics](https://opentelemetry.io/docs/specs/semconv/http/http-metrics/). - -These standard instruments are configurable in `router.yaml`: +These instruments are configurable in `router.yaml`: ```yaml title="router.yaml" telemetry: @@ -39,7 +34,7 @@ telemetry: http.server.response.body.size: true # (default false) ``` -Standard instruments can be customized by attaching or removing attributes. +They can be customized by attaching or removing attributes. See [attributes](#attributes) to learn more about configuring attributes. ```yaml title="router.yaml" telemetry: @@ -52,17 +47,19 @@ telemetry: http.request.method: true ``` -See the [attributes](#attributes) configuration for more information. +### Apollo standard instruments + +To learn about standard metric instruments for the router's request lifecycle, see [Apollo Router instruments](./standard-instruments). ### Custom instruments -You can define custom instruments on the router, supergraph and subgraph services in the router pipeline. +You can define custom instruments on the router, supergraph, and subgraph services in the router pipeline. -When defining a custom instrument, make sure to reference the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/). +When defining a custom instrument, make sure to reference [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/general/metrics/). diff --git a/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx b/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx index 25d55c165e..474b5f604d 100644 --- a/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx +++ b/docs/source/configuration/telemetry/instrumentation/standard-instruments.mdx @@ -6,7 +6,7 @@ description: Reference of standard metric instruments for the Apollo Router's re ## Standard metric instruments -The Apollo Router provides a set of non-configurable metric instruments that expose detailed information about the Router's request lifecycle. +The Apollo Router provides a set of non-configurable metric instruments that expose detailed information about the router's request lifecycle. These instruments can be consumed by configuring a [metrics exporter](../exporters/metrics/overview). diff --git a/docs/source/configuration/telemetry/overview.mdx b/docs/source/configuration/telemetry/overview.mdx index 821f4e707c..374ab96970 100644 --- a/docs/source/configuration/telemetry/overview.mdx +++ b/docs/source/configuration/telemetry/overview.mdx @@ -94,15 +94,17 @@ Logs can be consumed by [logging exporters](./exporters/logging/overview) and as ### Metrics and instruments -Metrics monitor aggregate information about the Apollo Router. Metrics include histograms, gauges, and counts. An individual metric is called an **instrument**. Examples of instruments include: +Metrics are measurements of the router's behavior that can be exported and monitored. Different kinds of metrics include histograms, gauges, and counts. + +Metrics can be consumed by _exporters_. See [Metrics exporters](./exporters/metrics/overview) for an overview of supported exporters. + +An individual metric is called an _instrument_. Example instruments of the router include: * Number of received requests * Histogram of request durations * Number of in-flight requests -You can find a full list of instruments in the [instrument documentation](./instrumentation/standard-instruments). - -Metrics can be consumed via [metrics exporters](./exporters/metrics/overview). +See [Instruments](./instrumentation/instruments) for an overview of available instruments and a guide for configuring and customizing instruments. ### Traces and spans