@effect-gql/opentelemetry 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Nick Fisher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/context-propagation.d.ts

@@ -0,0 +1,78 @@
+import { Effect, Context } from "effect";
+import { HttpServerRequest } from "@effect/platform";
+/**
+ * W3C Trace Context header names
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export declare const TRACEPARENT_HEADER = "traceparent";
+export declare 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;
+}
+declare const TraceContextTag_base: Context.TagClass<TraceContextTag, "@effect-gql/opentelemetry/TraceContext", TraceContext>;
+/**
+ * Context tag for TraceContext
+ */
+export 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
+ */
+export declare const parseTraceParent: (header: string) => TraceContext | null;
+/**
+ * Check if a trace context is sampled (should be recorded)
+ */
+export 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}`)
+ * }
+ * ```
+ */
+export declare const extractTraceContext: Effect.Effect<TraceContext | null, never, HttpServerRequest.HttpServerRequest>;
+/**
+ * Format a trace context as a traceparent header value
+ */
+export declare const formatTraceParent: (context: TraceContext) => string;
+export {};
+//# sourceMappingURL=context-propagation.d.ts.map

package/dist/context-propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-propagation.d.ts","sourceRoot":"","sources":["../src/context-propagation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,gBAAgB,CAAA;AAC/C,eAAO,MAAM,iBAAiB,eAAe,CAAA;AAE7C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,oBAGlC;CAAG;AAEN;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,MAAM,KAAG,YAAY,GAAG,IA4ChE,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,YAAY,KAAG,OAEjD,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,CAC7C,YAAY,GAAG,IAAI,EACnB,KAAK,EACL,iBAAiB,CAAC,iBAAiB,CAqCnC,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,YAAY,KAAG,MAGzD,CAAA"}

