@effect-gql/opentelemetry 0.1.0

package/src/tracing-extension.ts

@@ -0,0 +1,175 @@
+import { Effect, Option } from "effect"
+import type { DocumentNode, ExecutionResult, GraphQLError, OperationDefinitionNode } from "graphql"
+import type { GraphQLExtension, ExecutionArgs } from "@effect-gql/core"
+import { ExtensionsService } from "@effect-gql/core"
+
+/**
+ * Configuration for the GraphQL tracing extension
+ */
+export interface TracingExtensionConfig {
+  /**
+   * Include the query source in span attributes.
+   * Default: false (for security - queries may contain sensitive data)
+   */
+  readonly includeQuery?: boolean
+
+  /**
+   * Include variables in span attributes.
+   * Default: false (for security - variables may contain sensitive data)
+   */
+  readonly includeVariables?: boolean
+
+  /**
+   * Add trace ID and span ID to the GraphQL response extensions.
+   * Useful for correlating client requests with backend traces.
+   * Default: false
+   */
+  readonly exposeTraceIdInResponse?: boolean
+
+  /**
+   * Custom attributes to add to all spans.
+   */
+  readonly customAttributes?: Record<string, string | number | boolean>
+}
+
+/**
+ * Extract the operation name from a parsed GraphQL document
+ */
+const getOperationName = (document: DocumentNode): string | undefined => {
+  for (const definition of document.definitions) {
+    if (definition.kind === "OperationDefinition") {
+      return definition.name?.value
+    }
+  }
+  return undefined
+}
+
+/**
+ * Extract the operation type (query, mutation, subscription) from a parsed document
+ */
+const getOperationType = (document: DocumentNode): string => {
+  for (const definition of document.definitions) {
+    if (definition.kind === "OperationDefinition") {
+      return (definition as OperationDefinitionNode).operation
+    }
+  }
+  return "unknown"
+}
+
+/**
+ * Creates a GraphQL extension that adds OpenTelemetry tracing to all execution phases.
+ *
+ * This extension:
+ * - Creates spans for parse, validate phases
+ * - Annotates the current span with operation metadata during execution
+ * - Optionally exposes trace ID in response extensions
+ *
+ * Requires an OpenTelemetry tracer to be provided via Effect's tracing layer
+ * (e.g., `@effect/opentelemetry` NodeSdk.layer or OtlpTracer.layer).
+ *
+ * @example
+ * ```typescript
+ * import { tracingExtension } from "@effect-gql/opentelemetry"
+ *
+ * const builder = GraphQLSchemaBuilder.empty.pipe(
+ *   extension(tracingExtension({
+ *     exposeTraceIdInResponse: true
+ *   })),
+ *   query("hello", { ... })
+ * )
+ * ```
+ */
+export const tracingExtension = (
+  config?: TracingExtensionConfig
+): GraphQLExtension<ExtensionsService> => ({
+  name: "opentelemetry-tracing",
+  description: "Adds OpenTelemetry tracing to GraphQL execution phases",
+
+  onParse: (source: string, document: DocumentNode) =>
+    Effect.withSpan("graphql.parse")(
+      Effect.gen(function* () {
+        const operationName = getOperationName(document) ?? "anonymous"
+        yield* Effect.annotateCurrentSpan("graphql.document.name", operationName)
+        yield* Effect.annotateCurrentSpan(
+          "graphql.document.operation_count",
+          document.definitions.filter((d) => d.kind === "OperationDefinition").length
+        )
+
+        if (config?.includeQuery) {
+          yield* Effect.annotateCurrentSpan("graphql.source", source)
+        }
+
+        // Add custom attributes if provided
+        if (config?.customAttributes) {
+          for (const [key, value] of Object.entries(config.customAttributes)) {
+            yield* Effect.annotateCurrentSpan(key, value)
+          }
+        }
+      })
+    ),
+
+  onValidate: (document: DocumentNode, errors: readonly GraphQLError[]) =>
+    Effect.withSpan("graphql.validate")(
+      Effect.gen(function* () {
+        yield* Effect.annotateCurrentSpan("graphql.validation.error_count", errors.length)
+
+        if (errors.length > 0) {
+          yield* Effect.annotateCurrentSpan(
+            "graphql.validation.errors",
+            JSON.stringify(errors.map((e) => e.message))
+          )
+          yield* Effect.annotateCurrentSpan("error", true)
+        }
+      })
+    ),
+
+  onExecuteStart: (args: ExecutionArgs) =>
+    Effect.gen(function* () {
+      const operationName = args.operationName ?? getOperationName(args.document) ?? "anonymous"
+      const operationType = getOperationType(args.document)
+
+      yield* Effect.annotateCurrentSpan("graphql.operation.name", operationName)
+      yield* Effect.annotateCurrentSpan("graphql.operation.type", operationType)
+
+      if (config?.includeVariables && args.variableValues) {
+        yield* Effect.annotateCurrentSpan("graphql.variables", JSON.stringify(args.variableValues))
+      }
+
+      // Expose trace ID in response extensions if configured
+      if (config?.exposeTraceIdInResponse) {
+        const currentSpanOption = yield* Effect.option(Effect.currentSpan)
+        if (Option.isSome(currentSpanOption)) {
+          const span = currentSpanOption.value
+          const ext = yield* ExtensionsService
+          yield* ext.set("tracing", {
+            traceId: span.traceId,
+            spanId: span.spanId,
+          })
+        }
+      }
+    }),
+
+  onExecuteEnd: (result: ExecutionResult) =>
+    Effect.gen(function* () {
+      const hasErrors = result.errors !== undefined && result.errors.length > 0
+
+      yield* Effect.annotateCurrentSpan("graphql.response.has_errors", hasErrors)
+      yield* Effect.annotateCurrentSpan(
+        "graphql.response.has_data",
+        result.data !== null && result.data !== undefined
+      )
+
+      if (hasErrors) {
+        yield* Effect.annotateCurrentSpan("error", true)
+        yield* Effect.annotateCurrentSpan(
+          "graphql.errors",
+          JSON.stringify(
+            result.errors!.map((e) => ({
+              message: e.message,
+              path: e.path,
+            }))
+          )
+        )
+      }
+    }),
+})

