LANGFUSE_DEBUGGER_COMPONENT.md

Overview

The LangfuseDebugger component is a development tool that provides debugging and testing capabilities for Langfuse tracing integration. It offers real-time status checking, connection testing, and detailed error reporting for troubleshooting Langfuse configuration issues.

Purpose

• Debug Tool: Development interface for Langfuse integration testing
• Connection Testing: Verify Langfuse service connectivity and configuration
• Status Monitoring: Real-time display of Langfuse initialization status
• Error Diagnosis: Detailed error reporting for troubleshooting issues

Key Features

Status Checking

• Initialization Status: Check if Langfuse client is properly initialized
• Configuration Display: Show public key, base URL, and environment details
• Auto-Check: Automatic status check on component mount

Connection Testing

• Live Testing: Test actual connection to Langfuse service
• Async Operations: Handle asynchronous connection testing with loading states
• Result Display: Clear success/failure indicators with actionable feedback

Developer Tools

• Console Integration: Provides console commands for manual testing
• Error Handling: Comprehensive error capture and display
• Debug Information: Detailed technical information for troubleshooting

Component Interface

interface LangfuseDebuggerState {
  status: any | null;           // Current Langfuse status
  testResult: boolean | null;   // Connection test result
  testing: boolean;             // Test in progress flag
  error: string | null;         // Error message
}

Core Functionality

1. Status Debugging

const handleDebug = () => {
  console.log('Debug button clicked');
  setError(null);
  try {
    const debugStatus = debugLangfuseStatus();
    console.log('Debug status:', debugStatus);
    setStatus(debugStatus);
  } catch (err) {
    console.error('Debug error:', err);
    setError(err instanceof Error ? err.message : 'Failed to get debug status');
  }
};

// Auto-run debug on component mount
React.useEffect(() => {
  handleDebug();
}, []);

2. Connection Testing

const handleTest = async () => {
  console.log('Test button clicked');
  setTesting(true);
  setTestResult(null);
  setError(null);
  
  try {
    const result = await testLangfuseConnection();
    console.log('Test result:', result);
    setTestResult(result);
  } catch (error) {
    console.error('Test error:', error);
    setError(error instanceof Error ? error.message : 'Test failed');
    setTestResult(false);
  } finally {
    setTesting(false);
  }
};

3. Status Display

// Status information panel
{status && (
  <div className="bg-white p-4 rounded border">
    <h3 className="font-semibold mb-2">Current Status:</h3>
    <div className="space-y-1 text-sm font-mono">
      <div>Initialized: {status.initialized ? '✅ Yes' : '❌ No'}</div>
      <div>Public Key: {status.publicKey ? '✅ Available' : '❌ Missing'}</div>
      <div>Base URL: {status.baseUrl}</div>
      <div>Environment: {typeof window === 'undefined' ? 'Server' : 'Client'}</div>
      {status.publicKey && (
        <div>Key Preview: {status.publicKey}</div>
      )}
    </div>
  </div>
)}

4. Test Results Display

// Test result feedback
{testResult !== null && (
  <div className={`p-4 rounded ${testResult ? 'bg-green-100' : 'bg-red-100'}`}>
    <h3 className="font-semibold mb-2">Test Result:</h3>
    <div className="text-sm">
      {testResult ? (
        <>
          <p>✅ Connection successful!</p>
          <p>Check your Langfuse dashboard for the test trace.</p>
        </>
      ) : (
        <>
          <p>❌ Connection failed!</p>
          <p>Check the console for error details.</p>
        </>
      )}
    </div>
  </div>
)}

5. Error Display

// Error reporting
{error && (
  <div className="p-4 rounded bg-red-100 border border-red-300">
    <h3 className="font-semibold mb-2 text-red-800">Error:</h3>
    <p className="text-sm text-red-700">{error}</p>
  </div>
)}

Integration Examples

Development Page

function DeveloperTools() {
  return (
    <div className="dev-tools">
      <h1>Developer Tools</h1>
      <LangfuseDebugger />
    </div>
  );
}

Conditional Debug Panel

function AppWithDebug() {
  const isDevelopment = process.env.NODE_ENV === 'development';
  
  return (
    <div className="app">
      <MainContent />
      {isDevelopment && <LangfuseDebugger />}
    </div>
  );
}

Debug Page Route

// pages/debug/langfuse.tsx
export default function LangfuseDebugPage() {
  return (
    <div className="container mx-auto p-8">
      <h1 className="text-2xl font-bold mb-8">Langfuse Debug Console</h1>
      <LangfuseDebugger />
    </div>
  );
}

Console Commands

Manual Testing

// Available console commands for manual testing
debugLangfuseStatus()     // Check current status
testLangfuseConnection()  // Test connection manually

Debug Information

The component provides guidance for manual console usage:

<div className="text-sm text-gray-600">
  <p>Open the browser console for detailed debug information.</p>
  <p>You can also run these commands in the console:</p>
  <ul className="list-disc list-inside mt-2">
    <li><code>debugLangfuseStatus()</code></li>
    <li><code>testLangfuseConnection()</code></li>
  </ul>
</div>

State Management

// Component state tracking
const [status, setStatus] = React.useState<any>(null);        // Status object
const [testResult, setTestResult] = React.useState<boolean | null>(null); // Test outcome
const [testing, setTesting] = React.useState(false);          // Loading state
const [error, setError] = React.useState<string | null>(null); // Error state

Use Cases

Development Debugging

• Initial Setup: Verify Langfuse configuration during development
• Troubleshooting: Diagnose connection issues and configuration problems
• Testing: Validate Langfuse integration before deployment

Production Monitoring

• Health Checks: Verify Langfuse service availability
• Configuration Validation: Ensure proper environment variable setup
• Error Diagnosis: Identify and resolve runtime integration issues

Features

Visual Design

• Clear Status Indicators: Green checkmarks for success, red X for failures
• Loading States: Disabled buttons and loading text during operations
• Color-Coded Results: Green for success, red for errors, gray for neutral
• Monospace Font: Technical information displayed in monospace for readability

Error Handling

• Try-Catch Blocks: Comprehensive error catching for all operations
• Error Display: User-friendly error messages with technical details
• Console Logging: Detailed console output for developer debugging
• Graceful Degradation: Component continues to function despite errors

Development Features

• Auto-Initialization: Runs status check automatically on mount
• Manual Controls: Buttons for manual status and connection testing
• Console Integration: Direct access to underlying debugging functions
• Detailed Feedback: Comprehensive status information and test results