@effect-gql/opentelemetry 0.1.0 → 1.0.0

package/src/index.ts

@@ -1,139 +0,0 @@
-/**
- * @effect-gql/opentelemetry
- *
- * OpenTelemetry tracing integration for Effect GraphQL.
- *
- * Provides distributed tracing using Effect's native OpenTelemetry support.
- * Works with any OpenTelemetry-compatible backend (Jaeger, Tempo, Honeycomb, etc.).
- *
- * @example
- * ```typescript
- * import { GraphQLSchemaBuilder } from "@effect-gql/core"
- * import { serve } from "@effect-gql/node"
- * import { withTracing } from "@effect-gql/opentelemetry"
- * import { NodeSdk } from "@effect/opentelemetry"
- * import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"
- * import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"
- *
- * // Add tracing to schema
- * const builder = GraphQLSchemaBuilder.empty
- *   .query("users", { ... })
- *   .pipe(withTracing({
- *     extension: { exposeTraceIdInResponse: true },
- *     resolver: { excludePatterns: [/^Query\.__/] }
- *   }))
- *
- * // Configure OpenTelemetry
- * const TracingLayer = NodeSdk.layer(() => ({
- *   resource: { serviceName: "my-graphql-api" },
- *   spanProcessor: new BatchSpanProcessor(
- *     new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" })
- *   )
- * }))
- *
- * // Serve with tracing
- * serve(builder, TracingLayer.pipe(Layer.merge(serviceLayer)))
- * ```
- *
- * @packageDocumentation
- */
-
-import type { GraphQLSchemaBuilder } from "@effect-gql/core"
-import { tracingExtension, type TracingExtensionConfig } from "./tracing-extension"
-import { resolverTracingMiddleware, type ResolverTracingConfig } from "./tracing-middleware"
-
-/**
- * Complete configuration for GraphQL tracing
- */
-export interface GraphQLTracingConfig {
-  /**
-   * Configuration for phase-level tracing (parse, validate, execute).
-   * Uses the Extensions system.
-   */
-  readonly extension?: TracingExtensionConfig
-
-  /**
-   * Configuration for resolver-level tracing.
-   * Uses the Middleware system.
-   */
-  readonly resolver?: ResolverTracingConfig
-}
-
-/**
- * Add OpenTelemetry tracing to a GraphQL schema builder.
- *
- * This is a convenience function that registers both the tracing extension
- * (for phase-level spans) and resolver middleware (for field-level spans).
- *
- * **Span Hierarchy:**
- * ```
- * graphql.request (if using traced router)
- * ├── graphql.parse
- * ├── graphql.validate
- * └── graphql.execute
- *     ├── graphql.resolve Query.users
- *     ├── graphql.resolve User.posts
- *     └── graphql.resolve Post.author
- * ```
- *
- * **Requirements:**
- * - An OpenTelemetry tracer must be provided via Effect's tracing layer
- * - Use `@effect/opentelemetry` NodeSdk.layer or OtlpTracer.layer
- *
- * @example
- * ```typescript
- * import { GraphQLSchemaBuilder } from "@effect-gql/core"
- * import { withTracing } from "@effect-gql/opentelemetry"
- *
- * const builder = GraphQLSchemaBuilder.empty
- *   .query("hello", {
- *     type: S.String,
- *     resolve: () => Effect.succeed("world")
- *   })
- *   .pipe(withTracing({
- *     extension: {
- *       exposeTraceIdInResponse: true,  // Add traceId to response extensions
- *       includeQuery: false,            // Don't include query in spans (security)
- *     },
- *     resolver: {
- *       minDepth: 0,                    // Trace all resolvers
- *       excludePatterns: [/^Query\.__/], // Skip introspection
- *       includeArgs: false,             // Don't include args (security)
- *     }
- *   }))
- * ```
- *
- * @param config - Optional tracing configuration
- * @returns A function that adds tracing to a GraphQLSchemaBuilder
- */
-export const withTracing =
-  <R>(config?: GraphQLTracingConfig) =>
-  (builder: GraphQLSchemaBuilder<R>): GraphQLSchemaBuilder<R> => {
-    // Add tracing extension for phase-level spans
-    let result = builder.extension(tracingExtension(config?.extension))
-
-    // Add resolver tracing middleware for field-level spans
-    result = result.middleware(resolverTracingMiddleware(config?.resolver))
-
-    return result as GraphQLSchemaBuilder<R>
-  }
-
-// Re-export components for individual use
-export { tracingExtension, type TracingExtensionConfig } from "./tracing-extension"
-export { resolverTracingMiddleware, type ResolverTracingConfig } from "./tracing-middleware"
-export {
-  extractTraceContext,
-  parseTraceParent,
-  formatTraceParent,
-  isSampled,
-  TraceContextTag,
-  TRACEPARENT_HEADER,
-  TRACESTATE_HEADER,
-  type TraceContext,
-} from "./context-propagation"
-export { pathToString, getFieldDepth, isIntrospectionField } from "./utils"
-export {
-  makeTracedGraphQLRouter,
-  withTracedRouter,
-  type TracedRouterOptions,
-} from "./traced-router"