package/src/tracing-middleware.ts

@@ -0,0 +1,177 @@
+import { Effect } from "effect"
+import type { GraphQLResolveInfo } from "graphql"
+import type { MiddlewareRegistration, MiddlewareContext } from "@effect-gql/core"
+import { pathToString, getFieldDepth, isIntrospectionField } from "./utils"
+
+/**
+ * Configuration for resolver tracing middleware
+ */
+export interface ResolverTracingConfig {
+  /**
+   * Minimum field depth to trace.
+   * Depth 0 = root fields (Query.*, Mutation.*).
+   * Default: 0 (trace all fields)
+   */
+  readonly minDepth?: number
+
+  /**
+   * Maximum field depth to trace.
+   * Default: Infinity (no limit)
+   */
+  readonly maxDepth?: number
+
+  /**
+   * Field patterns to exclude from tracing.
+   * Patterns are matched against "TypeName.fieldName".
+   *
+   * @example
+   * // Exclude introspection and internal fields
+   * excludePatterns: [/^Query\.__/, /\.id$/]
+   */
+  readonly excludePatterns?: readonly RegExp[]
+
+  /**
+   * Whether to include field arguments in span attributes.
+   * Default: false (for security - args may contain sensitive data)
+   */
+  readonly includeArgs?: boolean
+
+  /**
+   * Whether to include parent type in span attributes.
+   * Default: true
+   */
+  readonly includeParentType?: boolean
+
+  /**
+   * Whether to trace introspection fields (__schema, __type, etc.).
+   * Default: false
+   */
+  readonly traceIntrospection?: boolean
+
+  /**
+   * Custom span name generator.
+   * Default: "graphql.resolve TypeName.fieldName"
+   */
+  readonly spanNameGenerator?: (info: GraphQLResolveInfo) => string
+}
+
+/**
+ * Check if a field should be traced based on configuration
+ */
+const shouldTraceField = (info: GraphQLResolveInfo, config?: ResolverTracingConfig): boolean => {
+  // Skip introspection fields unless explicitly enabled
+  if (!config?.traceIntrospection && isIntrospectionField(info)) {
+    return false
+  }
+
+  const depth = getFieldDepth(info)
+
+  // Check depth bounds
+  if (config?.minDepth !== undefined && depth < config.minDepth) {
+    return false
+  }
+  if (config?.maxDepth !== undefined && depth > config.maxDepth) {
+    return false
+  }
+
+  // Check exclude patterns
+  if (config?.excludePatterns) {
+    const fieldPath = `${info.parentType.name}.${info.fieldName}`
+    for (const pattern of config.excludePatterns) {
+      if (pattern.test(fieldPath)) {
+        return false
+      }
+    }
+  }
+
+  return true
+}
+
+/**
+ * Creates middleware that wraps each resolver in an OpenTelemetry span.
+ *
+ * Each resolver execution creates a child span with GraphQL-specific attributes:
+ * - `graphql.field.name`: The field being resolved
+ * - `graphql.field.path`: Full path to the field (e.g., "Query.users.0.posts")
+ * - `graphql.field.type`: The return type of the field
+ * - `graphql.parent.type`: The parent type name
+ * - `graphql.operation.name`: The operation name (if available)
+ * - `error`: Set to true if the resolver fails
+ * - `error.type`: Error type/class name
+ * - `error.message`: Error message
+ *
+ * Requires an OpenTelemetry tracer to be provided via Effect's tracing layer.
+ *
+ * @example
+ * ```typescript
+ * import { resolverTracingMiddleware } from "@effect-gql/opentelemetry"
+ *
+ * const builder = GraphQLSchemaBuilder.empty.pipe(
+ *   middleware(resolverTracingMiddleware({
+ *     minDepth: 0,
+ *     excludePatterns: [/^Query\.__/],
+ *     includeArgs: false
+ *   })),
+ *   query("users", { ... })
+ * )
+ * ```
+ */
+export const resolverTracingMiddleware = (
+  config?: ResolverTracingConfig
+): MiddlewareRegistration<never> => ({
+  name: "opentelemetry-resolver-tracing",
+  description: "Wraps resolvers in OpenTelemetry spans",
+
+  match: (info: GraphQLResolveInfo) => shouldTraceField(info, config),
+
+  apply: <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+    context: MiddlewareContext
+  ): Effect.Effect<A, E, R> => {
+    const { info } = context
+
+    const spanName = config?.spanNameGenerator
+      ? config.spanNameGenerator(info)
+      : `graphql.resolve ${info.parentType.name}.${info.fieldName}`
+
+    return Effect.withSpan(spanName)(
+      Effect.gen(function* () {
+        // Add standard attributes
+        yield* Effect.annotateCurrentSpan("graphql.field.name", info.fieldName)
+        yield* Effect.annotateCurrentSpan("graphql.field.path", pathToString(info.path))
+        yield* Effect.annotateCurrentSpan("graphql.field.type", String(info.returnType))
+
+        if (config?.includeParentType !== false) {
+          yield* Effect.annotateCurrentSpan("graphql.parent.type", info.parentType.name)
+        }
+
+        if (info.operation?.name?.value) {
+          yield* Effect.annotateCurrentSpan("graphql.operation.name", info.operation.name.value)
+        }
+
+        if (config?.includeArgs && context.args && Object.keys(context.args).length > 0) {
+          yield* Effect.annotateCurrentSpan("graphql.field.args", JSON.stringify(context.args))
+        }
+
+        // Execute resolver and handle errors
+        const result = yield* effect.pipe(
+          Effect.tapError((error) =>
+            Effect.gen(function* () {
+              yield* Effect.annotateCurrentSpan("error", true)
+              yield* Effect.annotateCurrentSpan(
+                "error.type",
+                error instanceof Error ? error.constructor.name : "Error"
+              )
+              yield* Effect.annotateCurrentSpan(
+                "error.message",
+                error instanceof Error ? error.message : String(error)
+              )
+            })
+          )
+        )
+
+        return result
+      })
+    ) as Effect.Effect<A, E, R>
+  },
+})

