Logging Configuration Guide

Looking for environment variables? See the Environment Variables Reference for complete configuration.

This guide covers the logging system configuration for TinyKit Pro.

Overview

TinyKit Pro uses environment variables for configuration across multiple environments:

Local Development (your machine)
Preview/Staging (Vercel preview deployments)
Production (Vercel production deployment)

Required Environment Variables

Convex Configuration

IMPORTANT: Convex requires manual environment setup for each deployment.

# ============================================
# REQUIRED - App will not function without these
# ============================================
npx convex env set BETTER_AUTH_SECRET "your-random-secret-here"  # Required for auth - auto-generated by setup wizard
npx convex env set SITE_URL "http://localhost:3000"              # Required for auth callbacks
npx convex env set STRIPE_SECRET_KEY "sk_test_..."               # Required for billing features
npx convex env set STRIPE_WEBHOOKS_SECRET "whsec_..."            # Required for Stripe webhook verification

# ============================================
# OPTIONAL - Features gracefully disabled if not set
# ============================================
npx convex env set RESEND_API_KEY "re_..."      # Optional - email features disabled if not set
npx convex env set RESEND_TEST_MODE "true"      # Optional - use sandbox mode for email testing

# Logging (optional - defaults to INFO if not set)
npx convex env set CONVEX_ENV "development"     # development | preview | staging | production
npx convex env set LOG_LEVEL "DEBUG"            # DEBUG | INFO | WARN | ERROR

# ============================================
# PRODUCTION - Update these when deploying
# ============================================
npx convex env set SITE_URL "https://yourdomain.com"
npx convex env set CONVEX_ENV "production"

Email Configuration: Email settings (support email, email name, etc.) are configured through Admin > Site Settings > Email.

Next.js Configuration

Create .env.local from the example file:

# Core configuration
CONVEX_DEPLOYMENT=dev:your-project-name
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site
NEXT_PUBLIC_SITE_URL=http://localhost:3000
SITE_DOMAIN=localhost

# Note: Stripe keys go in Convex environment (no frontend keys needed)
# npx convex env set STRIPE_SECRET_KEY sk_test_...

Logging System Configuration

Backend Logging (Convex)

The Convex backend uses the CONVEX_ENV variable for automatic log level detection:

# Required: Set environment type
npx convex env set CONVEX_ENV "development"  # or "production"

# Optional: Override default log level
npx convex env set LOG_LEVEL "DEBUG"  # DEBUG, INFO, WARN, ERROR

Default Log Levels by Environment:

development → DEBUG (all logs)
preview/staging → INFO (info and above)
production → ERROR (errors only)

Frontend Logging (Next.js)

Frontend logging auto-detects environment from NODE_ENV and VERCEL_ENV:

# Optional: Override auto-detection
NEXT_PUBLIC_LOG_LEVEL=DEBUG  # DEBUG, INFO, WARN, ERROR

Auto-Detection Priority:

NEXT_PUBLIC_LOG_LEVEL (manual override)
NEXT_PUBLIC_VERCEL_ENV (Vercel deployments)
NODE_ENV (standard Next.js)
Default to INFO

Environment-Specific Setup

Local Development

Convex Setup:

npx convex env set CONVEX_ENV "development"
npx convex env set LOG_LEVEL "DEBUG"  # optional

Next.js Setup (.env.local):

NODE_ENV=development  # set by Next.js automatically
NEXT_PUBLIC_LOG_LEVEL=DEBUG  # optional override

Vercel Preview (Staging)

Convex Setup:

# Switch to preview deployment first
npx convex env set CONVEX_ENV "preview"

Vercel Environment Variables:

# Vercel sets these automatically:
VERCEL_ENV=preview
NEXT_PUBLIC_VERCEL_ENV=preview

# Optional override in Vercel dashboard:
NEXT_PUBLIC_LOG_LEVEL=INFO

Production

Convex Setup:

# Switch to production deployment first
npx convex env set CONVEX_ENV "production"
npx convex env set LOG_LEVEL "WARN"  # optional, if ERROR is too restrictive

Vercel Environment Variables:

# Vercel sets these automatically:
VERCEL_ENV=production
NEXT_PUBLIC_VERCEL_ENV=production
NODE_ENV=production

# Optional override in Vercel dashboard:
NEXT_PUBLIC_LOG_LEVEL=ERROR

Logging Usage Examples

Backend (Convex)

import { createLogger, getDefaultLogLevel } from "../lib/logger";

// Use environment-based default
const logger = createLogger(getDefaultLogLevel());

export const myMutation = mutation({
  handler: async (ctx, args) => {
    logger.time("mutation-execution");
    logger.info("Processing request", { userId: args.userId });

    try {
      logger.debug("Step 1 completed", { data });
      // ... business logic
    } catch (error) {
      logger.error("Mutation failed", error);
      throw error;
    } finally {
      logger.timeEnd("mutation-execution");
    }
  },
});

// Runtime log level control (advanced)
export const debugMutation = mutation({
  args: {
    logLevel: v.optional(logLevel),
    // ... other args
  },
  handler: async (ctx, args) => {
    const logger = createLogger(args.logLevel);
    logger.debug("Debug mode enabled", args);
  },
});

Frontend (Next.js)

import { logger, devLogger, getCurrentLogLevel } from "@/lib/logger";

function MyComponent() {
  logger.debug("Component rendered", { props });

  // Development-only logging
  devLogger.debug("Debug info that never shows in production");

  // Conditional expensive logging
  if (getCurrentLogLevel() === "DEBUG") {
    const expensiveData = computeExpensiveDebugInfo();
    logger.debug("Expensive debug data", expensiveData);
  }

  const handleAction = async () => {
    logger.info("User action started");

    try {
      await someApiCall();
      logger.info("Action completed successfully");
    } catch (error) {
      logger.error("Action failed", error);
    }
  };
}

Troubleshooting

Common Issues

Issue: Convex logs not appearing in development

# Check environment setting
npx convex env list | grep CONVEX_ENV

# Set if missing
npx convex env set CONVEX_ENV "development"

Issue: Too many logs in production

# Check current log level
npx convex env list | grep LOG_LEVEL

# Set more restrictive level
npx convex env set LOG_LEVEL "ERROR"

Issue: Frontend logs not appearing

// Check current log level in browser console
import { getCurrentLogLevel } from "@/lib/logger";
console.log("Current log level:", getCurrentLogLevel());

Log Level Reference

Level	Convex Backend	Frontend	Use Case
DEBUG	All development logs	All development logs	Detailed debugging
INFO	Important operations	User actions	General information
WARN	Potential issues	Deprecations	Warnings
ERROR	Errors only	Errors only	Error tracking

Security Notes

Never log sensitive data (passwords, tokens, PII)
Use structured logging for better parsing
Consider log retention policies for production
Monitor log volume to avoid cost issues

Next Steps

Run the setup wizard: bun setup
Configure Convex environment: npx convex env set CONVEX_ENV "development"
Copy .env.local.example to .env.local and fill in values
Test logging in development: bun dev
Deploy and configure production environment variables

See Environment Variables Reference for complete configuration.

Logging Configuration Guide

On this page