Deep-Dive Debugging Guide

Overview

When a VWO Feature Experimentation (FE) SDK integration does not behave as expected, feature flags not evaluating correctly, variables returning defaults, events not tracking, or SDK initialization failing, the root cause is almost always visible through SDK logs or VWO’s built-in error monitoring.

VWO FE SDKs provide:

• Configurable log levels
• Custom log forwarding support
• Automatic error telemetry to VWO
• In-app error visibility for debugging

This guide explains how to systematically debug SDK integrations across:

• Server-side SDKs (Node, Java, Python, Go, .NET, PHP, Ruby)
• Client-side SDKs (JavaScript, React)
• Mobile SDKs (iOS, Android, React Native, Flutter)

Observability Flow (How Debugging Works)

Every VWO FE SDK emits three streams of diagnostic signals:

flowchart LR
    A[Application Runtime] --> B[VWO FE SDK Core]

    B --> C[Structured Logs]
    B --> D[Custom Logger Adapter]
    B --> E[Error Telemetry Pipeline]

    E --> F[VWO Aggregation Service]
    F --> G[VWO Dashboard Debug View]

📘

ERROR-level logs are automatically transmitted to VWO across server-side, browser, and mobile SDKs.

This allows remote diagnosis without SSH or mobile device log access.

What Happens Internally

1. Your application calls the VWO FE SDK.
2. SDK generates logs based on the configured log level.
3. Logs are:
   • Printed to standard output
   • Optionally forwarded to your logging system
   • ERROR-level logs automatically sent to VWO
4. VWO aggregates SDK errors and displays them inside the dashboard.

SDK Logging Fundamentals

All VWO FE SDKs from VWO:

• Log errors to standard output by default
• Default log level: ERROR
• Support configurable log levels:
  • ERROR
  • WARNING
  • INFO
  • DEBUG

What Each Level Provides

Default Behavior

If you don't configure anything at your end:

• Only ERROR logs are printed
• ERROR logs are also sent to VWO automatically

📘

For production debugging, temporarily elevate to DEBUG mode in a controlled environment.

Enabling Verbose Logging (Critical First Step)

When debugging, change the log level to DEBUG.

Below is a Node.js example of how to configure log level.

const { init, LogLevelEnum } = require('vwo-fme-node-sdk');

const vwoClient = init({
  sdkKey: 'YOUR_SDK_KEY',
  logger: {
    level: LogLevelEnum.DEBUG
  }
});

For more details, see the Logging section in each SDK reference—for example, the Node.js Logging documentation.

What You See in DEBUG Mode

• SDK initialization lifecycle
• Settings file fetch & polling
• Rule evaluation steps
• Targeting condition checks
• Bucketing logic
• Variable resolution
• Network calls and retries
• Event dispatch payloads

This is the most important step when troubleshooting incorrect flag evaluations.

Forwarding Logs to Your Monitoring System

All FE SDKs allow custom logger integration.

Instead of printing to the console, forward logs to:

• Datadog
• ELK Stack
• Splunk
• CloudWatch
• Any structured logging framework

Example of custom logger

const customLogger = {
  log: (level, message) => {
    myDatadogLogger.log(level, message);
  }
};

const vwoClient = init({
  sdkKey: 'YOUR_SDK_KEY',
  logger: customLogger
});

Why This Is Recommended

• Centralized observability
• Correlate SDK failures with deployments
• Identify environment-specific issues
• Monitor retry spikes

In production systems, this is far more powerful than console logging alone.

Automatic SDK Error Telemetry (Server + Client Side)

VWO FE SDKs automatically send ERROR-level logs to VWO servers across:

• Server-side SDKs
• JavaScript / React SDK
• Mobile SDKs (iOS, Android, React Native)

This means:

You can view critical SDK-generated errors inside the VWO dashboard, even without accessing internal application logs.

No additional configuration is required.

Using VWO Advanced Debugging Dashboard

Inside the VWO application, SDK-generated errors are aggregated and made searchable.

You can:

• View Critical Errors
• Initialization failures
• Invalid SDK key
• Missing feature key
• Network errors
• Retry attempts
• Timeout failures

Understand Scope

Compare:

• Total events
• Unique users affected

This helps determine whether an issue is:

• Isolated to one user
• Environment-specific
• Widespread

Filter Errors By

• Date range
• SDK name and version
• Environment
• Error category

Drill Down Into Specific Errors

Inspect:

• Raw event payload
• Timestamp
• Affected user IDs

For a complete walkthrough of the dashboard capabilities, refer to the VWO knowledge base article.

Step-by-Step Troubleshooting Playbook

Step 1 — Verify SDK Initialization

Enable DEBUG logs and confirm:

• SDK key is correct
• Settings file fetch succeeded

If initialization fails:

• Validate SDK key for the correct environment
• Check outbound network access
• Verify firewall/proxy restrictions

Step 2 — Validate Feature Key

Common mistake:

vwoClient.getFlag('wrong_feature_key', context);

DEBUG logs will show:

• Feature not found
• Returning default value

Confirm:

• Feature key matches exactly
• Feature is enabled
• Correct environment

Step 3 — Validate User Identity

Inconsistent user IDs cause bucketing inconsistencies.

Check:

• Same userId used across calls
• No random UUID per request
• Attribute types match targeting rules

DEBUG logs show:

• Which targeting condition failed
• Bucketing result
• Variation assignment

Step 4 — Check Network Calls & Retries

If events are not recorded:

Look for:

• Retry attempts
• Timeout logs
• Network failures

Common causes:

• Browser/Edge navigation terminating request
• Server shuts down before flush
• Firewall blocking VWO endpoints

Step 5 — Correlate Local Logs with VWO Dashboard

After enabling logs:

• Open VWO Application
• Navigate to Website and Apps under Configurations section from the left navbar
• Select the Feature Experimentation Default Project and switch to Logs tab
• Filter by environment
• Inspect error category

If errors appear there:

• SDK is sending telemetry successfully

If not:

• Environment mismatch likely
• SDK key may be incorrect

Common Integration Pitfalls

• Using the wrong SDK key
• Creating a new SDK instance per request
• Calling getFlag before initialization
• Inconsistent user ID
• Firewall blocking outbound calls

Recommended Production Debugging Strategy

For stable production systems:

1. Keep log level at ERROR
2. Temporarily enable DEBUG in an affected environment
3. Forward logs to centralized logging
4. Compare dashboard telemetry with application logs
5. Identify spike patterns before rollback

Three-Layer Debugging Model

flowchart TB
    A[Application Logs]
    B[Infrastructure Logs]
    C[VWO SDK Error Telemetry]

    A --> D[Root Cause Analysis]
    B --> D
    C --> D

When combined:

• Application logs show execution flow
• Infrastructure logs show environment failures
• VWO telemetry shows SDK-specific errors

Together, they eliminate blind spots.

When to Contact Support

If:

• Errors are visible but unclear.
• Initialization fails despite correct configuration.
• Network issues persist after validation.
• Dashboard shows repeated retry spikes.

Collect the following before contacting support:

• SDK name and version
• Environment (production/staging)
• Sample DEBUG logs
• Timestamp of issue
• Feature key involved
• User ID (if reproducible)

Providing these details significantly reduces resolution time.