آپلود source map با CLI

ابزار @abrova-trace/cli فایل‌های source map را از pipeline مربوط به CI/CD به ابرووا تریس آپلود می‌کند. هر خطایی که بعد از آپلود ثبت شود، در داشبورد با نام واقعی فایل‌ها و شماره‌ی خطوط نمایش داده می‌شود؛ دیگر خبری از stackهای minified مثل 4d240bf7.js:1:16945 نیست.

۱پیش‌نیازها#

سه چیز لازم دارید:

• Node.js 18+ روی ماشینی که آپلود را اجرا می‌کند (runner مربوط به CI یا سیستم توسعه‌ی خودتان)
• یک توکن دسترسی شخصی با دسترسی sourcemaps:write
• DSN پروژه از بخش ابرووا تریس ← Source map و symbol در کنسول ابرووا

۲نصب CLI#

این CLI از Abrova Center می‌آید. یک بار رجیستری را اضافه کنید، سپس آن را به‌عنوان dev dependency نصب کنید:

# .npmrc (in your project root)
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/

npm install --save-dev @abrova-trace/cli

آن را از داخل پروژه با npx abrova-trace اجرا کنید (مثلاً npx abrova-trace --help). نام دستور abrova-trace است.

۳ساختن توکن دسترسی شخصی#

توکن‌های دسترسی شخصی (PAT) اعتبارنامه‌هایی بلندمدت و وابسته به کاربرند؛ همان الگویی که بسیاری از CLIهای توسعه‌دهندگان به کار می‌برند. در جریان‌های خودکار، جای توکن نشست کاربر را می‌گیرند.

1. کنسول ابرووا را باز کنید: Account → Personal Access Tokens
2. روی token جدید کلیک کنید
3. یک نام به آن بدهید (مثلاً CI upload — production)
4. دسترسی sourcemaps:write را فعال کنید
5. تاریخ انقضا را انتخاب کنید (برای CI بدون انقضا هم مشکلی ندارد؛ ۹۰ روز یک حد وسط رایج است)
6. روی ساخت token کلیک کنید
7. مقدار ab_pat_xxx را همان لحظه کپی کنید؛ فقط یک بار نمایش داده می‌شود

این مقدار را در محیط CI به‌عنوان secret با نام ABROVA_TRACE_TOKEN ذخیره کنید.

۴پیدا کردن شناسه‌ی پروژه#

«project ID» در این CLI همان DSN پروژه برای پلتفرم وبی است که mapها به آن تعلق دارند (در یک پروژه‌ی ابرووا، هر پلتفرم DSN جداگانه‌ی خودش را دارد).

1. کنسول ابرووا را باز کنید و پروژه‌تان را انتخاب کنید
2. به ابرووا تریس ← Source map و symbol بروید (زبانه‌ی Source maps)
3. در کارت آپلود از CI، اگر پروژه بیش از یک پلتفرم دارد پلتفرم وب را انتخاب کنید، سپس DSN پروژه برای CLI را کپی کنید

این مقدار را با نام ABROVA_TRACE_PROJECT در محیط CI ذخیره کنید (CLI متغیر قدیمی ABROVA_TRACE_DSN را هم همچنان می‌خواند).

۵آپلود از CI#

این دو خط را درست بعد از build مربوط به production که فایل‌های source map را می‌سازد، به pipeline اضافه کنید:

export ABROVA_TRACE_TOKEN=ab_pat_xxx
export ABROVA_TRACE_PROJECT=<your-project-id>

npx abrova-trace sourcemaps upload ./path/to/your/sourcemaps \
  --release "1.2.3"

همین. CLI همه‌ی فایل‌های .map را در پوشه‌ی داده‌شده و زیرپوشه‌هایش پیدا می‌کند، همه را در یک درخواست آپلود می‌کند و با نسخه‌ی release برچسب می‌زند تا ابرووا تریس بتواند آن‌ها را با خطاهای همان نسخه جور کند.

۶مثال: آپلود source mapهای Next.js#

در Next.js ساخت source map را در next.config.js فعال کنید:

module.exports = {
  productionBrowserSourceMaps: true,
};

سپس در اسکریپت CI:

#!/bin/bash
set -e

# 1. Build with sourcemaps
npm run build

