feat: change to batch processor (#326)

danstarns · web-flow · commit c86ef7794f1a · 2024-06-09T14:32:58.000+01:00
* feat: change to batch exporter

* feat: add spanProcessorFactory

* feat: further usage of spanProcessorFactory

* docs: add performance note

* feat: more usage of spanProcessorFactory

* docs: remove unused code

* feat: more spanProcessorFactory usage

* fix: lower scheduledDelayMillis

* feat: more usage of spanProcessorFactory

* feat: more spanProcessorFactory usage

* feat: add test using the BatchSpanProcessor

* docs: *
diff --git a/apps/backend/package.json b/apps/backend/package.json
@@ -23,6 +23,7 @@
     "@graphql-debugger/graphql-schema": "workspace:^",
     "@graphql-debugger/plugin-express": "workspace:^",
     "@graphql-debugger/ui": "workspace:^",
+    "@graphql-debugger/opentelemetry": "workspace:^",
     "@graphql-debugger/utils": "workspace:^",
     "cors": "2.8.5",
     "express": "4.19.2",
diff --git a/apps/backend/src/index.ts b/apps/backend/src/index.ts
@@ -1,5 +1,6 @@
 import { DebuggerClient } from "@graphql-debugger/client";
 import { createServer } from "@graphql-debugger/graphql-schema";
+import { SpanExporter, SpanProcessor } from "@graphql-debugger/opentelemetry";
 import { graphqlDebugger } from "@graphql-debugger/plugin-express";
 
 import cors from "cors";
@@ -14,9 +15,11 @@ import { debug } from "./debug";
 export async function start({
   port,
   client,
+  spanProcessorFactory,
 }: {
   port: string;
   client: DebuggerClient;
+  spanProcessorFactory?: (exporter: SpanExporter) => SpanProcessor;
 }) {
   try {
     const app: Express = express();
@@ -29,6 +32,7 @@ export async function start({
       "/graphql",
       createServer({
         client,
+        spanProcessorFactory,
       }),
     );
     app.use(
diff --git a/apps/backend/src/main.ts b/apps/backend/src/main.ts
@@ -1,9 +1,19 @@
+import {
+  SimpleSpanProcessor,
+  SpanExporter,
+} from "@graphql-debugger/opentelemetry";
+
 import { client } from "./client";
 import { BACKEND_PORT } from "./config";
 import { debug } from "./debug";
 import { start } from "./index";
 
-start({ port: BACKEND_PORT, client })
+const spanProcessorFactory =
+  process.env.NODE_ENV === "development"
+    ? (exporter: SpanExporter) => new SimpleSpanProcessor(exporter)
+    : undefined;
+
+start({ port: BACKEND_PORT, client, spanProcessorFactory })
   .then(() => {
     debug("Online");
   })
diff --git a/docs/src/pages/docs/_meta.ts b/docs/src/pages/docs/_meta.ts
@@ -2,6 +2,7 @@ export default {
   index: "Quick Start",
   why: "Why Debugger ?",
   how: "How Debugger Works ?",
+  performance: "Performance",
   components: "Components",
   packages: "Packages",
   plugins: "Plugins",
diff --git a/docs/src/pages/docs/performance.mdx b/docs/src/pages/docs/performance.mdx
@@ -0,0 +1,21 @@
+# GraphQL Debugger Performance
+
+We use standard OpenTelemetry libraries in our implementation to ensure that our tool does not introduce any performance overhead. We accept there to be minor overhead from our implementation as we add additional instrumentation to the server. We work hard to ensure GraphQL Debuggers performance does not impact the performance of your server.
+
+## Benchmarks
+
+We have public benchmarks executed on each commit to ensure that we are not introduce any performance regressions. You can find the benchmarks in our monorepo under the `benchmarks` directory.
+
+1. https://github.com/rocket-connect/graphql-debugger/tree/main/benchmarks
+
+> We collaborate with the OpenTelemetry community to ensure that our implementation is as performant as possible see https://github.com/open-telemetry/opentelemetry-js/issues/4741
+
+## What does GraphQL Debugger instrument?
+
+GraphQL Debugger wraps each field resolver in your GraphQL schema with a span. It does this by visiting the AST at startup and adding the [`@trace` directive](/docs/packages/trace-directive) to each field. Each span is then generated using the OpenTelemetry API.
+
+On span creation we capture various attributes of the field resolver. This could include, the GraphQL query, the arguments passed to the field resolver, the result of the field resolver, and the time it took to execute the field resolver.
+
+## How can this impact performance?
+
+Adding more function calls to your stack is always going to have some impact on performance. We work hard to ensure that the impact is minimal. We have a number of optimizations in place to ensure that the impact is minimal. You can read more about these optimizations in our [Performance Issue](https://github.com/rocket-connect/graphql-debugger/issues/322).
diff --git a/e2e/package.json b/e2e/package.json
@@ -26,6 +26,7 @@
     "@graphql-debugger/client": "workspace:^",
     "@graphql-debugger/collector-proxy": "workspace:^",
     "@graphql-debugger/trace-schema": "workspace:^",
+    "@graphql-debugger/opentelemetry": "workspace:^",
     "@graphql-debugger/ui": "workspace:^",
     "@graphql-debugger/utils": "workspace:^",
     "@graphql-tools/schema": "10.0.3",
diff --git a/e2e/tests/utils/backend.ts b/e2e/tests/utils/backend.ts
@@ -1,5 +1,6 @@
 import * as backend from "@graphql-debugger/backend";
 import * as collector from "@graphql-debugger/collector-proxy";
+import { SimpleSpanProcessor } from "@graphql-debugger/opentelemetry";
 
 import http from "http";
 
@@ -18,6 +19,7 @@ export async function listen() {
     backendServer = await backend.start({
       port: backend.BACKEND_PORT,
       client: localClient,
+      spanProcessorFactory: (exporter) => new SimpleSpanProcessor(exporter),
     });
     const collectorInstance = await collector.start({
       port: collector.COLLECTOR_PORT,
diff --git a/e2e/tests/utils/create-test-schema.ts b/e2e/tests/utils/create-test-schema.ts
@@ -1,4 +1,5 @@
 import { DebuggerClient } from "@graphql-debugger/client";
+import { SimpleSpanProcessor } from "@graphql-debugger/opentelemetry";
 import { traceSchema } from "@graphql-debugger/trace-schema";
 import { Schema } from "@graphql-debugger/types";
 
@@ -65,6 +66,7 @@ export async function createTestSchema({
   const { schema, schemaHash } = traceSchema({
     schema: executableSchema,
     adapter: client.adapter,
+    spanProcessorFactory: (exporter) => new SimpleSpanProcessor(exporter),
   });
 
   const dbSchema = await client.schema.upsert({
diff --git a/package.json b/package.json
@@ -3,7 +3,7 @@
   "version": "0.0.0-alpha.109",
   "private": true,
   "scripts": {
-    "dev": "cross-env turbo dev --filter '!graphql-debugger' --filter '!@graphql-debugger/landing-page-app' --filter '!@graphql-debugger/landing-page-server' --concurrency=30",
+    "dev": "cross-env NODE_ENV=\"development\" turbo dev --filter '!graphql-debugger' --filter '!@graphql-debugger/landing-page-app' --filter '!@graphql-debugger/landing-page-server' --concurrency=30",
     "build": "turbo build",
     "release": "cross-env DEBUG=\"@graphql-debugger:*\" node ./packages/utils/build/release.js",
     "test:sequential": "pnpm recursive exec -- sh -c 'pnpm run test || (echo \"Tests failed!\" && exit 1)'",
diff --git a/packages/graphql-schema/src/index.ts b/packages/graphql-schema/src/index.ts
@@ -1,12 +1,19 @@
 import { DebuggerClient } from "@graphql-debugger/client";
+import { TraceSchemaInput } from "@graphql-debugger/trace-schema";
 
 import { createYoga } from "graphql-yoga";
 
 import { context } from "./context";
 import { createSchema } from "./schema";
 
-export function createServer({ client }: { client: DebuggerClient }) {
-  const { schema, schemaHash } = createSchema({ client });
+export function createServer({
+  client,
+  spanProcessorFactory,
+}: {
+  client: DebuggerClient;
+  spanProcessorFactory?: TraceSchemaInput["spanProcessorFactory"];
+}) {
+  const { schema, schemaHash } = createSchema({ client, spanProcessorFactory });
 
   return createYoga({
     schema,
diff --git a/packages/graphql-schema/src/schema.ts b/packages/graphql-schema/src/schema.ts
@@ -1,6 +1,6 @@
 import { DebuggerClient } from "@graphql-debugger/client";
 import { tracing } from "@graphql-debugger/data-access";
-import { traceSchema } from "@graphql-debugger/trace-schema";
+import { TraceSchemaInput, traceSchema } from "@graphql-debugger/trace-schema";
 import { hashSchema } from "@graphql-debugger/utils";
 
 import SchemaBuilder from "@pothos/core";
@@ -23,7 +23,13 @@ require("./mutations");
 
 const build = builder.toSchema();
 
-export function createSchema({ client }: { client: DebuggerClient }) {
+export function createSchema({
+  client,
+  spanProcessorFactory,
+}: {
+  client: DebuggerClient;
+  spanProcessorFactory?: TraceSchemaInput["spanProcessorFactory"];
+}) {
   let schema: GraphQLSchema;
   let schemaHash: string;
 
@@ -32,6 +38,7 @@ export function createSchema({ client }: { client: DebuggerClient }) {
       schema: build,
       adapter: client.adapter,
       shouldExportSchema: true,
+      spanProcessorFactory,
       ...(TRACE_PRISMA && {
         instrumentations: [tracing],
       }),
diff --git a/packages/opentelemetry/src/index.ts b/packages/opentelemetry/src/index.ts
@@ -13,6 +13,8 @@ export {
   InMemorySpanExporter,
   ReadableSpan,
   RandomIdGenerator,
+  SpanExporter,
+  SpanProcessor,
 } from "@opentelemetry/sdk-trace-base";
 export {
   Context,
@@ -27,3 +29,8 @@ export {
 export { InstrumentationOption } from "@opentelemetry/instrumentation";
 
 export { Span as ApiSpan } from "@opentelemetry/api";
+
+export {
+  SimpleSpanProcessor,
+  BatchSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
diff --git a/packages/opentelemetry/src/setup-otel.ts b/packages/opentelemetry/src/setup-otel.ts
@@ -7,8 +7,10 @@ import {
 } from "@opentelemetry/instrumentation";
 import { OTLPExporterNodeConfigBase } from "@opentelemetry/otlp-exporter-base";
 import {
+  BatchSpanProcessor,
   InMemorySpanExporter,
-  SimpleSpanProcessor,
+  SpanExporter,
+  SpanProcessor,
 } from "@opentelemetry/sdk-trace-base";
 
 import { provider } from "./provider";
@@ -17,15 +19,16 @@ export type SetupOtelInput = {
   inMemory?: boolean;
   exporterConfig?: OTLPExporterNodeConfigBase;
   instrumentations?: InstrumentationOption[];
+  spanProcessorFactory?: (exporter: SpanExporter) => SpanProcessor;
 };
 
 export function setupOtel({
   inMemory,
   exporterConfig,
   instrumentations,
-}: SetupOtelInput): OTLPTraceExporter | InMemorySpanExporter {
-  let exporter: OTLPTraceExporter | InMemorySpanExporter =
-    new OTLPTraceExporter();
+  spanProcessorFactory,
+}: SetupOtelInput): SpanExporter {
+  let exporter: SpanExporter = new OTLPTraceExporter();
   if (inMemory) {
     exporter = new InMemorySpanExporter();
   } else {
@@ -36,7 +39,11 @@ export function setupOtel({
 
   api.context.setGlobalContextManager(contextManager);
 
-  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+  const processor = spanProcessorFactory
+    ? spanProcessorFactory(exporter)
+    : new BatchSpanProcessor(exporter);
+
+  provider.addSpanProcessor(processor);
 
   if (instrumentations) {
     registerInstrumentations({
diff --git a/packages/trace-directive/tests/trace-batch.test.ts b/packages/trace-directive/tests/trace-batch.test.ts
@@ -0,0 +1,81 @@
+import {
+  BatchSpanProcessor,
+  InMemorySpanExporter,
+  ReadableSpan,
+  buildSpanTree,
+  setupOtel,
+} from "@graphql-debugger/opentelemetry";
+
+import { makeExecutableSchema } from "@graphql-tools/schema";
+import { graphql } from "graphql";
+
+import { GraphQLDebuggerContext, traceDirective } from "../src";
+
+const inMemorySpanExporter = setupOtel({
+  inMemory: true,
+  spanProcessorFactory: (exporter) => new BatchSpanProcessor(exporter),
+}) as InMemorySpanExporter;
+
+const util = require("util");
+const sleep = util.promisify(setTimeout);
+
+describe("@trace directive BatchSpanProcessor", () => {
+  beforeEach(() => {
+    inMemorySpanExporter.reset();
+  });
+
+  test("should trace a query", async () => {
+    const typeDefs = `
+          type User {
+            name: String
+          }
+  
+          type Query {
+            users: [User] @trace
+          }
+      `;
+
+    const resolvers = {
+      Query: {
+        users: async () => {
+          return [{ name: "Bob", age: 100 }];
+        },
+      },
+    };
+
+    const trace = traceDirective();
+
+    let schema = makeExecutableSchema({
+      typeDefs: [typeDefs, trace.typeDefs],
+      resolvers,
+    });
+
+    schema = trace.transformer(schema);
+
+    const query = `
+        query {
+          users {
+            name
+          }
+        }
+      `;
+
+    const { errors } = await graphql({
+      schema,
+      source: query,
+      contextValue: {
+        GraphQLDebuggerContext: new GraphQLDebuggerContext({ schema }),
+      },
+    });
+
+    expect(errors).toBeUndefined();
+
+    // This sleep is waiting for the batch span processor to finish processing
+    await sleep(5000);
+
+    const spans = inMemorySpanExporter.getFinishedSpans();
+    const rootSpan = spans.find((span) => !span.parentSpanId) as ReadableSpan;
+    const spanTree = buildSpanTree({ span: rootSpan, children: [] }, spans);
+    expect(spanTree.span.name).toEqual("query users");
+  });
+});
diff --git a/packages/trace-directive/tests/trace.test.ts b/packages/trace-directive/tests/trace.test.ts
@@ -1,6 +1,7 @@
 import {
   InMemorySpanExporter,
   ReadableSpan,
+  SimpleSpanProcessor,
   SpanStatusCode,
   buildSpanTree,
   setupOtel,
@@ -21,6 +22,7 @@ import { GraphQLDebuggerContext, traceDirective } from "../src";
 
 const inMemorySpanExporter = setupOtel({
   inMemory: true,
+  spanProcessorFactory: (exporter) => new SimpleSpanProcessor(exporter),
 }) as InMemorySpanExporter;
 
 const util = require("util");
diff --git a/packages/trace-schema/src/trace-schema.ts b/packages/trace-schema/src/trace-schema.ts
@@ -16,6 +16,7 @@ export interface TraceSchemaInput {
   adapter: BaseAdapter;
   exporterConfig?: SetupOtelInput["exporterConfig"];
   instrumentations?: SetupOtelInput["instrumentations"];
+  spanProcessorFactory?: SetupOtelInput["spanProcessorFactory"];
   shouldExportSchema?: boolean;
   // If you have large schema, enable this so you still get traces, but not one for each field on each type.
   shouldExcludeTypeFields?: boolean;
@@ -26,12 +27,13 @@ export function traceSchema({
   exporterConfig,
   adapter,
   instrumentations,
+  spanProcessorFactory,
   shouldExportSchema = true,
   shouldExcludeTypeFields = false,
 }: TraceSchemaInput): { schema: GraphQLSchema; schemaHash: string } {
   debug("Tracing schema");
 
-  setupOtel({ exporterConfig, instrumentations });
+  setupOtel({ exporterConfig, instrumentations, spanProcessorFactory });
 
   const directive = traceDirective();
 
diff --git a/plugins/apollo/tests/plugin-apollo.test.ts b/plugins/apollo/tests/plugin-apollo.test.ts
@@ -1,5 +1,6 @@
 import {
   InMemorySpanExporter,
+  SimpleSpanProcessor,
   setupOtel,
 } from "@graphql-debugger/opentelemetry";
 
@@ -11,6 +12,7 @@ import { graphqlDebuggerPlugin } from "../src";
 
 const exporter = setupOtel({
   inMemory: true,
+  spanProcessorFactory: (exporter) => new SimpleSpanProcessor(exporter),
 }) as InMemorySpanExporter;
 
 const sleep = util.promisify(setTimeout);
diff --git a/plugins/express/tests/plugin-express.test.ts b/plugins/express/tests/plugin-express.test.ts
@@ -1,5 +1,6 @@
 import {
   InMemorySpanExporter,
+  SimpleSpanProcessor,
   TRACER_NAME,
   setupOtel,
 } from "@graphql-debugger/opentelemetry";
@@ -12,6 +13,7 @@ import { HttpServerAttributeNames } from "../src/attributes";
 
 const exporter = setupOtel({
   inMemory: true,
+  spanProcessorFactory: (exporter) => new SimpleSpanProcessor(exporter),
 }) as unknown as InMemorySpanExporter;
 
 const app = express();
diff --git a/plugins/yoga/tests/plugin-graphql-yoga.test.ts b/plugins/yoga/tests/plugin-graphql-yoga.test.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
