Node.js / Backend Quick Start

Server-side tracking uses @grainql/analytics-web, a separate package from @grainql/tag. Grain Tag is for browser-side analytics. For browser tracking, see Installation.

Use Grain Analytics on your backend to track API calls, background jobs, and server-side events.

Install the Package

npm

npm install @grainql/analytics-web

yarn

yarn add @grainql/analytics-web

pnpm

pnpm add @grainql/analytics-web

Initialize the SDK

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY // Get this from your dashboard
});

Keep your secret key safe! Never commit it to version control or expose it in client-side code. Use environment variables.

Track Server-Side Events

// Track an API request
app.post('/api/users', async (req, res) => {
  // Your logic...

  await grain.track('api_request', {
    endpoint: '/api/users',
    method: 'POST',
    user_id: req.user?.id,
    status: 200
  }, { flush: true }); // Flush immediately for serverless

  res.json({ success: true });
});

Serverless environments: Use { flush: true } to send events immediately before the function terminates. Otherwise, events might not get sent.

Track Background Jobs

// Track a cron job or background task
async function processOrders() {
  const orders = await getOrders();

  for (const order of orders) {
    await processOrder(order);

    await grain.track('order_processed', {
      order_id: order.id,
      total: order.total,
      items_count: order.items.length
    });
  }

  // Flush at the end of the batch
  await grain.flush();
}

Use Remote Configuration

Control server-side behavior without redeploying:

// Check if a feature is enabled
const isNewAlgorithmEnabled = grain.getConfig('use_new_algorithm');

if (isNewAlgorithmEnabled === 'true') {
  result = await newAlgorithm(data);
} else {
  result = await oldAlgorithm(data);
}

// Get configuration values
const maxRetries = parseInt(grain.getConfig('max_retries') || '3');
const timeout = parseInt(grain.getConfig('api_timeout') || '5000');

Express.js Middleware

Track all requests automatically:

import express from 'express';
import { createGrainAnalytics } from '@grainql/analytics-web';

const app = express();
const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

// Middleware to track all requests
app.use((req, res, next) => {
  const startTime = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - startTime;

    grain.track('api_request', {
      path: req.path,
      method: req.method,
      status: res.statusCode,
      duration,
      user_id: req.user?.id
    });
  });

  next();
});

// Your routes...
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

// Flush events before shutdown
process.on('SIGTERM', async () => {
  await grain.flush();
  process.exit(0);
});

app.listen(3000);

Fastify Plugin

import Fastify from 'fastify';
import { createGrainAnalytics } from '@grainql/analytics-web';

const fastify = Fastify();
const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

// Track requests
fastify.addHook('onResponse', async (request, reply) => {
  await grain.track('api_request', {
    path: request.url,
    method: request.method,
    status: reply.statusCode,
    duration: reply.getResponseTime()
  });
});

// Flush on shutdown
fastify.addHook('onClose', async () => {
  await grain.flush();
});

fastify.listen({ port: 3000 });

AWS Lambda Example

import { Handler } from 'aws-lambda';
import { createGrainAnalytics } from '@grainql/analytics-web';

// Initialize outside handler for connection reuse
const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

export const handler: Handler = async (event, context) => {
  try {
    // Your logic...
    const result = await processEvent(event);

    // Track with immediate flush for Lambda
    await grain.track('lambda_invoked', {
      function_name: context.functionName,
      event_type: event.type,
      success: true
    }, { flush: true });

    return { statusCode: 200, body: JSON.stringify(result) };
  } catch (error) {
    await grain.track('lambda_error', {
      function_name: context.functionName,
      error: error.message
    }, { flush: true });

    throw error;
  }
};

Lambda optimization: Initialize the Grain client outside your handler function so it’s reused across invocations. This improves performance and reduces cold starts.

Vercel Serverless Functions

// api/users.ts
import type { VercelRequest, VercelResponse } from '@vercel/node';
import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

export default async function handler(req: VercelRequest, res: VercelResponse) {
  // Your logic...

  await grain.track('api_request', {
    path: req.url,
    method: req.method
  }, { flush: true });

  res.json({ success: true });
}

Track User Events Server-Side

Associate events with specific users:

// When a user signs up
app.post('/api/signup', async (req, res) => {
  const user = await createUser(req.body);

  // Identify the user
  grain.identify(user.id, {
    email: user.email,
    name: user.name,
    plan: 'free',
    signup_date: new Date().toISOString()
  });

  // Track signup event
  await grain.track('user_signed_up', {
    method: 'email',
    source: req.query.utm_source
  }, { flush: true });

  res.json({ user });
});

Error Tracking

Track backend errors to understand failure patterns:

app.use((err, req, res, next) => {
  // Log to Grain
  grain.track('server_error', {
    error: err.message,
    stack: err.stack,
    path: req.path,
    method: req.method,
    user_id: req.user?.id
  });

  res.status(500).json({ error: 'Internal server error' });
});

Testing Your Integration

// test.ts
import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!,
  debug: true // Enable debug logging
});

async function test() {
  await grain.track('test_event', {
    timestamp: new Date().toISOString()
  }, { flush: true });

  console.log('Event sent! Check your dashboard.');
}

test();

Run it:

node test.ts

Check your dashboard to see the event come in.

What’s Next?

Core API Reference

See all available methods and options

Authentication

Learn about server-side authentication

Query API

Query your analytics data programmatically

Configuration Guide

Advanced configuration options

Production checklist:

Store secret key in environment variables
Use { flush: true } for serverless functions
Set up error handling and retry logic
Monitor batch queue size in long-running processes

Getting Started

Integrations

Tracking & Events

Dashboard

MCP Server

Guides

React SDK

Advanced

Node.js / Backend Quick Start

Install the Package

Initialize the SDK

Track Server-Side Events

Track Background Jobs

Use Remote Configuration

Express.js Middleware

Fastify Plugin

AWS Lambda Example

Vercel Serverless Functions

Track User Events Server-Side

Error Tracking

Testing Your Integration

What’s Next?

Core API Reference

Authentication

Query API

Configuration Guide

​Install the Package

​Initialize the SDK

​Track Server-Side Events

​Track Background Jobs

​Use Remote Configuration

​Express.js Middleware

​Fastify Plugin

​AWS Lambda Example

​Vercel Serverless Functions

​Track User Events Server-Side

​Error Tracking

​Testing Your Integration

​What’s Next?

Core API Reference

Authentication

Query API

Configuration Guide

Install the Package

Initialize the SDK

Track Server-Side Events

Track Background Jobs

Use Remote Configuration

Express.js Middleware

Fastify Plugin

AWS Lambda Example

Vercel Serverless Functions

Track User Events Server-Side

Error Tracking

Testing Your Integration

What’s Next?