> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# 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.

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
import { setupObservability } from "langwatch/observability/node";

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

```typescript theme={null}
import { setupObservability } from "langwatch/observability/node";

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](https://discord.gg/langwatch) for help
5. **GitHub Issues**: Report bugs and feature requests on [GitHub](https://github.com/langwatch/langwatch/issues)

## Related Documentation

For more debugging techniques and advanced troubleshooting:

* **[Integration Guide](https://langwatch.ai/docs/integration/typescript/guide.md)** - Basic setup and common issues
* **[API Reference](https://langwatch.ai/docs/integration/typescript/reference.md)** - Configuration options and error handling
* **[Manual Instrumentation](https://langwatch.ai/docs/integration/typescript/tutorials/manual-instrumentation.md)** - Debugging manual span management
* **[Framework Integrations](https://langwatch.ai/docs/integration/overview.md)** - Framework-specific debugging guides
* **[OpenTelemetry Migration](https://langwatch.ai/docs/integration/typescript/tutorials/opentelemetry-migration.md)** - Troubleshooting migration issues

> [!TIP]
>
> For complex debugging scenarios, combine console tracing with [Manual
> Instrumentation](https://langwatch.ai/docs/integration/typescript/tutorials/manual-instrumentation.md) techniques for detailed
> span analysis.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.