Skip to content
Lonely Planet Docs

New Relic Source Map Upload

This document explains how to configure and use automatic source map uploads to New Relic for better error reporting and debugging.

Overview

Section titled “Overview”

Source maps allow New Relic to un-minify JavaScript error stack traces, making it easier to debug production issues. Our build process automatically generates source maps, and we can upload them to New Relic using their API.

This setup covers both:

  • 🌐 Browser Monitoring: Client-side JavaScript errors (via API upload)
  • 🖥️ APM Monitoring: Server-side Node.js errors (via Node.js flag)

APM vs Browser Source Maps

Section titled “APM vs Browser Source Maps”
FeatureAPM (Server-side)Browser (Client-side)
PurposeServer-side Node.js errorsClient-side JavaScript errors
SetupNode.js --enable-source-maps flagUpload via API
DetectionAutomaticManual upload required
Source Mapsdist/server/*.mjs.mapdist/client/_astro/*.js.map
Configuration✅ Already enabled in this project⚠️ Requires API keys

Setup

Section titled “Setup”

1. Required Environment Variables

Section titled “1. Required Environment Variables”

You need to set the following environment variables:

Required for Source Map Upload:

Section titled “Required for Source Map Upload:”
  • NEW_RELIC_USER_API_KEY - Your New Relic User API Key (not the same as the license key)
  • NEW_RELIC_BROWSER_APPLICATION_ID - Your New Relic Browser Application ID
Section titled “Optional (but recommended for better tracking):”
  • GITHUB_REPOSITORY_URL - Your repository URL (e.g., https://github.com/your-org/your-repo)
  • GITHUB_SHA or GIT_COMMIT - Git commit hash for the build

2. Getting Your New Relic User API Key

Section titled “2. Getting Your New Relic User API Key”
  1. Go to New Relic API Keys
  2. Click “Create a key”
  3. Choose “User key” type
  4. Give it a descriptive name like “Source Maps Upload”
  5. Copy the generated key

3. Finding Your Browser Application ID

Section titled “3. Finding Your Browser Application ID”
  1. Go to your New Relic Browser application
  2. Look at the URL - it should contain the application ID
  3. Or go to Settings → Application settings and find the Application ID

Usage

Section titled “Usage”

Manual Upload

Section titled “Manual Upload”

Upload source maps manually after building:

Terminal window
# Build the project first
npm run build


# Then upload source maps (CI/CD only)
node .github/scripts/upload-sourcemaps.js

Note: Manual upload requires the same environment variables as CI/CD and is primarily intended for debugging.

CI/CD Integration

Section titled “CI/CD Integration”

For GitHub Actions, the source maps are uploaded as part of the deployment process (not build process) to ensure environment-specific application IDs are used.

Required GitHub Secrets:

NEW_RELIC_USER_API_KEY: your_user_api_key
NEW_RELIC_BROWSER_APPLICATION_ID_PROD: browser_app_id_for_production
NEW_RELIC_BROWSER_APPLICATION_ID_NONPROD: browser_app_id_for_nonprod_and_ephemeral
NEW_RELIC_APM_APPLICATION_ID_PROD: apm_app_id_for_production
NEW_RELIC_APM_APPLICATION_ID_NONPROD: apm_app_id_for_nonprod_and_ephemeral

The workflow automatically:

  1. Downloads build artifacts (including source maps)
  2. Determines environment (production vs nonprod/ephemeral)
  3. Sets the appropriate New Relic application IDs (both Browser and APM)
  4. Uploads source maps with deployment metadata
  5. Records deployment markers in APM for performance correlation

This approach allows you to:

  • ✅ Build once, deploy to multiple environments
  • ✅ Use environment-specific New Relic application IDs
  • ✅ Track source maps per deployment
  • ✅ Include git commit information for better tracking
  • ✅ Correlate deployments with performance changes in APM

Deployment-Based Upload Benefits

Section titled “Deployment-Based Upload Benefits”

This deployment-based approach provides several advantages over build-time uploads:

  • 🏗️ Build once, deploy many: Source maps uploaded per environment, not per build
  • 🎯 Environment-specific: Different New Relic app IDs for prod vs nonprod
  • 🔄 Deployment tracking: Source maps tied to specific deployments with git commit info
  • 🚀 Parallel uploads: Multiple environments can be deployed with appropriate source maps
  • 📦 Artifact reuse: Same build artifacts used across all environments

Deployment Markers

Section titled “Deployment Markers”

The deployment markers provide additional observability benefits:

  • 📈 Performance correlation: See how deployments affect response times, error rates, and throughput
  • 📅 Timeline visualization: Vertical lines on APM charts mark deployment times
  • 🔍 Deployment details: View who deployed, when, and what changed
  • 🚨 Incident correlation: Quickly identify if performance issues started after a deployment
  • 📋 Deployment history: Track all deployments in the APM Deployments page

Architecture

Section titled “Architecture”
┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Build     │───▶│   Artifacts  │───▶│   Deploy        │
│ (with maps) │    │   (dist/)    │    │ (per env)       │
└─────────────┘    └──────────────┘    └─────────┬───────┘
                                                 │
                                                 ▼
                                    ┌─────────────────────┐
                                    │ Upload Source Maps  │
                                    │ (env-specific)      │
                                    └─────────────────────┘

How It Works

Section titled “How It Works”
  1. Build Process: Astro/Vite generates source maps alongside the minified JavaScript files
  2. Discovery: The upload script scans the dist/ directory for .map files
  3. Mapping: For each source map, it finds the corresponding JavaScript file
  4. Upload: Each source map is uploaded to New Relic with metadata about the JavaScript URL
  5. Verification: The script reports success/failure for each upload

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

  1. “No source maps found”

    • Ensure sourcemap: true is set in your Vite configuration
    • Check that the build completed successfully
    • Verify the dist directory contains .map files

  2. “API key invalid”

    • Verify you’re using a User API key, not the license key
    • Check the key hasn’t expired
    • Ensure the key has proper permissions

  3. “Application ID not found”

    • Verify the Browser Application ID is correct
    • Ensure you’re using the browser app ID, not the APM app ID

  4. Rate limit errors

    • New Relic limits: 1000 uploads/minute, 15000 uploads/day
    • If you hit limits, wait and retry

Debug Mode

Section titled “Debug Mode”

For more verbose logging, you can modify the script or add environment variables to see detailed upload information.

Benefits

Section titled “Benefits”

Once set up, you’ll get:

  • 🐛 Readable Stack Traces: Error reports in New Relic will show original source code locations
  • 🎯 Better Debugging: Click through from errors to exact source code lines
  • 👥 Team Collaboration: Developers can quickly identify and fix production issues
  • 📊 Performance Insights: Link performance data to specific code areas
  • 📍 Deployment Correlation: See how code changes affect performance in APM charts and dashboards

Current Implementation Status

Section titled “Current Implementation Status”

✅ APM Source Maps: Enabled via Node.js --enable-source-maps flag (server-side errors)
✅ Browser Source Maps: Upload script configured for client-side errors
✅ GitHub Actions: Deployment-based upload workflow ready
✅ Deployment Markers: APM deployment tracking configured
⚠️ Secrets: Requires GitHub secrets setup for New Relic API keys

References

Section titled “References”