# 2. Copy sourcemaps into a dedicated folder
mkdir -p ./sourcemaps
find .next/static/chunks -name "*.js.map" -exec cp {} ./sourcemaps \;

# 3. Upload to Abrova Trace tagged with the release version
npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps

# 4. Remove sourcemaps from the deployed build so browsers can't download them
#    (source stays private — Abrova keeps the maps server-side)
find .next/static/chunks -name "*.js.map" -delete
find .next/static/chunks -name "*.js" -exec \
  sed -i '/^\/\/# sourceMappingURL=/d' {} +

۷یکسان بودن نسخه‌ی release#

مقدار فلگ --release باید با نسخه‌ای که SDK هنگام ارسال خطا می‌فرستد یکی باشد. اگر SDK مربوط به Next.js این‌طور مقداردهی شده است:

AbrovaTrace.init({
  apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION, // e.g. "1.2.3"
});

با این دستور آپلود کنید:

npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps

اگر رشته‌های release یکی نباشند، ابرووا تریس source map را برای خطا پیدا نمی‌کند و همان stack فشرده‌شده را نشان می‌دهد.

۸گزینه‌های CLI#

فلگ بر متغیر محیطی متناظرش اولویت دارد. کلید API پروژه (ab_live_…) اینجا کار نمی‌کند؛ CLI توکن دسترسی شخصی لازم دارد.

۹ابرووا تریس روی سرور خودتان#

وقتی ابرووا تریس را روی زیرساخت خودتان اجرا می‌کنید، CLI را به API خودتان وصل کنید:

export ABROVA_TRACE_API_URL=https://trace.mycompany.com

npx abrova-trace sourcemaps upload \
  --release "1.2.3" \
  ./sourcemaps

CLI روی نسخه‌ی self-hosted دقیقاً همان کار را می‌کند؛ بدون تغییر کد، فقط با تغییر URL.

۱۰کدهای خروج#

• 0: موفق
• 1: هر خطایی (توکن نامعتبر، خطای شبکه، رد شدن آپلود و غیره)

مناسب برای این‌که deploy فقط بعد از آپلود موفق انجام شود:

# .github/workflows/deploy.yml
- name: Upload sourcemaps
  run: npx abrova-trace sourcemaps upload --release "$GITHUB_SHA" ./sourcemaps
  env:
    ABROVA_TRACE_TOKEN: ${{ secrets.ABROVA_TRACE_TOKEN }}
    ABROVA_TRACE_PROJECT: ${{ secrets.ABROVA_TRACE_PROJECT }}

- name: Deploy
  run: ./deploy.sh
  # Deploy only runs if sourcemap upload succeeded

۱۱محدودیت‌های آپلود#

• بیشینه‌ی حجم bundle: ۱۱۰ مگابایت در هر آپلود (کل درخواست multipart)
• بیشینه‌ی حجم فایل: ۵۰ مگابایت برای هر فایل .map
• بیشینه‌ی تعداد فایل در هر آپلود: ۵۰۰

این مقادیر پیش‌فرض سخاوتمندانه‌اند و برای buildهای معمول Next.js، Vite و webpack کافی‌اند. فایل‌های بزرگ‌تر با HTTP 413 رد می‌شوند. اگر bundle شما از ۱۱۰ مگابایت بیشتر است، آن را در چند آپلود با همان --release تقسیم کنید (مثلاً هر بار یک پوشه)، یا با ما تماس بگیرید.

۱۲dSYMهای iOS#

CLI فقط source mapهای جاوااسکریپت را آپلود می‌کند. debug symbolهای iOS (dSYM) در کنسول ابرووا آپلود می‌شوند:

1. در Xcode به Organizer › Archives › Download Debug Symbols بروید، سپس پوشه‌ی .dSYM را zip کنید
2. ابرووا تریس ← Source map و symbol را باز کنید و زبانه‌ی dSYMهای iOS را انتخاب کنید
3. release را انتخاب کنید و فایل .zip را رها کنید (در هر آپلود یک .zip، تا ۱۰ مگابایت)

آپلود دست‌کم نقش member می‌خواهد؛ حذف فایل‌های آپلودشده نقش admin یا owner. نقش‌ها و دسترسی‌ها را ببینید.

۱۳عیب‌یابی#