Gentrace Documentation

Want to see the complete code? Check out our Next.js + Gentrace example on GitHub.

Next.js applications require a special setup to integrate Gentrace due to the framework’s built-in OpenTelemetry support. This guide covers the Next.js-specific configuration.

Prerequisites

Next.js 14.0.0+ (with App Router)
Node.js 18.17.0+
A Gentrace API key

Installation

npm install @vercel/otel @opentelemetry/sdk-trace-node@^1 @opentelemetry/api-logs@0.55.0 @opentelemetry/instrumentation@0.52.1 @opentelemetry/sdk-logs@0.55.0 gentrace

yarn add @vercel/otel @opentelemetry/sdk-trace-node@^1 @opentelemetry/api-logs@0.55.0 @opentelemetry/instrumentation@0.52.1 @opentelemetry/sdk-logs@0.55.0 gentrace

pnpm add @vercel/otel @opentelemetry/sdk-trace-node@^1 @opentelemetry/api-logs@0.55.0 @opentelemetry/instrumentation@0.52.1 @opentelemetry/sdk-logs@0.55.0 gentrace

It’s critical to use @opentelemetry/sdk-trace-node v1 (not v2) due to functionality and type compatibility issues with v2.

Configuration

Next.js requires a two-part setup to avoid conflicts between OpenTelemetry configurations.

Step 1: Create instrumentation.ts

Create an instrumentation.ts file in your project root:

instrumentation.ts

import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-node';
import {
  OTLPHttpJsonTraceExporter,
  registerOTel,
} from '@vercel/otel';

const traceExporter = new OTLPHttpJsonTraceExporter({
  url: 'https://gentrace.ai/api/otel/v1/traces',
  headers: {
    authorization: `Bearer ${process.env.GENTRACE_API_KEY}`,
  },
});

export function register() {
  registerOTel({
    serviceName: 'your-app-name',
    spanProcessors: [
      new SimpleSpanProcessor(traceExporter),
      new SimpleSpanProcessor(new ConsoleSpanExporter()),
    ],
  });
}

Next.js automatically runs instrumentation.ts during server startup. No additional configuration is needed.

Step 2: Initialize Gentrace SDK

In your API routes, initialize Gentrace with otelSetup: false:

app/api/your-route/route.ts

import { init } from 'gentrace';

// Initialize once at the top of your route file
init({
  apiKey: process.env.GENTRACE_API_KEY!,
  otelSetup: false, // Critical: Prevents conflicts with Vercel's OTEL
});

Always set otelSetup: false in Next.js to avoid conflicts between Gentrace’s OpenTelemetry setup and Vercel’s.

Usage Example

Here’s a complete example of an API route with Gentrace tracing:

app/api/completion/route.ts

import { init, interaction } from 'gentrace';
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { NextRequest } from 'next/server';

// Initialize Gentrace
init({
  apiKey: process.env.GENTRACE_API_KEY!,
  otelSetup: false,
});

export async function POST(req: NextRequest) {
  const { prompt } = await req.json();

  // Wrap your AI calls with interaction()
  const response = await interaction(
    'completion-request',
    async () => {
      return streamText({
        model: openai('gpt-4o-mini'),
        prompt,
      });
    },
    {
      pipelineId: process.env.GENTRACE_PIPELINE_ID!,
    },
  );

  return response.toDataStreamResponse();
}

Environment Variables

Add these to your .env.local:

.env.local

GENTRACE_API_KEY=your-api-key-here
GENTRACE_PIPELINE_ID=your-pipeline-id-here

Streaming Support

Next.js with Vercel AI SDK supports streaming responses. Gentrace automatically traces streaming interactions:

const response = await interaction(
  'streaming-conversation',
  async () => {
    return streamText({
      model: openai('gpt-4o-mini'),
      messages: conversation,
    });
  },
  {
    pipelineId: process.env.GENTRACE_PIPELINE_ID!,
  },
);

// Return streaming response to client
return response.toDataStreamResponse();

Using with Sentry

If you’re using Sentry in your Next.js application, the standard instrumentation.ts approach won’t work due to conflicts between Sentry’s OpenTelemetry configuration and the default setup. Sentry overrides many of the default OpenTelemetry SDK configurations, which can prevent traces from being sent to Gentrace.

Important Version Compatibility:

Sentry SDK versions ≤9.x use OpenTelemetry v1
Sentry SDK versions 10.0.0+ use OpenTelemetry v2

Ensure your OpenTelemetry dependencies match your Sentry version to avoid compatibility issues.

The workaround is to configure Gentrace directly within Sentry’s initialization using the openTelemetrySpanProcessors option:

Configuration

Create or update your Sentry configuration files:

sentry.server.config.ts

import * as Sentry from '@sentry/nextjs';
import {
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} from '@opentelemetry/sdk-trace-base';
import { OTLPHttpJsonTraceExporter } from '@vercel/otel';

// Configure Gentrace trace exporter
const traceExporter = new OTLPHttpJsonTraceExporter({
  url: 'https://gentrace.ai/api/otel/v1/traces',
  headers: {
    authorization: `Bearer ${process.env.GENTRACE_API_KEY}`,
  },
});

Sentry.init({
  dsn: process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0,

  // Add Gentrace to Sentry's OpenTelemetry span processors
  openTelemetrySpanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter()), // Optional: for debugging
    new SimpleSpanProcessor(traceExporter), // Send traces to Gentrace
  ],
});

Do not use both the instrumentation.ts approach and the Sentry configuration approach simultaneously. This will cause conflicts and may result in missing or duplicated traces.

Checking Your Sentry Version

To check which version of Sentry you’re using:

npm list @sentry/nextjs

Then ensure your OpenTelemetry dependencies match:

For Sentry ≤9.x: Use @opentelemetry/sdk-trace-base@^1
For Sentry 10.0.0+: Use @opentelemetry/sdk-trace-base@^2

Additional Resources

Installation Guide - General SDK setup
Initialization Reference - Detailed init() options
OpenTelemetry Setup - Understanding OTEL configuration

Getting started

Error analysis

Tracing

Evaluation

Integrations

Administration

Reference

SDK Entities

Next.js

Prerequisites

Installation

Configuration

Step 1: Create instrumentation.ts

Step 2: Initialize Gentrace SDK

Usage Example

Environment Variables

Streaming Support

Using with Sentry

Configuration

Checking Your Sentry Version

Additional Resources

​Prerequisites

​Installation

​Configuration

​Step 1: Create instrumentation.ts

​Step 2: Initialize Gentrace SDK

​Usage Example

​Environment Variables

​Streaming Support

​Using with Sentry

​Configuration

​Checking Your Sentry Version

​Additional Resources

​Related Resources

Prerequisites

Installation

Configuration

Step 1: Create instrumentation.ts

Step 2: Initialize Gentrace SDK

Usage Example

Environment Variables

Streaming Support

Using with Sentry

Configuration

Checking Your Sentry Version

Additional Resources

Related Resources