Documentation Grafana Cloud Monitor applications Frontend Observability Source map uploads Upload with the CLI

Upload source maps with the CLI

Use the Faro CLI to upload source maps separately from your build process, particularly useful for CI/CD pipelines.

Install the CLI

Install the Faro CLI tool.

Bash Copy

npm install --save-dev @grafana/faro-cli

or

Bash Copy

yarn add --dev @grafana/faro-cli

Obtain an API key

To upload source maps with the CLI, you must generate a token for the API key value with the necessary permissions to upload source maps to Grafana Cloud. To generate a token, follow these steps:

1. Navigate to the Grafana website.
2. Sign in to your account and then click My Account in the top right corner.
3. In the sidebar under Security, click Access Policies and then click Create access policy.
4. Select the sourcemaps:read, sourcemaps:delete, and sourcemaps:write scopes from the drop-down list.
5. After creating your access policy, click Add token in the card for your newly created policy.
6. Create the token and be sure to copy the token value, as you aren’t be able to see it again.

After you have generated a token with the API key value, you can use it in the Faro JavaScript bundler plugins to upload your source maps to Grafana Cloud. Use the generated token value as the apiKey value in the configuration options for the bundler plugins.

For best practices, store your token in a secure location and don’t expose it in your source code. Consider using environment variables or a secrets manager to securely store and access your API key.

Upload source maps

Upload source maps using the CLI

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id env \
  --app-name "$your-app-name" \
  --output-path "./dist" \
  --verbose

File size handling

The CLI handles large files automatically within the Faro API’s 30MB per file limit:

• Checks file sizes and warns about oversized files
• Streams files and creates upload batches as they approach size limits
• Supports tuning with --max-upload-size while respecting backend limits

Compression options

Reduce bandwidth usage with these compression strategies:

Compress tarred contents for multiple files:

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-contents \
  --verbose

Compress HTTP payload for large individual files:

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-payload \
  --verbose

Combine both compression methods for maximum efficiency:

Bash Copy

npx faro-cli upload \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --output-path "./dist" \
  --patterns "*.map" \
  --gzip-contents \
  --gzip-payload \
  --verbose

Inject bundle ID into JavaScript files

Add bundle IDs to built JavaScript files:

Bash Copy

npx faro-cli inject-bundle-id \
  --bundle-id "$your-bundle-id" \
  --app-name "$your-app-name" \
  --files "dist/**/*.js" \
  --verbose

Test the injection without making changes:

Bash Copy

npx faro-cli inject-bundle-id \
  --bundle-id "$your-bundle-id" \
  --app-name "$your-app-name" \
  --files "dist/**/*.js" \
  --dry-run \
  --verbose

Generate cURL commands

Create ready-to-run cURL commands for source map uploads:

Bash Copy

npx faro-cli curl \
  --endpoint "$your-faro-sourcemap-api-url" \
  --app-id "$your-app-id" \
  --api-key "$your-api-key" \
  --stack-id "$your-stack-id" \
  --bundle-id "$your-bundle-id" \
  --file "./dist/main.js.map"

Upload command options

Required options:

• -e, --endpoint <url> - Faro API endpoint URL from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -a, --app-id <id> - Faro application ID
• -k, --api-key <key> - Faro API key
• -s, --stack-id <id> - Faro stack ID from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -b, --bundle-id <id> - Bundle ID. Set to env to read from environment variable
• -o, --output-path <path> - Path to directory containing source maps

Optional options:

• -n, --app-name <name> - Application name for finding bundle ID in environment variables
• -k, --keep-sourcemaps - Keep source maps after uploading. Default: false
• -g, --gzip-contents - Compress source maps as tarball before uploading. Default: false
• -z, --gzip-payload - Gzip HTTP payload for smaller uploads. Default: false
• -v, --verbose - Enable detailed logging. Default: false
• -r, --recursive - Recursively search subdirectories for source maps. Default: false
• -x, --max-upload-size <size> - Maximum upload size in bytes. Default: 30MB

cURL command options

Required options:

• -e, --endpoint <url> - Faro API endpoint URL from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -a, --app-id <id> - Faro application ID
• -k, --api-key <key> - Faro API key
• -s, --stack-id <id> - Faro stack ID from Frontend Observability > Settings > Source Maps > Configure source map uploads
• -b, --bundle-id <id> - Bundle ID. Set to env to read from environment variable
• -f, --file <path> - Path to source map file

Optional options:

• -n, --app-name <name> - Application name for finding bundle ID in environment variables
• -t, --content-type <type> - Content type for upload. Default: application/json
• -z, --gzip-payload - Generate command that compresses payload. Default: false

After uploading, verify your source maps in Frontend Observability by navigating to Settings > Source Maps. For troubleshooting common issues, refer to Troubleshooting.