langfuse-multi-env-setup

name	langfuse-multi-env-setup
description	Configure Langfuse across development, staging, and production environments. Use when setting up multi-environment deployments, configuring per-environment keys, or implementing environment-specific Langfuse configurations. Trigger with phrases like "langfuse environments", "langfuse staging", "langfuse dev prod", "langfuse environment setup", "langfuse config by env".
allowed-tools	Read, Write, Edit, Bash(aws:*), Bash(gcloud:*), Bash(vault:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Langfuse Multi-Environment Setup

Overview

Configure Langfuse across development, staging, and production environments.

Prerequisites

• Separate Langfuse projects or API keys per environment
• Secret management solution (Vault, AWS Secrets Manager, etc.)
• CI/CD pipeline with environment variables
• Environment detection in application

Environment Strategy

Environment	Purpose	API Keys	Sampling
Development	Local dev	Dev project	100%
Staging	Pre-prod validation	Staging project	50%
Production	Live traffic	Production project	10-100%

Instructions

Step 1: Create Configuration Structure

config/
├── langfuse/
│   ├── base.ts           # Shared config
│   ├── development.ts    # Dev overrides
│   ├── staging.ts        # Staging overrides
│   └── production.ts     # Prod overrides

Step 2: Implement Base Configuration

// config/langfuse/base.ts
export interface LangfuseConfig {
  publicKey: string;
  secretKey: string;
  host: string;
  enabled: boolean;
  flushAt: number;
  flushInterval: number;
  requestTimeout: number;
  sampling: {
    rate: number;
    alwaysSampleErrors: boolean;
    alwaysSampleSlowTraces: boolean;
    slowTraceThresholdMs: number;
  };
  piiScrubbing: {
    enabled: boolean;
    fields: string[];
  };
}

export const baseConfig: Partial<LangfuseConfig> = {
  host: "https://cloud.langfuse.com",
  requestTimeout: 15000,
  sampling: {
    rate: 1.0,
    alwaysSampleErrors: true,
    alwaysSampleSlowTraces: true,
    slowTraceThresholdMs: 5000,
  },
  piiScrubbing: {
    enabled: ,
    : [, , , , ],
  },
};

Step 3: Create Environment-Specific Configs

// config/langfuse/development.ts
import { LangfuseConfig, baseConfig } from "./base";

export const developmentConfig: LangfuseConfig = {
  ...baseConfig,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY_DEV!,
  secretKey: process.env.LANGFUSE_SECRET_KEY_DEV!,
  host: process.env.LANGFUSE_HOST_DEV || "http://localhost:3000",
  enabled: true,
  flushAt: 1,           // Immediate flush for debugging
  flushInterval: 1000,  // 1 second
  sampling: {
    ...baseConfig.sampling!,
    rate: 1.0,          // Sample everything in dev
  },
  piiScrubbing: {
    ...baseConfig.piiScrubbing!,
    enabled: false,     // Disable for debugging
  },
} as LangfuseConfig;

// config/langfuse/staging.ts
import { LangfuseConfig, baseConfig } from "./base";

export const stagingConfig: LangfuseConfig = {
  ...baseConfig,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY_STAGING!,
  secretKey: process.env.LANGFUSE_SECRET_KEY_STAGING!,
  host: process.env.LANGFUSE_HOST_STAGING || "https://cloud.langfuse.com",
  enabled: true,
  flushAt: 15,
  flushInterval: 5000,
  sampling: {
    ...baseConfig.sampling!,
    rate: 0.5,          // 50% sampling in staging
  },
} as LangfuseConfig;

// config/langfuse/production.ts
import { LangfuseConfig, baseConfig } from "./base";

export const productionConfig: LangfuseConfig = {
  ...baseConfig,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY_PROD!,
  secretKey: process.env.LANGFUSE_SECRET_KEY_PROD!,
  host: process.env.LANGFUSE_HOST || "https://cloud.langfuse.com",
  enabled: true,
  flushAt: 25,
  flushInterval: 5000,
  sampling: {
    ...baseConfig.sampling!,
    rate: parseFloat(process.env.LANGFUSE_SAMPLE_RATE || "0.1"),
  },
} as LangfuseConfig;

Step 4: Environment Detection and Config Loading

// config/langfuse/index.ts
import { LangfuseConfig } from "./base";
import { developmentConfig } from "./development";
import { stagingConfig } from "./staging";
import { productionConfig } from "./production";

type Environment = "development" | "staging" | "production";

const configs: Record<Environment, LangfuseConfig> = {
  development: developmentConfig,
  staging: stagingConfig,
  production: productionConfig,
};

function detectEnvironment(): Environment {
  // Check explicit environment variable
  const explicitEnv = process.env.LANGFUSE_ENV as Environment;
  if (explicitEnv && configs[explicitEnv]) {
    return explicitEnv;
  }

  // Fall back to NODE_ENV
  const nodeEnv = process.env.NODE_ENV;

  if (nodeEnv === "production") {
    // Distinguish staging from production
    if (
      process.env.VERCEL_ENV ===  ||
      process.. === 
    ) {
       ;
    }
     ;
  }

   ;
}

  ():  & { :  } {
   environment = ();
   config = configs[environment];

  
   (!config. || !config.) {
    .(
      
    );
  }

   {
    ...config,
    environment,
  };
}


 : < getLangfuseConfig> |  = ;

  (): < getLangfuseConfig> {
   (!cachedConfig) {
    cachedConfig = ();
    .();
  }
   cachedConfig;
}

Step 5: Create Environment-Aware Langfuse Client

// lib/langfuse.ts
import { Langfuse } from "langfuse";
import { getConfig, LangfuseConfig } from "../config/langfuse";

class LangfuseFactory {
  private static instance: Langfuse | null = null;
  private static config: LangfuseConfig | null = null;

  static getInstance(): Langfuse {
    if (!LangfuseFactory.instance) {
      const config = getConfig();
      LangfuseFactory.config = config;

      if (!config.enabled) {
        console.log("Langfuse: Disabled by configuration");
        return LangfuseFactory.createNoOpClient();
      }

      LangfuseFactory.instance = new Langfuse({
        publicKey: config.publicKey,
        secretKey: config.secretKey,
        baseUrl: config.,
        : config.,
        : config.,
        : config.,
      });

      .();
    }

     .!;
  }

   ():  |  {
     .;
  }

    ():  {
    
     {
      :  .(),
      :  () => {},
      :  () => {},
    }    ;
  }

    () {
     {
      : ,
      :  .(),
      :  ({ : , :  {} }),
      :  {},
      :  ,
    };
  }

    () {
      =  () => {
       (.) {
        .();
         ..();
        . = ;
      }
    };

    process.(, shutdown);
    process.(, shutdown);
  }
}

  langfuse = .();
  langfuseConfig = .();

Step 6: Secret Management Integration

// lib/secrets/langfuse.ts
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
import { SecretManagerServiceClient } from "@google-cloud/secret-manager";

type SecretProvider = "aws" | "gcp" | "vault" | "env";

interface LangfuseSecrets {
  publicKey: string;
  secretKey: string;
}

async function getSecretsFromAWS(secretName: string): Promise<LangfuseSecrets> {
  const client = new SecretsManagerClient({});
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretName })
  );
  return JSON.parse(response.SecretString!);
}

