@effect-gql/opentelemetry 0.1.0

package/src/context-propagation.ts

@@ -0,0 +1,177 @@
+import { Effect, Context } from "effect"
+import { HttpServerRequest } from "@effect/platform"
+
+/**
+ * W3C Trace Context header names
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export const TRACEPARENT_HEADER = "traceparent"
+export const TRACESTATE_HEADER = "tracestate"
+
+/**
+ * Parsed W3C Trace Context from incoming HTTP headers
+ */
+export interface TraceContext {
+  /**
+   * Version of the trace context format (always "00" for current spec)
+   */
+  readonly version: string
+
+  /**
+   * Trace ID - 32 character lowercase hex string
+   */
+  readonly traceId: string
+
+  /**
+   * Parent Span ID - 16 character lowercase hex string
+   */
+  readonly parentSpanId: string
+
+  /**
+   * Trace flags - determines if trace is sampled
+   * Bit 0 (0x01) = sampled flag
+   */
+  readonly traceFlags: number
+
+  /**
+   * Optional trace state from upstream services
+   */
+  readonly traceState?: string
+}
+
+/**
+ * Context tag for TraceContext
+ */
+export class TraceContextTag extends Context.Tag("@effect-gql/opentelemetry/TraceContext")<
+  TraceContextTag,
+  TraceContext
+>() {}
+
+/**
+ * Parse a W3C traceparent header value.
+ *
+ * Format: {version}-{trace-id}-{parent-id}-{trace-flags}
+ * Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+ *
+ * @see https://www.w3.org/TR/trace-context/#traceparent-header
+ *
+ * @param header - The traceparent header value
+ * @returns Parsed trace context or null if invalid
+ */
+export const parseTraceParent = (header: string): TraceContext | null => {
+  const trimmed = header.trim().toLowerCase()
+  const parts = trimmed.split("-")
+
+  if (parts.length !== 4) {
+    return null
+  }
+
+  const [version, traceId, parentSpanId, flagsHex] = parts
+
+  // Validate version (2 hex chars)
+  if (version.length !== 2 || !/^[0-9a-f]{2}$/.test(version)) {
+    return null
+  }
+
+  // Validate trace ID (32 hex chars, not all zeros)
+  if (traceId.length !== 32 || !/^[0-9a-f]{32}$/.test(traceId)) {
+    return null
+  }
+  if (traceId === "00000000000000000000000000000000") {
+    return null
+  }
+
+  // Validate parent span ID (16 hex chars, not all zeros)
+  if (parentSpanId.length !== 16 || !/^[0-9a-f]{16}$/.test(parentSpanId)) {
+    return null
+  }
+  if (parentSpanId === "0000000000000000") {
+    return null
+  }
+
+  // Validate trace flags (2 hex chars)
+  if (flagsHex.length !== 2 || !/^[0-9a-f]{2}$/.test(flagsHex)) {
+    return null
+  }
+
+  const traceFlags = parseInt(flagsHex, 16)
+
+  return {
+    version,
+    traceId,
+    parentSpanId,
+    traceFlags,
+  }
+}
+
+/**
+ * Check if a trace context is sampled (should be recorded)
+ */
+export const isSampled = (context: TraceContext): boolean => {
+  return (context.traceFlags & 0x01) === 0x01
+}
+
+/**
+ * Extract trace context from HTTP request headers.
+ *
+ * Looks for the W3C Trace Context headers:
+ * - `traceparent`: Required, contains trace ID, span ID, and flags
+ * - `tracestate`: Optional, vendor-specific trace data
+ *
+ * @example
+ * ```typescript
+ * const context = yield* extractTraceContext
+ * if (context) {
+ *   console.log(`Continuing trace: ${context.traceId}`)
+ * }
+ * ```
+ */
+export const extractTraceContext: Effect.Effect<
+  TraceContext | null,
+  never,
+  HttpServerRequest.HttpServerRequest
+> = Effect.gen(function* () {
+  const request = yield* HttpServerRequest.HttpServerRequest
+  const headers = request.headers
+
+  // Get traceparent header (case-insensitive)
+  const traceparentKey = Object.keys(headers).find((k) => k.toLowerCase() === TRACEPARENT_HEADER)
+
+  if (!traceparentKey) {
+    return null
+  }
+
+  const traceparentValue = headers[traceparentKey]
+  const traceparent = Array.isArray(traceparentValue) ? traceparentValue[0] : traceparentValue
+
+  if (!traceparent) {
+    return null
+  }
+
+  const context = parseTraceParent(traceparent)
+  if (!context) {
+    return null
+  }
+
+  // Get optional tracestate header
+  const tracestateKey = Object.keys(headers).find((k) => k.toLowerCase() === TRACESTATE_HEADER)
+
+  if (tracestateKey) {
+    const tracestateValue = headers[tracestateKey]
+    const tracestate = Array.isArray(tracestateValue) ? tracestateValue[0] : tracestateValue
+
+    if (tracestate) {
+      return { ...context, traceState: tracestate }
+    }
+  }
+
+  return context
+})
+
+/**
+ * Format a trace context as a traceparent header value
+ */
+export const formatTraceParent = (context: TraceContext): string => {
+  const flags = context.traceFlags.toString(16).padStart(2, "0")
+  return `${context.version}-${context.traceId}-${context.parentSpanId}-${flags}`
+}

package/src/index.ts

@@ -0,0 +1,139 @@
+/**
+ * @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

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