package/src/traced-router.ts

@@ -1,240 +0,0 @@
-import { HttpRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform"
-import { Effect, Layer, Tracer } from "effect"
-import type { GraphQLSchema } from "graphql"
-import { makeGraphQLRouter, type MakeGraphQLRouterOptions } from "@effect-gql/core/server"
-import { extractTraceContext, type TraceContext } from "./context-propagation"
-
-/**
- * Options for the traced GraphQL router
- */
-export interface TracedRouterOptions extends MakeGraphQLRouterOptions {
-  /**
-   * Name for the root HTTP span.
-   * Default: "graphql.http"
-   */
-  readonly rootSpanName?: string
-
-  /**
-   * Additional attributes to add to the root span.
-   */
-  readonly rootSpanAttributes?: Record<string, string | number | boolean>
-
-  /**
-   * Whether to propagate trace context from incoming HTTP headers.
-   * Uses W3C Trace Context (traceparent header).
-   * Default: true
-   */
-  readonly propagateContext?: boolean
-}
-
-/**
- * Create an Effect span options object from trace context
- */
-const createSpanOptions = (
-  traceContext: TraceContext | null,
-  request: HttpServerRequest.HttpServerRequest,
-  config: TracedRouterOptions
-): {
-  attributes?: Record<string, unknown>
-  parent?: Tracer.ExternalSpan
-} => {
-  const attributes: Record<string, unknown> = {
-    "http.method": request.method,
-    "http.url": request.url,
-    "http.target": request.url,
-    ...config.rootSpanAttributes,
-  }
-
-  if (traceContext && config.propagateContext !== false) {
-    return {
-      attributes,
-      parent: Tracer.externalSpan({
-        traceId: traceContext.traceId,
-        spanId: traceContext.parentSpanId,
-        sampled: (traceContext.traceFlags & 0x01) === 0x01,
-      }),
-    }
-  }
-
-  return { attributes }
-}
-
-/**
- * Creates a GraphQL router with OpenTelemetry tracing at the HTTP level.
- *
- * This wraps the standard makeGraphQLRouter to:
- * 1. Extract trace context from incoming HTTP headers (W3C Trace Context)
- * 2. Create a root span for the entire HTTP request
- * 3. Propagate trace context to child spans created by extensions/middleware
- *
- * **Span Hierarchy:**
- * ```
- * graphql.http (created by this router)
- * ├── graphql.parse (from tracing extension)
- * ├── graphql.validate (from tracing extension)
- * └── graphql.resolve Query.* (from tracing middleware)
- * ```
- *
- * @example
- * ```typescript
- * import { makeTracedGraphQLRouter } from "@effect-gql/opentelemetry"
- * import { NodeSdk } from "@effect/opentelemetry"
- *
- * const router = makeTracedGraphQLRouter(schema, serviceLayer, {
- *   path: "/graphql",
- *   graphiql: { path: "/graphiql" },
- *   rootSpanName: "graphql.http",
- *   rootSpanAttributes: {
- *     "service.name": "my-api"
- *   }
- * })
- *
- * // Provide OpenTelemetry layer when serving
- * const TracingLayer = NodeSdk.layer(() => ({
- *   resource: { serviceName: "my-graphql-api" },
- *   spanProcessor: new BatchSpanProcessor(new OTLPTraceExporter())
- * }))
- * ```
- *
- * @param schema - The GraphQL schema
- * @param layer - Effect layer providing services required by resolvers
- * @param options - Router and tracing configuration
- * @returns An HttpRouter with tracing enabled
- */
-export const makeTracedGraphQLRouter = <R>(
-  schema: GraphQLSchema,
-  layer: Layer.Layer<R>,
-  options: TracedRouterOptions = {}
-): HttpRouter.HttpRouter<never, never> => {
-  const rootSpanName = options.rootSpanName ?? "graphql.http"
-
-  // Create the base router (handles GraphQL logic)
-  const baseRouter = makeGraphQLRouter(schema, layer, options)
-
-  // Convert base router to an HttpApp for Effect-based handling
-  const baseApp = HttpRouter.toHttpApp(baseRouter)
-
-  // Wrap with tracing
-  return HttpRouter.empty.pipe(
-    HttpRouter.all(
-      "*",
-      Effect.gen(function* () {
-        const request = yield* HttpServerRequest.HttpServerRequest
-
-        // Extract trace context from headers (if enabled)
-        const traceContext =
-          options.propagateContext !== false
-            ? yield* extractTraceContext.pipe(Effect.catchAll(() => Effect.succeed(null)))
-            : null
-
-        // Create span options with parent context if available
-        const spanOptions = createSpanOptions(traceContext, request, options)
-
-        // Execute the request inside a root span
-        return yield* Effect.withSpan(
-          rootSpanName,
-          spanOptions
-        )(
-          Effect.gen(function* () {
-            // Delegate to the base app (which handles the request from context)
-            const app = yield* baseApp
-            const response = yield* app.pipe(
-              Effect.catchTag("RouteNotFound", () =>
-                HttpServerResponse.text(JSON.stringify({ errors: [{ message: "Not Found" }] }), {
-                  status: 404,
-                  headers: { "content-type": "application/json" },
-                })
-              )
-            )
-
-            // Annotate span with response info
-            yield* Effect.annotateCurrentSpan("http.status_code", response.status)
-
-            return response
-          })
-        )
-      })
-    )
-  )
-}
-
-/**
- * Wrap an existing HttpRouter with OpenTelemetry tracing.
- *
- * This is useful when you already have a router and want to add
- * request-level tracing without recreating it.
- *
- * @example
- * ```typescript
- * import { toRouter } from "@effect-gql/core/server"
- * import { withTracedRouter } from "@effect-gql/opentelemetry"
- *
- * const baseRouter = toRouter(builder, serviceLayer)
- * const tracedRouter = withTracedRouter(baseRouter, {
- *   rootSpanName: "graphql.http"
- * })
- * ```
- */
-export const withTracedRouter = (
-  router: HttpRouter.HttpRouter<any, any>,
-  options: {
-    rootSpanName?: string
-    rootSpanAttributes?: Record<string, string | number | boolean>
-    propagateContext?: boolean
-  } = {}
-): HttpRouter.HttpRouter<any, any> => {
-  const rootSpanName = options.rootSpanName ?? "graphql.http"
-
-  // Convert router to an HttpApp for Effect-based handling
-  const baseApp = HttpRouter.toHttpApp(router)
-
-  return HttpRouter.empty.pipe(
-    HttpRouter.all(
-      "*",
-      Effect.gen(function* () {
-        const request = yield* HttpServerRequest.HttpServerRequest
-
-        // Extract trace context from headers
-        const traceContext =
-          options.propagateContext !== false
-            ? yield* extractTraceContext.pipe(Effect.catchAll(() => Effect.succeed(null)))
-            : null
-
-        const spanOptions: {
-          attributes: Record<string, unknown>
-          parent?: Tracer.ExternalSpan
-        } = {
-          attributes: {
-            "http.method": request.method,
-            "http.url": request.url,
-            ...options.rootSpanAttributes,
-          },
-        }
-
-        if (traceContext && options.propagateContext !== false) {
-          spanOptions.parent = Tracer.externalSpan({
-            traceId: traceContext.traceId,
-            spanId: traceContext.parentSpanId,
-            sampled: (traceContext.traceFlags & 0x01) === 0x01,
-          })
-        }
-
-        return yield* Effect.withSpan(
-          rootSpanName,
-          spanOptions
-        )(
-          Effect.gen(function* () {
-            // Delegate to the base app (which handles the request from context)
-            const app = yield* baseApp
-            const response = yield* app
-
-            // Annotate span with response info
-            yield* Effect.annotateCurrentSpan("http.status_code", response.status)
-
-            return response
-          })
-        )
-      })
-    )
-  )
-}

package/src/tracing-extension.ts

@@ -1,175 +0,0 @@
-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,
-            }))
-          )
-        )
-      }
-    }),
-})