Improvements for opentelemetry plugin (#2201)

Author: dotansimha

.changeset/early-books-jam.md

@@ -0,0 +1,5 @@
+---
+'@envelop/opentelemetry': minor
+---
+
+feat: exclude operations by using list of names or a custom function

.changeset/tall-avocados-collect.md

@@ -0,0 +1,5 @@
+---
+'@envelop/opentelemetry': minor
+---
+
+feat: allow to use a custom function to resolve/sanitize variables

packages/plugins/opentelemetry/README.md

@@ -35,8 +35,53 @@ const getEnveloped = envelop({
 })
 ```
 
-If you wish to use custom tracer/exporter, create it and pass it. This example integrates Jaeger
-tracer:
+## Integration with `@opentelemetry` packages
+
+By default, this plugin is creating a console exporter for exporting the `Span`s.
+
+If you wish to use custom tracer/exporter, create it and pass it to the plugin factory function.
+
+The following example is taking the current global tracer:
+
+```ts
+import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
+import { envelop, useEngine } from '@envelop/core'
+import { useOpenTelemetry } from '@envelop/opentelemetry'
+import { trace } from '@opentelemetry/api'
+import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
+
+const getEnveloped = envelop({
+  plugins: [
+    useEngine({ parse, validate, specifiedRules, execute, subscribe }),
+    // ... other plugins ...
+    useOpenTelemetry(
+      {
+        resolvers: true, // Tracks resolvers calls, and tracks resolvers thrown errors
+        variables: true, // Includes the operation variables values as part of the metadata collected
+        result: true // Includes execution result object as part of the metadata collected
+      },
+      trace.getTracerProvider()
+    )
+  ]
+})
+```
+
+This example integrates Jaeger tracer. To use this example, start by running Jaeger locally in a
+Docker container (or, follow
+[other options to run Jaeger locally](https://www.npmjs.com/package/@opentelemetry/exporter-jaeger#prerequisites)):
+
+```
+docker run -d --name jaeger \
+  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
+  -p 5775:5775/udp \
+  -p 6831:6831/udp \
+  -p 6832:6832/udp \
+  -p 5778:5778 \
+  -p 16686:16686 \
+  -p 14268:14268 \
+  -p 9411:9411 \
+  jaegertracing/all-in-one:latest
+```
 
 ```ts
 import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
@@ -45,10 +90,14 @@ import { useOpenTelemetry } from '@envelop/opentelemetry'
 import { JaegerExporter } from '@opentelemetry/exporter-jaeger'
 import { BasicTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
 
+// Create your exporter
 const exporter = new JaegerExporter({
-  serviceName: 'my-service-name'
+  serviceName: 'my-service-name',
+  host: 'localhost',
+  port: 6832
 })
 
+// Configure opentelmetry to run for your service
 const provider = new BasicTracerProvider()
 provider.addSpanProcessor(new SimpleSpanProcessor(exporter))
 provider.register()

packages/plugins/opentelemetry/src/index.ts

@@ -32,12 +32,16 @@ export enum AttributeName {
 
 const tracingSpanSymbol = Symbol('OPEN_TELEMETRY_GRAPHQL');
 
+export type ResolveVariablesAttributesFn = (variableValues: any) => opentelemetry.AttributeValue;
+export type ExcludeOperationNamesFn = (operationName: string | undefined) => boolean;
+
 export type TracingOptions = {
   document?: boolean;
   resolvers?: boolean;
-  variables?: boolean;
+  variables?: boolean | ResolveVariablesAttributesFn;
   result?: boolean;
   traceIdInResult?: string;
+  excludedOperationNames?: string[] | ExcludeOperationNamesFn;
 };
 
 type PluginContext = {
@@ -131,6 +135,16 @@ export const useOpenTelemetry = (
       if (!operationAst) {
         return;
       }
+
+      if (
+        options.excludedOperationNames &&
+        (typeof options.excludedOperationNames === 'function'
+          ? options.excludedOperationNames(operationAst.name?.value)
+          : options.excludedOperationNames.includes(operationAst.name?.value || ''))
+      ) {
+        return;
+      }
+
       const operationType = operationAst.operation;
       let isDocumentLoggable: boolean;
       if (options.document == null || options.document === true) {
@@ -146,6 +160,15 @@ export const useOpenTelemetry = (
       }
       const operationName = operationAst.name?.value || 'anonymous';
       const currOtelContext = getCurrentOtelContext(args.contextValue);
+
+      const variablesAttribute = options.variables
+        ? {
+            [AttributeName.EXECUTION_VARIABLES]:
+              typeof options.variables === 'function'
+                ? options.variables(args.variableValues)
+                : JSON.stringify(args.variableValues ?? {}),
+          }
+        : {};
       const executionSpan = tracer.startSpan(
         `${spanPrefix}${operationType}.${operationName}`,
         {
@@ -157,9 +180,7 @@ export const useOpenTelemetry = (
             [AttributeName.EXECUTION_OPERATION_DOCUMENT]: isDocumentLoggable
               ? getDocumentString(args.document, print)
               : undefined,
-            ...(options.variables
-              ? { [AttributeName.EXECUTION_VARIABLES]: JSON.stringify(args.variableValues ?? {}) }
-              : {}),
+            ...variablesAttribute,
           },
         },
         currOtelContext,
@@ -216,6 +237,16 @@ export const useOpenTelemetry = (
       if (!operationAst) {
         return;
       }
+
+      if (
+        options.excludedOperationNames &&
+        (typeof options.excludedOperationNames === 'function'
+          ? options.excludedOperationNames(operationAst.name?.value)
+          : options.excludedOperationNames.includes(operationAst.name?.value || ''))
+      ) {
+        return;
+      }
+
       const operationType = 'subscription';
       let isDocumentLoggable: boolean;
       if (options.variables) {
@@ -227,6 +258,15 @@ export const useOpenTelemetry = (
       }
       const currOtelContext = getCurrentOtelContext(args.contextValue);
       const operationName = operationAst.name?.value || 'anonymous';
+      const variablesAttribute = options.variables
+        ? {
+            [AttributeName.EXECUTION_VARIABLES]:
+              typeof options.variables === 'function'
+                ? options.variables(args.variableValues)
+                : JSON.stringify(args.variableValues ?? {}),
+          }
+        : {};
+
       const subscriptionSpan = tracer.startSpan(
         `${operationType}.${operationName}`,
         {
@@ -238,9 +278,7 @@ export const useOpenTelemetry = (
             [AttributeName.EXECUTION_OPERATION_DOCUMENT]: isDocumentLoggable
               ? getDocumentString(args.document, print)
               : undefined,
-            ...(options.variables
-              ? { [AttributeName.EXECUTION_VARIABLES]: JSON.stringify(args.variableValues ?? {}) }
-              : {}),
+            ...variablesAttribute,
           },
         },
         currOtelContext,

packages/plugins/opentelemetry/test/use-open-telemetry.spec.ts

@@ -156,6 +156,66 @@ describe('useOpenTelemetry', () => {
     expect(actual[0].name).toBe('query.ping');
   });
 
+  it('can exclude operation by using list of strings', async () => {
+    const exporter = new InMemorySpanExporter();
+    const testInstance = createTestkit(
+      [
+        useTestOpenTelemetry(exporter, {
+          excludedOperationNames: ['ping'],
+        }),
+      ],
+      schema,
+    );
+
+    await testInstance.execute(/* GraphQL */ `
+      query ping {
+        ping
+      }
+    `);
+    const actual = exporter.getFinishedSpans();
+    expect(actual.length).toBe(0);
+  });
+
+  it('can exclude anonymous operations with fn', async () => {
+    const exporter = new InMemorySpanExporter();
+    const testInstance = createTestkit(
+      [
+        useTestOpenTelemetry(exporter, {
+          excludedOperationNames: name => name === undefined,
+        }),
+      ],
+      schema,
+    );
+
+    await testInstance.execute(/* GraphQL */ `
+      query {
+        ping
+      }
+    `);
+    const actual = exporter.getFinishedSpans();
+    expect(actual.length).toBe(0);
+  });
+
+  it('can exclude anonymous operations with fn', async () => {
+    const exporter = new InMemorySpanExporter();
+    const testInstance = createTestkit(
+      [
+        useTestOpenTelemetry(exporter, {
+          excludedOperationNames: name => name !== undefined && name.startsWith('pi'),
+        }),
+      ],
+      schema,
+    );
+
+    await testInstance.execute(/* GraphQL */ `
+      query ping {
+        ping
+      }
+    `);
+    const actual = exporter.getFinishedSpans();
+    expect(actual.length).toBe(0);
+  });
+
   it('execute span should add attributes', async () => {
     const exporter = new InMemorySpanExporter();
     const testInstance = createTestkit([useTestOpenTelemetry(exporter)], schema);
@@ -208,6 +268,57 @@ describe('useOpenTelemetry', () => {
     });
   });
 
+  it('custom variables attributes with fn', async () => {
+    const exporter = new InMemorySpanExporter();
+    const testInstance = createTestkit(
+      [
+        useTestOpenTelemetry(exporter, {
+          variables: v => {
+            if (v && typeof v === 'object' && 'selector' in v) {
+              return JSON.stringify(v.selector);
+            }
+
+            return '';
+          },
+        }),
+      ],
+      schema,
+    );
+
+    const queryStr = /* GraphQL */ `
+      query echo($testVar: String!, $testVar2: String!, $selector: String!) {
+        echo1: echo(message: $testVar)
+        echo2: echo(message: $testVar2)
+        echo3: echo(message: $selector)
+      }
+    `;
+
+    const resp = await testInstance.execute(queryStr, {
+      testVar: 'hello',
+      testVar2: 'world',
+      selector: '1',
+    });
+
+    console.log(resp);
+
+    assertSingleValue(resp);
+
+    const actual = exporter.getFinishedSpans();
+    expect(actual.length).toBe(1);
+    expect(actual[0].attributes).toEqual({
+      [AttributeName.EXECUTION_OPERATION_DOCUMENT]: `
+      query echo($testVar: String!, $testVar2: String!, $selector: String!) {
+        echo1: echo(message: $testVar)
+        echo2: echo(message: $testVar2)
+        echo3: echo(message: $selector)
+      }
+    `,
+      [AttributeName.EXECUTION_OPERATION_NAME]: 'echo',
+      [AttributeName.EXECUTION_OPERATION_TYPE]: 'query',
+      [AttributeName.EXECUTION_VARIABLES]: '"1"',
+    });
+  });
+
   it('span should not add document attribute if options false', async () => {
     const exporter = new InMemorySpanExporter();
     const testInstance = createTestkit(