package/src/utils.ts

@@ -0,0 +1,48 @@
+import type { GraphQLResolveInfo, ResponsePath } from "graphql"
+
+/**
+ * Convert a GraphQL response path to a string representation.
+ *
+ * @example
+ * // For path: Query -> users -> 0 -> posts -> 1 -> title
+ * // Returns: "Query.users.0.posts.1.title"
+ */
+export const pathToString = (path: ResponsePath | undefined): string => {
+  if (!path) return ""
+
+  const segments: (string | number)[] = []
+  let current: ResponsePath | undefined = path
+
+  while (current) {
+    segments.unshift(current.key)
+    current = current.prev
+  }
+
+  return segments.join(".")
+}
+
+/**
+ * Get the depth of a field in the query tree.
+ * Root fields (Query.*, Mutation.*) have depth 0.
+ */
+export const getFieldDepth = (info: GraphQLResolveInfo): number => {
+  let depth = 0
+  let current: ResponsePath | undefined = info.path
+
+  while (current?.prev) {
+    // Skip array indices in depth calculation
+    if (typeof current.key === "string") {
+      depth++
+    }
+    current = current.prev
+  }
+
+  return depth
+}
+
+/**
+ * Check if a field is an introspection field (__schema, __type, etc.)
+ */
+export const isIntrospectionField = (info: GraphQLResolveInfo): boolean => {
+  return info.fieldName.startsWith("__")
+}