@envelop/opentelemetry 6.2.1 → 6.3.0-alpha-20240402093155-a99b4960

package/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()

package/cjs/index.js

@@ -88,6 +88,14 @@ const useOpenTelemetry = (options, tracingProvider, spanKind = api_1.SpanKind.SE
             if (!operationAst) {
                 return;
             }
+            const shouldReport = options.excludedOperationNames
+                ? typeof options.excludedOperationNames === 'function'
+                    ? !options.excludedOperationNames(operationAst.name?.value)
+                    : !options.excludedOperationNames.includes(operationAst.name?.value || '')
+                : true;
+            if (!shouldReport) {
+                return;
+            }
             const operationType = operationAst.operation;
             let isDocumentLoggable;
             if (options.document == null || options.document === true) {
@@ -106,6 +114,13 @@ const useOpenTelemetry = (options, tracingProvider, spanKind = api_1.SpanKind.SE
             }
             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}`, {
                 kind: spanKind,
                 attributes: {
@@ -115,9 +130,7 @@ const useOpenTelemetry = (options, tracingProvider, spanKind = api_1.SpanKind.SE
                     [AttributeName.EXECUTION_OPERATION_DOCUMENT]: isDocumentLoggable
                         ? (0, core_1.getDocumentString)(args.document, graphql_1.print)
                         : undefined,
-                    ...(options.variables
-                        ? { [AttributeName.EXECUTION_VARIABLES]: JSON.stringify(args.variableValues ?? {}) }
-                        : {}),
+                    ...variablesAttribute,
                 },
             }, currOtelContext);
             setCurrentOtelContext(args.contextValue, opentelemetry.trace.setSpan(currOtelContext, executionSpan));
@@ -162,6 +175,14 @@ const useOpenTelemetry = (options, tracingProvider, spanKind = api_1.SpanKind.SE
             if (!operationAst) {
                 return;
             }
+            const shouldReport = options.excludedOperationNames
+                ? typeof options.excludedOperationNames === 'function'
+                    ? !options.excludedOperationNames(operationAst.name?.value)
+                    : !options.excludedOperationNames.includes(operationAst.name?.value || '')
+                : true;
+            if (!shouldReport) {
+                return;
+            }
             const operationType = 'subscription';
             let isDocumentLoggable;
             if (options.variables) {
@@ -175,6 +196,13 @@ const useOpenTelemetry = (options, tracingProvider, spanKind = api_1.SpanKind.SE
             }
             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}`, {
                 kind: spanKind,
                 attributes: {
@@ -184,9 +212,7 @@ const useOpenTelemetry = (options, tracingProvider, spanKind = api_1.SpanKind.SE
                     [AttributeName.EXECUTION_OPERATION_DOCUMENT]: isDocumentLoggable
                         ? (0, core_1.getDocumentString)(args.document, graphql_1.print)
                         : undefined,
-                    ...(options.variables
-                        ? { [AttributeName.EXECUTION_VARIABLES]: JSON.stringify(args.variableValues ?? {}) }
-                        : {}),
+                    ...variablesAttribute,
                 },
             }, currOtelContext);
             setCurrentOtelContext(args.contextValue, opentelemetry.trace.setSpan(currOtelContext, subscriptionSpan));

package/esm/index.js

@@ -82,6 +82,14 @@ export const useOpenTelemetry = (options, tracingProvider, spanKind = SpanKind.S
             if (!operationAst) {
                 return;
             }
+            const shouldReport = options.excludedOperationNames
+                ? typeof options.excludedOperationNames === 'function'
+                    ? !options.excludedOperationNames(operationAst.name?.value)
+                    : !options.excludedOperationNames.includes(operationAst.name?.value || '')
+                : true;
+            if (!shouldReport) {
+                return;
+            }
             const operationType = operationAst.operation;
             let isDocumentLoggable;
             if (options.document == null || options.document === true) {
@@ -100,6 +108,13 @@ export const useOpenTelemetry = (options, tracingProvider, spanKind = SpanKind.S
             }
             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}`, {
                 kind: spanKind,
                 attributes: {
@@ -109,9 +124,7 @@ export const useOpenTelemetry = (options, tracingProvider, spanKind = SpanKind.S
                     [AttributeName.EXECUTION_OPERATION_DOCUMENT]: isDocumentLoggable
                         ? getDocumentString(args.document, print)
                         : undefined,
-                    ...(options.variables
-                        ? { [AttributeName.EXECUTION_VARIABLES]: JSON.stringify(args.variableValues ?? {}) }
-                        : {}),
+                    ...variablesAttribute,
                 },
             }, currOtelContext);
             setCurrentOtelContext(args.contextValue, opentelemetry.trace.setSpan(currOtelContext, executionSpan));
@@ -156,6 +169,14 @@ export const useOpenTelemetry = (options, tracingProvider, spanKind = SpanKind.S
             if (!operationAst) {
                 return;
             }
+            const shouldReport = options.excludedOperationNames
+                ? typeof options.excludedOperationNames === 'function'
+                    ? !options.excludedOperationNames(operationAst.name?.value)
+                    : !options.excludedOperationNames.includes(operationAst.name?.value || '')
+                : true;
+            if (!shouldReport) {
+                return;
+            }
             const operationType = 'subscription';
             let isDocumentLoggable;
             if (options.variables) {
@@ -169,6 +190,13 @@ export const useOpenTelemetry = (options, tracingProvider, spanKind = SpanKind.S
             }
             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}`, {
                 kind: spanKind,
                 attributes: {
@@ -178,9 +206,7 @@ export const useOpenTelemetry = (options, tracingProvider, spanKind = SpanKind.S
                     [AttributeName.EXECUTION_OPERATION_DOCUMENT]: isDocumentLoggable
                         ? getDocumentString(args.document, print)
                         : undefined,
-                    ...(options.variables
-                        ? { [AttributeName.EXECUTION_VARIABLES]: JSON.stringify(args.variableValues ?? {}) }
-                        : {}),
+                    ...variablesAttribute,
                 },
             }, currOtelContext);
             setCurrentOtelContext(args.contextValue, opentelemetry.trace.setSpan(currOtelContext, subscriptionSpan));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envelop/opentelemetry",
-  "version": "6.2.1",
+  "version": "6.3.0-alpha-20240402093155-a99b4960",
   "sideEffects": false,
   "peerDependencies": {
     "@envelop/core": "^5.0.0",

package/typings/index.d.cts

@@ -15,12 +15,15 @@ export declare enum AttributeName {
     EXECUTION_VARIABLES = "graphql.execute.variables"
 }
 declare const tracingSpanSymbol: unique symbol;
+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 = {
     [tracingSpanSymbol]: opentelemetry.Span;

package/typings/index.d.ts

@@ -15,12 +15,15 @@ export declare enum AttributeName {
     EXECUTION_VARIABLES = "graphql.execute.variables"
 }
 declare const tracingSpanSymbol: unique symbol;
+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 = {
     [tracingSpanSymbol]: opentelemetry.Span;