Skip to main content

Troubleshooting

Common issues and their solutions.

Agent Issues​

Agent Not Sending Data​

Symptoms: No data appearing in dashboard after installation.

Solutions:

  1. Verify API Key

    // Check your settings.json
    {
      "skysignal": {
        "apiKey": "sk_live_xxx"  // Must start with sk_live_ or sk_test_
      }
    }

  2. Check Agent Initialization

    # Look for SkySignal logs on startup
    meteor run --settings settings.json
    # Should see: "SkySignal: Connected to dash.skysignal.app"

  3. Verify Network Connectivity

    # Test from your server
    curl -I https://dash.skysignal.app/health
    # Should return 200 OK

  4. Check Firewall Rules

    • Allow outbound HTTPS to dash.skysignal.app
    • Allow outbound on port 443

High Memory Usage from Agent​

Symptoms: Memory increases after installing agent.

Solutions:

  1. Reduce Sample Rate

    SkySignal.init({
      apiKey: 'sk_live_xxx',
      sampleRate: 0.5  // Sample 50% of traces
    });

  2. Disable Unused Collectors

    SkySignal.init({
      apiKey: 'sk_live_xxx',
      enableRUM: false,      // Disable if not needed
      enableHTTP: false      // Disable HTTP tracking
    });

  3. Increase Flush Interval

    SkySignal.init({
      apiKey: 'sk_live_xxx',
      flushInterval: 30000  // Batch for 30 seconds
    });

Method Names Showing as "unknown"​

Symptoms: Method traces appear but names are "unknown".

Solutions:

  1. Ensure Methods are Defined Before Agent Init

    // ✅ Correct order
    import './methods';  // Define methods first
    import '@skysignal/agent';  // Then import agent

  2. Check for Dynamic Method Registration

    // If using ValidatedMethod, ensure proper naming
    export const myMethod = new ValidatedMethod({
      name: 'myModule.myMethod',  // Explicit name required
      // ...
    });

Dashboard Issues​

No Data Showing​

Symptoms: Dashboard loads but shows "No data available".

Solutions:

  1. Check Time Range

    • Default is last 24 hours
    • Adjust to "Last 7 days" if just installed

  2. Verify Site Selection

    • Ensure correct site is selected
    • Check you have access to the site

  3. Wait for Data Processing

    • Data may take 1-2 minutes to appear
    • Check "Last seen" timestamp in site settings

Charts Not Loading​

Symptoms: Blank charts or loading spinners.

Solutions:

  1. Clear Browser Cache

    Chrome: Ctrl+Shift+Delete → Cached images and files

  2. Check Console for Errors

    F12 → Console tab → Look for red errors

  3. Try Different Browser

    • Supported: Chrome, Firefox, Safari, Edge (latest)

Slow Dashboard Performance​

Symptoms: Dashboard takes long to load.

Solutions:

  1. Reduce Time Range

    • Use shorter time ranges (1h, 6h) for faster queries

  2. Use Filters

    • Filter by specific method or host
    • Reduces data volume

  3. Check Network

    • Slow connection affects dashboard
    • Try from different network

Data Issues​

Missing Traces​

Symptoms: Some method calls not appearing.

Solutions:

  1. Check Sample Rate

    // If sample rate < 1, some traces won't be captured
    SkySignal.init({
      sampleRate: 1.0  // Capture everything
    });

  2. Verify Method Tracking

    // Some methods may be filtered
    SkySignal.init({
      excludeMethods: ['debug.*']  // Check exclusions
    });

  3. Check for Errors

    • Failed method calls may still be captured
    • Look in Errors tab

Incorrect Response Times​

Symptoms: Response times seem wrong.

Solutions:

  1. Understand Measurement Point

    • Server-side time only (not network)
    • Includes async operations within method

  2. Check for Long-Running Operations

    Meteor.methods({
      'myMethod'() {
        this.unblock();  // Without this, includes wait time
        // ...
      }
    });

Duplicate Errors​

Symptoms: Same error appears multiple times.

Solutions:

  1. Errors are Grouped by Default

    • Same error message = same group
    • Check occurrence count

  2. Enable Error Fingerprinting

    SkySignal.init({
      errorTracking: {
        fingerprint: ['message', 'type', 'method']
      }
    });

Authentication Issues​

"Invalid API Key" Error​

Solutions:

  1. Verify Key Format

    Production: sk_live_xxxxx (28+ characters)
    Test: sk_test_xxxxx

  2. Check for Whitespace

    // ❌ Wrong
    apiKey: ' sk_live_xxx '  // Has spaces

    // ✅ Correct
    apiKey: 'sk_live_xxx'

  3. Regenerate Key

    • Site Settings → API → Rotate Key

"Unauthorized" in Dashboard​

Solutions:

  1. Log Out and Back In

    • Session may have expired

  2. Check Email Verification

    • Must verify email to access dashboard

  3. Check Team Membership

    • Ensure you're added to the customer account

Performance Issues​

High CPU on Server​

Symptoms: CPU spikes after installing agent.

Solutions:

  1. Enable Sampling

    SkySignal.init({
      sampleRate: 0.1  // Only track 10% of requests
    });

  2. Disable Detailed Tracing

    SkySignal.init({
      traceDetails: false  // Skip argument capture
    });

Increased Latency​

Symptoms: Methods slower after agent installation.

Solutions:

  1. Agent adds ~1-2ms overhead max

    • If seeing more, check other factors

  2. Use Async Reporting

    // Default is async, verify not changed
    SkySignal.init({
      sync: false  // Should be false
    });

Getting Help​

Collect Debug Information​

Before contacting support:

// Enable debug logging
SkySignal.init({
  apiKey: 'sk_live_xxx',
  debug: true
});

Then collect:

  • Agent version (npm list @skysignal/agent)
  • Meteor version (meteor --version)
  • Node version (node --version)
  • Browser console logs
  • Server logs with SkySignal output

Contact Support​

Include:

  • Description of the issue
  • Steps to reproduce
  • Debug information collected above
  • Screenshots if applicable