Debugging and Troubleshooting

Debug TypeScript SDK integrations with LangWatch to fix tracing gaps, evaluation mismatches, and agent testing issues.

Troubleshooting Tools

The LangWatch TypeScript SDK has console tracing, a custom logger hook, and error-handling options for troubleshooting an integration.

Console Tracing and Logging

Enable console output and detailed logging for development and troubleshooting.

import { setupObservability } from "langwatch/observability/node";

const handle = setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY,
    processorType: 'simple' // Use 'simple' for immediate export during debugging
  },
  serviceName: "my-service",
  
  // Debug options for development
  debug: {
    consoleTracing: true, // Log spans to console
    consoleLogging: true, // Log records to console
    logLevel: 'debug'     // SDK internal logging
  }
});

Custom Logger

Create a custom logger for better integration with your existing logging system:

import { setupObservability } from "langwatch/observability/node";

// Create a custom logger
const customLogger = {
  debug: (message: string) => console.log(`[DEBUG] ${message}`),
  info: (message: string) => console.log(`[INFO] ${message}`),
  warn: (message: string) => console.warn(`[WARN] ${message}`),
  error: (message: string) => console.error(`[ERROR] ${message}`),
};

const handle = setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY
  },
  serviceName: "my-service",

  debug: {
    logger: customLogger,
    logLevel: 'debug'
  }
});

Error Handling

Configure error handling behavior for different environments:

import { setupObservability } from "langwatch/observability/node";

const handle = setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY
  },
  serviceName: "my-service",

  // Advanced options for error handling
  advanced: {
    throwOnSetupError: true, // Throw errors instead of returning no-op handles
  }
});

Common Issues

Spans Not Appearing in Dashboard

1. Check API Key: Ensure your LANGWATCH_API_KEY is correctly set
2. Verify Endpoint: Confirm the LANGWATCH_ENDPOINT is accessible
3. Check Network: Ensure your application can reach the LangWatch API
4. Processor Type: Use 'simple' processor for immediate export during debugging

Performance Issues

1. Batch Processing: Use 'batch' processor for production to reduce API calls
2. Sampling: Implement sampling for high-volume applications
3. Data Capture: Limit data capture to essential information

Integration Issues

1. Framework Compatibility: Ensure you’re using the correct integration for your framework
2. Version Compatibility: Check that your LangWatch SDK version is compatible with your framework
3. Configuration: Verify that all required configuration options are set

Environment-Specific Debugging

Development Environment

const handle = setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY,
    processorType: 'simple' // Immediate export for debugging
  },
  serviceName: "my-service",
  debug: {
    consoleTracing: true,
    consoleLogging: true,
    logLevel: 'info' // Raise this to `debug` if you're debugging the LangWatch integration
  }
});

Production Environment

const handle = setupObservability({
  langwatch: {
    apiKey: process.env.LANGWATCH_API_KEY,
    processorType: 'batch' // Efficient batching for production
  },
  serviceName: "my-service",
  debug: {
    consoleTracing: false, // Disable console output in production
    logLevel: 'warn' // Only log warnings and errors
  }
});

Getting Help

If you’re still experiencing issues:

1. Check Logs: Review console output and application logs
2. Verify Configuration: Double-check all configuration options
3. Test Connectivity: Ensure your application can reach LangWatch services
4. Community Support: Visit our Discord community for help
5. GitHub Issues: Report bugs and feature requests on GitHub

Related Documentation

For more debugging techniques and advanced troubleshooting:

• Integration Guide - Basic setup and common issues
• API Reference - Configuration options and error handling
• Manual Instrumentation - Debugging manual span management
• Framework Integrations - Framework-specific debugging guides
• OpenTelemetry Migration - Troubleshooting migration issues

For complex debugging scenarios, combine console tracing with Manual Instrumentation techniques for detailed span analysis.