refactor(prometheus-plugin): rename metrics options (#2270)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

.changeset/heavy-houses-kick.md

@@ -0,0 +1,51 @@
+---
+'@envelop/prometheus': major
+---
+
+**Breaking Change:** Rename all metrics options to their actual metric name to avoid confusion.
+
+All metric options have been moved under a mandatory `metrics` key, and the name of each options
+have been renamed to match the default metric name.
+
+The plugin option argument is also now mandatory.
+
+```diff
+export const serveConfig = defineConfig({
+  plugins: pluginCtx => [
+    usePrometheus({
+      ...pluginCtx,
+
+      // Enable all available metrics
+
+-     requestSummary: true,
+-     parse: true,
+-     validate: true,
+-     contextBuilding: true,
+-     execute: true,
+-     subscribe: true,
+-     errors: true,
+-     deprecatedFields: true,
+-     requestTotalDuration: true,
+-     schemaChangeCount: true,
+
+      // Warning: enabling resolvers level metrics will introduce significant overhead
+-     resolvers: true,
++     metrics: {
++       graphql_envelop_request_time_summary: true,
++       graphql_envelop_phase_parse: true,
++       graphql_envelop_phase_validate: true,
++       graphql_envelop_phase_context: true,
++       graphql_envelop_phase_execute: true,
++       graphql_envelop_phase_subscribe: true,
++       graphql_envelop_error_result: true,
++       graphql_envelop_deprecated_field: true,
++       graphql_envelop_request_duration: true,
++       graphql_envelop_schema_change: true,
+
+        // Warning: enabling resolvers level metrics will introduce significant overhead
++       graphql_envelop_execute_resolver: true,
++     }
+    })
+  ]
+})
+```

.changeset/proud-insects-tell.md

@@ -0,0 +1,5 @@
+---
+'@envelop/prometheus': minor
+---
+
+Add missing labels `path` and `phase` of `graphql_envelop_error_result` metric to the configuration.

packages/plugins/prometheus/src/config.ts

@@ -2,26 +2,220 @@ import { Registry } from 'prom-client';
 import { createCounter, createHistogram, createSummary } from './utils.js';
 
 export type PrometheusTracingPluginConfig = {
-  requestCount?: boolean | string | ReturnType<typeof createCounter>;
-  requestTotalDuration?: boolean | string | ReturnType<typeof createHistogram>;
-  requestSummary?: boolean | string | ReturnType<typeof createSummary>;
-  parse?: boolean | string | ReturnType<typeof createHistogram>;
-  validate?: boolean | string | ReturnType<typeof createHistogram>;
-  contextBuilding?: boolean | string | ReturnType<typeof createHistogram>;
-  execute?: boolean | string | ReturnType<typeof createHistogram>;
-  subscribe?: boolean | string | ReturnType<typeof createHistogram>;
-  errors?: boolean | string | ReturnType<typeof createCounter>;
-  resolvers?: boolean | string | ReturnType<typeof createHistogram>;
-  resolversWhitelist?: string[];
-  deprecatedFields?: boolean | string | ReturnType<typeof createCounter>;
+  /**
+   * The `prom-client` registry to use. If not provided, the default global registry will be used.
+   */
   registry?: Registry;
+
+  /**
+   * Ignore introspection queries when collecting metrics.
+   *
+   * @default false
+   */
   skipIntrospection?: boolean;
-  schemaChangeCount?: boolean | string | ReturnType<typeof createCounter>;
-  labels?: {
-    operationName?: boolean;
-    operationType?: boolean;
-    fieldName?: boolean;
-    typeName?: boolean;
-    returnType?: boolean;
-  };
+
+  /**
+   * Only applicable when `metrics.graphql_envelop_execute_resolver` is enabled.
+   *
+   * Allows to whitelist resolvers to collect metrics for. It is highly recommended to provide this
+   * option to avoid metrics explosion and performance degradation.
+   */
+  resolversWhitelist?: string[];
+
+  /**
+   * Metrics configuration.
+   *
+   * By default, all metrics are disabled. You can enable them by setting the corresponding field to `true`.
+   *
+   * An object can also be passed to configure the metric.
+   * Please use the factories `createCounter`, `createHistogram` and `createSummary`
+   * to create those metric configuration objects.
+   */
+  metrics: MetricsConfig;
+
+  /**
+   * All labels attached to metrics can be disabled. This can help you reduce the size of the exported metrics
+   *
+   * By default, all labels are enabled, but all labels are not available for all metrics.
+   * See the documentation for each metric to see which labels are available.
+   */
+  labels?: LabelsConfig;
+};
+
+export type MetricsConfig = {
+  /**
+   * Tracks the number of GraphQL operations executed.
+   * It counts all operations, either failed or successful, including subscriptions.
+   * It is exposed as a counter.
+   */
+  graphql_envelop_request?: boolean | string | ReturnType<typeof createCounter>;
+
+  /**
+   * Tracks the duration of the complete GraphQL operation execution.
+   * It is reported as a histogram.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_request_duration?:
+    | boolean
+    | string
+    | number[]
+    | ReturnType<typeof createHistogram>;
+  /**
+   * Provides a summary of the time spent on the GraphQL operation execution.
+   * It reports the same timing than graphql_envelop_request_duration but as a summary.
+   */
+  graphql_envelop_request_time_summary?: boolean | string | ReturnType<typeof createSummary>;
+  /**
+   * Tracks the duration of the parse phase of the GraphQL execution.
+   * It reports the time spent parsing the incoming GraphQL operation.
+   * It is reported as a histogram.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_phase_parse?: boolean | string | number[] | ReturnType<typeof createHistogram>;
+  /**
+   * Tracks the duration of the validate phase of the GraphQL execution.
+   * It reports the time spent validating the incoming GraphQL operation.
+   * It is reported as a histogram.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_phase_validate?: boolean | string | number[] | ReturnType<typeof createHistogram>;
+  /**
+   * Tracks the duration of the context phase of the GraphQL execution.
+   * It reports the time spent building the context object that will be passed to the executors.
+   * It is reported as a histogram.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_phase_context?: boolean | string | number[] | ReturnType<typeof createHistogram>;
+  /**
+   * Tracks the duration of the execute phase of the GraphQL execution.
+   * It reports the time spent actually resolving the response of the incoming operation.
+   * This includes the gathering of all the data from all sources required to construct the final response.
+   * It is reported as a histogram.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_phase_execute?: boolean | string | number[] | ReturnType<typeof createHistogram>;
+  /**
+   * This metric tracks the duration of the subscribe phase of the GraphQL execution.
+   * It reports the time spent initiating a subscription (which doesn’t include actually sending the first response).
+   * It is reported as a histogram.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_phase_subscribe?:
+    | boolean
+    | string
+    | number[]
+    | ReturnType<typeof createHistogram>;
+  /**
+   * This metric tracks the number of errors that returned by the GraphQL execution.
+   * It counts all errors found in response, but it also includes errors from other GraphQL
+   * processing phases (parsing, validation and context building).
+   * It is exposed as a counter.
+   */
+  graphql_envelop_error_result?: boolean | string | ReturnType<typeof createCounter>;
+  /**
+   * This metric tracks the number of deprecated fields used in the GraphQL operation.
+   * It is exposed as a counter.
+   */
+  graphql_envelop_deprecated_field?: boolean | string | ReturnType<typeof createCounter>;
+  /**
+   * This metric tracks the number of schema changes that have occurred since the gateway started.
+   * If you are using a plugin that modifies the schema on the fly,
+   * be aware that this metric will also include updates made by those plugins.
+   * Which means that one schema update can actually trigger multiple schema changes.
+   * It is exposed as a counter.
+   */
+  graphql_envelop_schema_change?: boolean | string | ReturnType<typeof createCounter>;
+  /**
+   * This metric tracks the duration of each resolver execution.
+   *
+   * It is highly recommended to enable this metric for debugging purposes only,
+   * since it can have a significant performance impact.
+   * You can use the `resolversWhitelist` option to limit metrics explosion and performance degradation.
+   *
+   * You can pass multiple type of values:
+   *  - boolean: Disable or Enable the metric with default configuration
+   *  - string: Enable the metric with custom name
+   *  - number[]: Enable the metric with custom buckets
+   *  - ReturnType<typeof createHistogram>: Enable the metric with custom configuration
+   */
+  graphql_envelop_execute_resolver?:
+    | boolean
+    | string
+    | number[]
+    | ReturnType<typeof createHistogram>;
+};
+
+export type LabelsConfig = {
+  /**
+   * The currently executing operation name.
+   *
+   * If no operation name is provided, this will be set to 'Anonymous'
+   *
+   * @default true
+   */
+  operationName?: boolean;
+  /**
+   * The currently executing operation type.
+   *
+   * @default true
+   */
+  operationType?: boolean;
+
+  /**
+   * The resolved field name.
+   *
+   * @default true
+   */
+  fieldName?: boolean;
+  /**
+   * The resolved field parent type name.
+   *
+   * @default true
+   */
+  typeName?: boolean;
+  /**
+   * The resolved field type name. This is only available for the `graphql_envelop_execute_resolver` metric.
+   *
+   * @default true
+   */
+  returnType?: boolean;
+
+  /**
+   * The path of the field from which originated the error. Only available for the `graphql_envelop_error_result` metric.
+   */
+  path?: boolean;
+  /**
+   * The execution phase where the error occurred. Only available for the `graphql_envelop_error_result` metric.
+   */
+  phase?: boolean;
 };