@effect-gql/opentelemetry 0.1.0 → 1.0.0

package/index.d.cts

@@ -0,0 +1,416 @@
+import { GraphQLExtension, ExtensionsService, MiddlewareRegistration, GraphQLSchemaBuilder } from '@effect-gql/core';
+import { GraphQLResolveInfo, ResponsePath, GraphQLSchema } from 'graphql';
+import { Effect, Context, Layer } from 'effect';
+import { HttpServerRequest, HttpRouter } from '@effect/platform';
+import { MakeGraphQLRouterOptions } from '@effect-gql/core/server';
+
+/**
+ * Configuration for the GraphQL tracing extension
+ */
+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>;
+}
+/**
+ * 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", { ... })
+ * )
+ * ```
+ */
+declare const tracingExtension: (config?: TracingExtensionConfig) => GraphQLExtension<ExtensionsService>;
+
+/**
+ * Configuration for resolver tracing middleware
+ */
+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;
+}
+/**
+ * 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", { ... })
+ * )
+ * ```
+ */
+declare const resolverTracingMiddleware: (config?: ResolverTracingConfig) => MiddlewareRegistration<never>;
+
+/**
+ * W3C Trace Context header names
+ * @see https://www.w3.org/TR/trace-context/
+ */
+declare const TRACEPARENT_HEADER = "traceparent";
+declare const TRACESTATE_HEADER = "tracestate";
+/**
+ * Parsed W3C Trace Context from incoming HTTP headers
+ */
+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;
+}
+declare const TraceContextTag_base: Context.TagClass<TraceContextTag, "@effect-gql/opentelemetry/TraceContext", TraceContext>;
+/**
+ * Context tag for TraceContext
+ */
+declare class TraceContextTag extends TraceContextTag_base {
+}
+/**
+ * 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
+ */
+declare const parseTraceParent: (header: string) => TraceContext | null;
+/**
+ * Check if a trace context is sampled (should be recorded)
+ */
+declare const isSampled: (context: TraceContext) => boolean;
+/**
+ * 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}`)
+ * }
+ * ```
+ */
+declare const extractTraceContext: Effect.Effect<TraceContext | null, never, HttpServerRequest.HttpServerRequest>;
+/**
+ * Format a trace context as a traceparent header value
+ */
+declare const formatTraceParent: (context: TraceContext) => string;
+
+/**
+ * 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"
+ */
+declare const pathToString: (path: ResponsePath | undefined) => string;
+/**
+ * Get the depth of a field in the query tree.
+ * Root fields (Query.*, Mutation.*) have depth 0.
+ */
+declare const getFieldDepth: (info: GraphQLResolveInfo) => number;
+/**
+ * Check if a field is an introspection field (__schema, __type, etc.)
+ */
+declare const isIntrospectionField: (info: GraphQLResolveInfo) => boolean;
+
+/**
+ * Options for the traced GraphQL router
+ */
+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;
+}
+/**
+ * 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
+ */
+declare const makeTracedGraphQLRouter: <R>(schema: GraphQLSchema, layer: Layer.Layer<R>, options?: TracedRouterOptions) => HttpRouter.HttpRouter<never, never>;
+/**
+ * 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"
+ * })
+ * ```
+ */
+declare const withTracedRouter: (router: HttpRouter.HttpRouter<any, any>, options?: {
+    rootSpanName?: string;
+    rootSpanAttributes?: Record<string, string | number | boolean>;
+    propagateContext?: boolean;
+}) => HttpRouter.HttpRouter<any, any>;
+
+/**
+ * @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
+ */
+
+/**
+ * Complete configuration for GraphQL tracing
+ */
+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
+ */
+declare const withTracing: <R>(config?: GraphQLTracingConfig) => (builder: GraphQLSchemaBuilder<R>) => GraphQLSchemaBuilder<R>;
+
+export { type GraphQLTracingConfig, type ResolverTracingConfig, TRACEPARENT_HEADER, TRACESTATE_HEADER, type TraceContext, TraceContextTag, type TracedRouterOptions, type TracingExtensionConfig, extractTraceContext, formatTraceParent, getFieldDepth, isIntrospectionField, isSampled, makeTracedGraphQLRouter, parseTraceParent, pathToString, resolverTracingMiddleware, tracingExtension, withTracedRouter, withTracing };