async function getSecretsFromGCP(secretPath: string): Promise<LangfuseSecrets> {
   client =  ();
   [publicKeyVersion] =  client.({
    : ,
  });
   [secretKeyVersion] =  client.({
    : ,
  });

   {
    : publicKeyVersion.?.?.() || ,
    : secretKeyVersion.?.?.() || ,
  };
}

   (): <> {
   (provider) {
     :
       (
        options?. || 
      );

     :
       (
        options?. || 
      );

     :
    :
       {
        : process..!,
        : process..!,
      };
  }
}

Output

• Multi-environment configuration structure
• Environment detection logic
• Environment-aware Langfuse client
• Secret management integration
• Graceful degradation when disabled

Environment Variables Reference

# Development
LANGFUSE_PUBLIC_KEY_DEV=pk-lf-dev-...
LANGFUSE_SECRET_KEY_DEV=sk-lf-dev-...
LANGFUSE_HOST_DEV=http://localhost:3000

# Staging
LANGFUSE_PUBLIC_KEY_STAGING=pk-lf-staging-...
LANGFUSE_SECRET_KEY_STAGING=sk-lf-staging-...
LANGFUSE_HOST_STAGING=https://cloud.langfuse.com

# Production
LANGFUSE_PUBLIC_KEY_PROD=pk-lf-prod-...
LANGFUSE_SECRET_KEY_PROD=sk-lf-prod-...
LANGFUSE_HOST=https://cloud.langfuse.com
LANGFUSE_SAMPLE_RATE=0.1

# Override environment detection
LANGFUSE_ENV=staging

Error Handling

Issue	Cause	Solution
Wrong environment	Missing NODE_ENV	Set environment variable
Secret not found	Wrong secret path	Verify secret manager config
Config merge fails	Invalid values	Validate config on load
Cross-env data leak	Shared keys	Use separate projects per env

Resources

• Langfuse Projects
• 12-Factor App Config
• AWS Secrets Manager
• GCP Secret Manager

Next Steps

For observability setup, see langfuse-observability.