package/dist/context-propagation.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTraceParent = exports.extractTraceContext = exports.isSampled = exports.parseTraceParent = exports.TraceContextTag = exports.TRACESTATE_HEADER = exports.TRACEPARENT_HEADER = void 0;
+const effect_1 = require("effect");
+const platform_1 = require("@effect/platform");
+/**
+ * W3C Trace Context header names
+ * @see https://www.w3.org/TR/trace-context/
+ */
+exports.TRACEPARENT_HEADER = "traceparent";
+exports.TRACESTATE_HEADER = "tracestate";
+/**
+ * Context tag for TraceContext
+ */
+class TraceContextTag extends effect_1.Context.Tag("@effect-gql/opentelemetry/TraceContext")() {
+}
+exports.TraceContextTag = TraceContextTag;
+/**
+ * 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
+ */
+const parseTraceParent = (header) => {
+    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,
+    };
+};
+exports.parseTraceParent = parseTraceParent;
+/**
+ * Check if a trace context is sampled (should be recorded)
+ */
+const isSampled = (context) => {
+    return (context.traceFlags & 0x01) === 0x01;
+};
+exports.isSampled = isSampled;
+/**
+ * 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}`)
+ * }
+ * ```
+ */
+exports.extractTraceContext = effect_1.Effect.gen(function* () {
+    const request = yield* platform_1.HttpServerRequest.HttpServerRequest;
+    const headers = request.headers;
+    // Get traceparent header (case-insensitive)
+    const traceparentKey = Object.keys(headers).find((k) => k.toLowerCase() === exports.TRACEPARENT_HEADER);
+    if (!traceparentKey) {
+        return null;
+    }
+    const traceparentValue = headers[traceparentKey];
+    const traceparent = Array.isArray(traceparentValue) ? traceparentValue[0] : traceparentValue;
+    if (!traceparent) {
+        return null;
+    }
+    const context = (0, exports.parseTraceParent)(traceparent);
+    if (!context) {
+        return null;
+    }
+    // Get optional tracestate header
+    const tracestateKey = Object.keys(headers).find((k) => k.toLowerCase() === exports.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
+ */
+const formatTraceParent = (context) => {
+    const flags = context.traceFlags.toString(16).padStart(2, "0");
+    return `${context.version}-${context.traceId}-${context.parentSpanId}-${flags}`;
+};
+exports.formatTraceParent = formatTraceParent;
+//# sourceMappingURL=context-propagation.js.map

package/dist/context-propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-propagation.js","sourceRoot":"","sources":["../src/context-propagation.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @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 { type TracingExtensionConfig } from "./tracing-extension";
+import { 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 declare const withTracing: <R>(config?: GraphQLTracingConfig) => (builder: GraphQLSchemaBuilder<R>) => GraphQLSchemaBuilder<R>;
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,EAAoB,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAE5F;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAA;IAE3C;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,WAAW,GACrB,CAAC,EAAE,SAAS,oBAAoB,MAChC,SAAS,oBAAoB,CAAC,CAAC,CAAC,KAAG,oBAAoB,CAAC,CAAC,CAQzD,CAAA;AAGH,OAAO,EAAE,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACnF,OAAO,EAAE,yBAAyB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5F,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC3E,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTracedRouter = exports.makeTracedGraphQLRouter = exports.isIntrospectionField = exports.getFieldDepth = exports.pathToString = exports.TRACESTATE_HEADER = exports.TRACEPARENT_HEADER = exports.TraceContextTag = exports.isSampled = exports.formatTraceParent = exports.parseTraceParent = exports.extractTraceContext = exports.resolverTracingMiddleware = exports.tracingExtension = exports.withTracing = void 0;
+const tracing_extension_1 = require("./tracing-extension");
+const tracing_middleware_1 = require("./tracing-middleware");
+/**
+ * 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
+ */
+const withTracing = (config) => (builder) => {
+    // Add tracing extension for phase-level spans
+    let result = builder.extension((0, tracing_extension_1.tracingExtension)(config?.extension));
+    // Add resolver tracing middleware for field-level spans
+    result = result.middleware((0, tracing_middleware_1.resolverTracingMiddleware)(config?.resolver));
+    return result;
+};
+exports.withTracing = withTracing;
+// Re-export components for individual use
+var tracing_extension_2 = require("./tracing-extension");
+Object.defineProperty(exports, "tracingExtension", { enumerable: true, get: function () { return tracing_extension_2.tracingExtension; } });
+var tracing_middleware_2 = require("./tracing-middleware");
+Object.defineProperty(exports, "resolverTracingMiddleware", { enumerable: true, get: function () { return tracing_middleware_2.resolverTracingMiddleware; } });
+var context_propagation_1 = require("./context-propagation");
+Object.defineProperty(exports, "extractTraceContext", { enumerable: true, get: function () { return context_propagation_1.extractTraceContext; } });
+Object.defineProperty(exports, "parseTraceParent", { enumerable: true, get: function () { return context_propagation_1.parseTraceParent; } });
+Object.defineProperty(exports, "formatTraceParent", { enumerable: true, get: function () { return context_propagation_1.formatTraceParent; } });
+Object.defineProperty(exports, "isSampled", { enumerable: true, get: function () { return context_propagation_1.isSampled; } });
+Object.defineProperty(exports, "TraceContextTag", { enumerable: true, get: function () { return context_propagation_1.TraceContextTag; } });
+Object.defineProperty(exports, "TRACEPARENT_HEADER", { enumerable: true, get: function () { return context_propagation_1.TRACEPARENT_HEADER; } });
+Object.defineProperty(exports, "TRACESTATE_HEADER", { enumerable: true, get: function () { return context_propagation_1.TRACESTATE_HEADER; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "pathToString", { enumerable: true, get: function () { return utils_1.pathToString; } });
+Object.defineProperty(exports, "getFieldDepth", { enumerable: true, get: function () { return utils_1.getFieldDepth; } });
+Object.defineProperty(exports, "isIntrospectionField", { enumerable: true, get: function () { return utils_1.isIntrospectionField; } });
+var traced_router_1 = require("./traced-router");
+Object.defineProperty(exports, "makeTracedGraphQLRouter", { enumerable: true, get: function () { return traced_router_1.makeTracedGraphQLRouter; } });
+Object.defineProperty(exports, "withTracedRouter", { enumerable: true, get: function () { return traced_router_1.withTracedRouter; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAGH,2DAAmF;AACnF,6DAA4F;AAmB5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACI,MAAM,WAAW,GACtB,CAAI,MAA6B,EAAE,EAAE,CACrC,CAAC,OAAgC,EAA2B,EAAE;IAC5D,8CAA8C;IAC9C,IAAI,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,IAAA,oCAAgB,EAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IAEnE,wDAAwD;IACxD,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,IAAA,8CAAyB,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;IAEvE,OAAO,MAAiC,CAAA;AAC1C,CAAC,CAAA;AAVU,QAAA,WAAW,eAUrB;AAEH,0CAA0C;AAC1C,yDAAmF;AAA1E,qHAAA,gBAAgB,OAAA;AACzB,2DAA4F;AAAnF,+HAAA,yBAAyB,OAAA;AAClC,6DAS8B;AAR5B,0HAAA,mBAAmB,OAAA;AACnB,uHAAA,gBAAgB,OAAA;AAChB,wHAAA,iBAAiB,OAAA;AACjB,gHAAA,SAAS,OAAA;AACT,sHAAA,eAAe,OAAA;AACf,yHAAA,kBAAkB,OAAA;AAClB,wHAAA,iBAAiB,OAAA;AAGnB,iCAA2E;AAAlE,qGAAA,YAAY,OAAA;AAAE,sGAAA,aAAa,OAAA;AAAE,6GAAA,oBAAoB,OAAA;AAC1D,iDAIwB;AAHtB,wHAAA,uBAAuB,OAAA;AACvB,iHAAA,gBAAgB,OAAA"}

package/dist/traced-router.d.ts

@@ -0,0 +1,90 @@
+import { HttpRouter } from "@effect/platform";
+import { Layer } from "effect";
+import type { GraphQLSchema } from "graphql";
+import { type MakeGraphQLRouterOptions } from "@effect-gql/core/server";
+/**
+ * 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;
+}
+/**
+ * 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 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"
+ * })
+ * ```
+ */
+export declare const withTracedRouter: (router: HttpRouter.HttpRouter<any, any>, options?: {
+    rootSpanName?: string;
+    rootSpanAttributes?: Record<string, string | number | boolean>;
+    propagateContext?: boolean;
+}) => HttpRouter.HttpRouter<any, any>;
+//# sourceMappingURL=traced-router.d.ts.map

package/dist/traced-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traced-router.d.ts","sourceRoot":"","sources":["../src/traced-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAyC,MAAM,kBAAkB,CAAA;AACpF,OAAO,EAAU,KAAK,EAAU,MAAM,QAAQ,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAqB,KAAK,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAG1F;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,wBAAwB;IACnE;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAE9B;;OAEG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;IAEvE;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CACpC;AAkCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,uBAAuB,GAAI,CAAC,EACvC,QAAQ,aAAa,EACrB,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EACrB,UAAS,mBAAwB,KAChC,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAmDpC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,UAAU,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,EACvC,UAAS;IACP,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAA;CACtB,KACL,UAAU,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAuDhC,CAAA"}