Skip to main content

​
Overview

Connect your Next.js application to Kubiks using the Vercel OpenTelemetry SDK with HTTP exporters. This setup works for any deployment platform (not just Vercel) and provides complete observability for your app.

​
Installation

Install the required OpenTelemetry packages: 
npm install @vercel/otel @opentelemetry/api @opentelemetry/api-logs

​
Environment Variables

Add these environment variables to your deployment configuration:
.env.local
# Required: Your Kubiks API key (get this from kubiks.app/connect)
KUBIKS_API_KEY=your_api_key_here

# Required: OTLP endpoint
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.kubiks.app

# Optional: Set service name (defaults to your app name)
OTEL_SERVICE_NAME=my-nextjs-app

# Optional: Environment (production, staging, development)
OTEL_ENVIRONMENT=production

​
Configuration

Create an instrumentation.ts file in your project root (same level as app/ or pages/):
instrumentation.ts
import { OTLPHttpProtoTraceExporter, registerOTel } from '@vercel/otel';

export function register() {
  registerOTel({
    serviceName: process.env.OTEL_SERVICE_NAME || 'nextjs-app',
    traceExporter: new OTLPHttpProtoTraceExporter({
      url: "https://ingest.kubiks.app/v1/traces",
      headers: {
        "X-Kubiks-Key": process.env.KUBIKS_API_KEY!,
      },
    }),
  });
}
Next.js automatically loads instrumentation.ts when the application starts. No additional imports needed!

​
Environment-Specific Configuration

Set environment variables based on your deployment platform:
  • Vercel
  • Docker
  • Railway / Render
  • Self-Hosted
Add environment variables in your Vercel project settings:
  1. Go to Settings → Environment Variables
  2. Add KUBIKS_API_KEY with your API key
  3. Add OTEL_EXPORTER_OTLP_ENDPOINT with value https://ingest.kubiks.app
  4. Add OTEL_SERVICE_NAME with your app name
  5. Deploy your application

​
Get Your API Key

1

Navigate to Connect Page

Go to kubiks.app/connect in your dashboard
2

Create API Key

Click Create API Key in the OpenTelemetry Ingestion section
3

Copy the Key

Copy the generated API key and add it to your environment variables

​
Verify Setup

Once configured, your Next.js app will automatically send traces and logs to Kubiks. To verify:
  1. Start your development server or deploy your app
  2. Make some requests to your application
  3. Check your Kubiks dashboard for traces and logs
Traces appear in real-time. If you don’t see data after a few seconds, check your API key and endpoint configuration.

​
What Gets Tracked

The @vercel/otel package automatically instruments:
  • All incoming HTTP requests
  • Request/response headers
  • Status codes and response times
  • URL paths and query parameters
  • Server-side rendering (SSR)
  • API routes
  • Server components
  • Middleware
  • Static generation
  • fetch() calls to external APIs
  • Database queries (when instrumented)
  • Third-party service calls
  • Request duration
  • Time to first byte (TTFB)
  • Server-side rendering time
  • API response times

​
Instrument Your Dependencies

Enhance observability by adding Kubiks OpenTelemetry SDKs for popular frameworks:

Drizzle ORM

Trace all database queries and transactions

Better Auth

Monitor authentication flows and sessions

Resend

Track email delivery and operations

Upstash QStash

Monitor message queue operations

Autumn Billing

Trace billing and payment flows

View All Integrations

Explore all available SDKs

​
Troubleshooting

Check these common issues:
  1. Verify KUBIKS_API_KEY is set correctly
  2. Confirm OTEL_EXPORTER_OTLP_ENDPOINT is https://ingest.kubiks.app
  3. Ensure instrumentationHook: true is in next.config.ts
  4. Check that instrumentation.ts is in your project root
  5. Restart your development server after config changes
Make sure:
  1. File is named exactly instrumentation.ts (or .js)
  2. File is in project root (same level as app/ or pages/)
  3. experimental.instrumentationHook is enabled in Next.js config
  4. You’re using Next.js 13.2 or later
  1. Double-check your API key from kubiks.app/connect
  2. Ensure no extra spaces or quotes in your .env.local
  3. Verify environment variables are loaded (check process.env.KUBIKS_API_KEY)
  4. For production, confirm variables are set in your deployment platform
The SDK uses sampling by default. To see all traces in development:
instrumentation.ts
import { registerOTel } from '@vercel/otel';

export function register() {
  registerOTel({
    serviceName: process.env.OTEL_SERVICE_NAME || 'nextjs-app',
    // Sample all traces in development
    ...(process.env.NODE_ENV === 'development' && {
      tracesSampleRate: 1.0,
    }),
  });
}

​
Next Steps

View Traces

Check your dashboard for real-time traces

Add Database Tracing

Instrument your database queries

Vercel Integration

Using Vercel? Try our native integration

OpenTelemetry Docs

Explore all integrations