SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

مقایسه ابزارهای ردیابی هزینه Claude Code

ابزارهای ردیابی هزینه Claude Code پرسش‌های متفاوتی را پاسخ می‌دهند. مقایسه کنید: تحلیل‌گرهای لاگ محلی، صفحه‌های مصرف داخلی و پشته OpenTelemetry شخصی شما چه می‌خوانند.

ردیاب‌های هزینه Claude Code دقیقاً چه چیزی را می‌خوانند

هر ردیاب هزینه Claude Code یکی از سه منبع داده را می‌خواند و همین منبع تعیین می‌کند که ردیاب به چه پرسشی می‌تواند پاسخ دهد. یک تحلیل‌گر لاگ (log parser)، فایل‌های رونوشت نشست (session transcript) را روی دیسک خودتان می‌خواند. یک داشبورد، سوابق مصرفی را می‌خواند که Anthropic برای حساب کاربری یا سازمان شما نگهداری می‌کند. یک بک‌اند متریک، جریان OpenTelemetry (OTel) را می‌خواند که Claude Code هنگام فعال‌سازی منتشر می‌کند. هر سه منبع می‌توانند همزمان درست باشند و در عین حال با هم اختلاف داشته باشند، زیرا هر کدام چیزهای متفاوتی را شمارش می‌کنند.

این راهنما دوباره توکن‌ها را توضیح نمی‌دهد. نحوه شمارش مصرف توکن توسط Claude Code ورودی، خروجی، نوشتن در حافظه پنهان (cache) و خواندن از آن را پوشش می‌دهد و تا زمانی که آن بخش شفاف نباشد، هیچ داشبوردی معنای چندانی نخواهد داشت. پرسش در اینجا محدودتر است: برای هر نوع ابزار، چه چیزی قابل مشاهده است و چه چیزی هرگز قابل مشاهده نخواهد بود.

چرا سه ابزار ردیابی هزینه برای Claude Code در یک روز منتشر شدند

سه ابزار ردیابی هزینه مجزا برای Claude Code در یک روز منتشر شدند. این‌ها سه نسخه از یک ابزار واحد نبودند و همین نکته، بخش مفید ماجراست. یکی از آن‌ها فایل‌های نشست محلی را تحلیل می‌کرد. دیگری صفحات مربوط به میزان مصرف حساب کاربری را بسته‌بندی (wrap) می‌کرد. سومی یک backend ردیابی میزبانی‌شده بود که خودتان آن را اجرا می‌کنید.

دلیل هم‌زمانی انتشار آن‌ها این است که هزینه نشست‌های agent دیگر شفاف نیست. هزینه یک چت تقریباً همان چیزی است که روی صفحه می‌بینید. اما یک agent بیست فایل را می‌خواند، مجموعه تست‌ها را اجرا می‌کند و در هر مرحله، کل تاریخچه گفتگو را دوباره ارسال می‌کند؛ بنابراین صورت‌حساب شما بر اساس متنی افزایش می‌یابد که هرگز تایپ نکرده‌اید. در اشتراک‌های فعلی، مبلغ دلاری نشست که Claude Code نمایش می‌دهد، صرفاً یک تخمین است که Anthropic اعلام کرده برای صورت‌حساب نهایی ملاک نیست؛ عدد واقعی، نوار میزان مصرف است که در برخی روزها سریع‌تر از روزهای دیگر پر می‌شود. هر یک از این سه ابزار، بخش متفاوتی از این شکاف اطلاعاتی را پر می‌کنند.

شکل 1: یک تحلیل‌گر لاگ محلی که هزینه امروز را به شما می‌گوید

Claude Code هر گفتگو را به صورت JSON Lines در مسیر ~/.claude/projects/<project>/<session-id>.jsonl ذخیره می‌کند، که در آن <project> مسیر دایرکتوری کاری شماست که کاراکترهای غیرالفبایی آن با - جایگزین شده‌اند. هر نوبت پاسخ دستیار در آن فایل، شامل تعداد توکن‌های درخواست مربوطه است. یک تحلیل‌گر لاگ آن‌ها را جمع زده و قیمت‌گذاری می‌کند.

ccusage گزینه‌ای است که اکثر افراد از آن استفاده می‌کنند. این ابزار نیازی به نصب ندارد:

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily مجموع‌ها را بر اساس تاریخ ارائه می‌دهد. --breakdown هر ردیف را بر اساس مدل تفکیک می‌کند، که به این ترتیب متوجه می‌شوید یک بعدازظهر کار با Opus، بخش بزرگی از هزینه هفته را تشکیل می‌دهد. blocks داده‌ها را بر اساس بازه پنج‌ساعته‌ای که اشتراک در آن ریست می‌شود، گروه‌بندی می‌کند. session مجموع را به تفکیک هر گفتگو نشان می‌دهد و daily --instances بر اساس پروژه گروه‌بندی می‌کند تا بتوانید ببینید کدام مخزن (repository) پرهزینه است. برای محدود کردن بازه از --since و --until استفاده کنید و برای فرمت تاریخی که نسخه شما انتظار دارد، npx ccusage@latest daily --help را اجرا کنید. از اکتبر 2026، این ابزار سایر CLIهای عامل (agent) از جمله Codex و OpenCode را نیز می‌خواند که در صورت مقایسه آن‌ها با یکدیگر اهمیت دارد. گزارش‌های پیش‌فرض تمام منابع شناسایی‌شده را ترکیب می‌کنند؛ برای تمرکز بر Claude Code، قبل از daily یا session از claude استفاده کنید.

قیمت‌گذاری از یک جدول قیمت مدل استخراج می‌شود و این ابزار سه حالت هزینه دارد. --mode auto از مقدار costUSD که Claude Code در زمان حضور در فایل نوشته است استفاده می‌کند و در صورت عدم وجود، محاسبات را بر اساس تعداد توکن‌ها انجام می‌دهد. --mode calculate همیشه بر اساس توکن‌ها محاسبه کرده و هزینه ثبت‌شده را نادیده می‌گیرد. --mode display فقط هزینه‌های ثبت‌شده را نمایش می‌دهد و برای ردیف‌هایی که هزینه‌ای ندارند، $0.00 چاپ می‌کند. اگر مجموع نادرست به نظر می‌رسد، همان گزارش را یک بار تحت calculate و بار دیگر تحت display اجرا کنید. شکاف بزرگ بین این دو به این معنی است که اکثر ورودی‌ها فاقد هزینه ثبت‌شده هستند، بنابراین هر چیزی که می‌خوانید یک تخمین است. اگر نرخ‌های قراردادی پرداخت می‌کنید، pricingOverrides تحت defaults در یک فایل پیکربندی ccusage.json، جایگزین قیمت مدل‌های تکی می‌شود.

همین داده‌ها می‌توانند به پرامپت شما تزریق شوند. ccusage statusline یک خط فشرده برای نوار وضعیت Claude Code چاپ می‌کند که مانند هر دستور خط وضعیت دیگر به ~/.claude/settings.json متصل می‌شود. برای مشاهده بلوک تنظیمات و فیلدهایی که دریافت می‌کند، به ساخت خط وضعیت Claude Code مراجعه کنید.

آنچه یک تحلیل‌گر لاگ نمی‌تواند ببیند، هر چیزی است که در این دستگاه رخ نداده است. لپ‌تاپ دوم، یک نشست در claude.ai، یا کار همکار شما: آن رونوشت‌ها روی همان دیسک‌ها باقی می‌مانند. نشست‌های قدیمی ترمینال به‌طور پیش‌فرض پس از 30 روز عدم فعالیت تحت cleanupPeriodDays پاک می‌شوند، اما قابلیت نگهداری قابل تنظیم است: از مقدار بزرگی مانند 3650 برای حفظ سال‌ها تاریخچه استفاده کنید. رونوشت نشست‌هایی که در Desktop یا Cowork شروع شده یا اخیراً ادامه یافته‌اند، به‌طور پیش‌فرض فراتر از آن دوره نگهداری می‌شوند، مگر در موارد خاص مانند پیکربندی‌های HIPAA.

یک ریسک دیگر وجود دارد و آن ساختاری است. مستندات Anthropic بیان می‌کند که فرمت ورودی داخلی Claude Code است و بین نسخه‌ها تغییر می‌کند، بنابراین اسکریپت‌هایی که مستقیماً این فایل‌ها را تجزیه می‌کنند ممکن است با هر نسخه جدید از کار بیفتند. این موضوع در مورد تمام ابزارهای این چنینی صدق می‌کند. به همین دلیل است که یک دستور یک‌خطی jq که به صورت دستی روی JSONL نوشته شده، ایده بدتری نسبت به آنچه به نظر می‌رسد است: تحلیل‌گرهای نگهداری‌شده، تغییرات فرمت را برای شما دنبال می‌کنند، اما دستور یک‌خطی شما در روزی که یک فیلد تغییر نام یابد، یک عدد غلط با اطمینان کاذب گزارش خواهد داد.

در نهایت، رقم دلاری در یک اشتراک نیاز به یک تذکر دارد. استفاده در محدوده طرح Pro یا Max شما، به ازای هر توکن صورت‌حساب نمی‌شود، بنابراین این عدد نشان‌دهنده هزینه‌ای است که توکن‌های شما با نرخ‌های لیست API می‌داشتند. این عدد میزان سنگینی استفاده شما را اندازه‌گیری می‌کند. این مبلغ قبض شما نیست. استثنا در مورد اعتبارات استفاده (usage credits) است: اگر آن‌ها را فعال کنید، استفاده فراتر از محدودیت طرح، با نرخ‌های استاندارد API به عنوان یک هزینه جداگانه محاسبه می‌شود و claude.ai هزینه آن ماه را در بخش Settings > Usage نشان می‌دهد. اگر سوال اصلی این است که در کدام طرح باشید، آن مقایسه یک تمرین جداگانه است: به صورت‌حساب API در مقابل اشتراک Claude مراجعه کنید.

شکل 2: صفحه‌های نمایش داخلی میزان مصرف، به شما می‌گویند کدام مدل بودجه را مصرف کرده است

Claude Code گزارش‌دهی داخلی خود را دارد و اکثر کاربران هرگز آن را باز نمی‌کنند. دستور /usage را در یک نشست اجرا کنید. بلوک Session در بالا، توکن‌ها را بر اساس مدل و مبلغ دلاری نشست فعلی نشان می‌دهد. این مبلغ به‌صورت محلی و بر اساس نرخ‌های استاندارد لیست توکن‌ها محاسبه می‌شود، مگر اینکه مدیر سیستم یک جدول modelPricing در تنظیمات مدیریت‌شده تعریف کرده باشد که در این صورت، خط Total cost عبارت at your organization's configured rates را نمایش می‌دهد. در هر دو حالت، این رقم یک تخمین است که می‌تواند با صورت‌حساب شما متفاوت باشد. در پلن‌های Pro یا Max، شرکت Anthropic اعلام کرده است که این رقم برای صورت‌حساب ملاک نیست، زیرا آن میزان مصرف در پلن گنجانده شده است. مجموع‌ها با شروع یک گفتگوی جدید توسط /clear بازنشانی می‌شوند.

در پلن‌های Pro، Max، Team یا پلن‌های Enterprise مبتنی بر تعداد کاربر (seat-based)، همین صفحه نشان می‌دهد که چه مقدار از سقف پلن خود را مصرف کرده‌اید. پلن‌های Enterprise مبتنی بر مصرف (usage-based)، سقف مجاز مشخصی ندارند که تمام شود، زیرا هر توکن با نرخ API محاسبه می‌شود. در این پلن‌ها، صفحه مذکور همچنین مصرف اخیر را بر اساس مهارت‌ها، زیر-عامل‌ها (subagents)، افزونه‌ها و سرورهای MCP فردی به صورت درصدی از کل نشان می‌دهد. این صفحه رفتارهایی را که 10 درصد یا بیشتر از مصرف اخیر را تشکیل می‌دهند، مانند context طولانی یا cache miss، مشخص می‌کند. برای جابه‌جایی بین بازه 24 ساعت گذشته و 7 روز گذشته، d یا w را فشار دهید. این ارقام تقریبی هستند و از تاریخچه نشست محلی روی این دستگاه محاسبه می‌شوند، بنابراین دستگاه دوم در این آمار لحاظ نمی‌شود. هنگامی که سقف مجاز تمام شود، Claude Code محدودیت مربوطه و زمان بازنشانی آن را نشان می‌دهد؛ خالی بودن نوار مصرف به معنای تمام شدن سقف مجاز نیست. نشست می‌تواند منتظر بماند و پس از بازنشانی ادامه یابد، و اقدامات لازم پس از رسیدن به سقف مجاز یک تصمیم جداگانه در مورد مدل، context و پلن است.

برای تیم‌های بزرگ‌تر از یک توسعه‌دهنده، اعداد به سطح حساب کاربری منتقل می‌شوند. یک سازمان API به صفحه Console Cost دسترسی دارد؛ این صفحه یک داشبورد Claude Code است که هزینه‌ها و تعداد خطوط پذیرفته‌شده به ازای هر عضو را نشان می‌دهد. همچنین یک API تحلیل Claude Code وجود دارد که همان معیارهای روزانه به ازای هر کاربر را با استفاده از یک کلید مدیریتی ارائه می‌دهد. پلن‌های Team و Enterprise یک گزارش هزینه در کنسول مدیریت با قابلیت خروجی CSV دریافت می‌کنند که روزانه به‌روزرسانی می‌شود؛ این گزارش هزینه‌های اعتبار مصرف در پلن‌های مبتنی بر کاربر و کل مصرف در پلن‌های Enterprise مبتنی بر مصرف را پوشش می‌دهد. پلن Enterprise یک API تحلیل نیز اضافه می‌کند. اینکه کدام‌یک از این موارد را مشاهده می‌کنید به نحوه ورود هر توسعه‌دهنده بستگی دارد، بنابراین در یک سازمان ترکیبی باید دو گزارش را خوانده و به‌صورت دستی با هم جمع کنید.

برای برآورد بودجه، رقم منتشرشده در مستندات هزینه Anthropic تا اکتبر 2026، میانگینی نزدیک به 13 دلار به ازای هر توسعه‌دهنده در هر روز فعال و 150 تا 250 دلار به ازای هر توسعه‌دهنده در ماه است، به‌طوری که 90 درصد کاربران زیر 30 دلار در هر روز فعال هزینه دارند. این ارقام را به عنوان یک معیار منتشرشده از پیاده‌سازی‌های سازمانی در نظر بگیرید، نه به عنوان پیش‌بینی برای تیم خودتان. یک گروه آزمایشی تشکیل دهید و پیش از تعمیم دادن، اندازه‌گیری کنید.

آنچه داشبوردها نمی‌توانند ببینند، جزئیات کمتر از سطح روز و شخص است. آن‌ها به شما می‌گویند که Opus بیشترین مصرف را در روز سه‌شنبه داشته است، اما به شما نمی‌گویند کدام prompt، کدام مخزن (repository) یا کدام job در CI باعث آن شده است. این گزارش‌ها همچنین دارای تأخیر هستند، زیرا گزارش‌های سازمانی روزانه به‌روز می‌شوند، بنابراین آن‌ها ابزاری برای بررسی هستند نه راهی برای متوقف کردن یک عامل (agent) خارج از کنترل در لحظه. متوقف کردن عامل خارج از کنترل به محدودیت‌ها نیاز دارد، نه گزارش‌ها، که موضوع محدود کردن هزینه‌های عامل روی یک VPS است.

شکل 3: پشته OpenTelemetry اختصاصی شما مشخص می‌کند کدام پرامپت دچار افت کیفیت شده است

ابزار Claude Code پس از فعال‌سازی تله‌متری و پیکربندی صادرکننده‌ها (exporters)، متریک‌ها و رویدادهای OpenTelemetry را منتشر می‌کند. این تنها گزینه‌ای است که داده‌های مربوط به توکن و هزینه هر کاربر را به‌صورت بلادرنگ در سیستمی که تحت کنترل شماست، استریم می‌کند. این متریک‌ها شامل claude_code.cost.usage به دلار آمریکا، claude_code.token.usage بر حسب توکن، claude_code.session.count و claude_code.active_time.total هستند.

متریک توکن به دلیل ویژگی‌های (attributes) همراهش، حائز اهمیت است. هر نقطه داده شامل type است که می‌تواند input، output، cacheRead یا cacheCreation باشد؛ به‌علاوه model و query_source که شامل main، subagent یا auxiliary است. این داده‌ها همچنین شامل agent.name، skill.name، mcp_server.name و mcp_tool.name هستند. نام سرورهای MCP که خودتان پیکربندی کرده‌اید و نام زیر-عامل‌های (subagents) سفارشی‌تان، به‌عنوان custom ثبت می‌شوند، مگر اینکه OTEL_LOG_TOOL_DETAILS=1 را تنظیم کنید که در این صورت دستورات Bash و ورودی ابزارها نیز به رویدادهای ابزار اضافه می‌شوند. این اطلاعات برای پاسخ به پرسش‌هایی که هیچ داشبوردی قادر به پاسخگویی به آن‌ها نیست، کافی است: چه مقدار از هزینه مربوط به زیر-عامل‌هاست و چه مقدار مربوط به تعاملات مستقیم شما، آیا یک سرور MCP خاص باعث دو برابر شدن توکن‌های ورودی شده است، یا اینکه آیا پس از ویرایش فایل CLAUDE.md، نرخ خواندن از حافظه کش (cache) کاهش یافته است. رفتار کش معمولاً جایی است که موارد غیرمنتظره پنهان می‌شوند و زمانی که کش کردن پرامپت هزینه‌های خود را جبران می‌کند توضیح می‌دهد که با چه چیزی روبرو هستید.

یک اصلاح لازم است، زیرا این موضوع در تمام بحث‌ها مطرح می‌شود. Langfuse یک بک‌اند ردیابی (tracing) مناسب برای میزبانی شخصی است و اجرای آن روی یک VPS در میزبانی شخصی Langfuse برای ردیابی عامل‌ها پوشش داده شده است. نقطه پایانی OTLP در این ابزار فقط traceها را می‌پذیرد. به‌صورت پیش‌فرض، Claude Code متریک‌ها و رویدادهای لاگ را صادر می‌کند، نه spanها را؛ بنابراین تنظیم OTEL_EXPORTER_OTLP_ENDPOINT روی Langfuse باعث می‌شود پروژه خالی بماند و هیچ خطای قابل‌فهمی دریافت نکنید. قابلیت صدور span وجود دارد، اما به‌عنوان یک ویژگی بتا تا زمانی که CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 و OTEL_TRACES_EXPORTER را تنظیم نکنید، غیرفعال باقی می‌ماند. ادغام اختصاصی Langfuse با Claude Code مسیر متفاوتی را طی می‌کند: یک Stop hook یا پلاگینی که آن را نصب می‌کند، رونوشت‌های نشست (session transcripts) را پس از هر پاسخ می‌خواند و آن‌ها را به trace تبدیل می‌کند؛ بنابراین این روش محدودیت‌های محلی یک تحلیل‌گر لاگ (log parser) را دارد. Langfuse ابزار مناسبی برای عامل‌هایی است که خودتان با استفاده از API می‌سازید، جایی که کد شما هر span را با پرامپت، مدل و هزینه مربوطه ایجاد می‌کند. برای مجموع هزینه‌های CLI ابزار Claude Code، استفاده از یک مخزن متریک (metrics store) گزینه مناسب‌تری است.

راه‌اندازی ردیابی هزینه‌های Claude Code روی VPS شخصی

دو سرویس برای این کار کافی است: یک collector برای دریافت معیارها (metrics) و Prometheus برای ذخیره‌سازی آن‌ها. هر دو را از دسترس اینترنت عمومی خارج کنید، زیرا پورت OTLP باز، داده‌های ارسالی از سوی هر کسی که آن را پیدا کند را می‌پذیرد. فایل /opt/ccmetrics/compose.yaml را بنویسید:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 آدرس سرور در داخل تونل WireGuard است، بنابراین collector فقط از ماشین‌های شما قابل دسترسی است و نه از هیچ جای دیگر. آدرس جلوی پورت در اینجا نقش مهمی ایفا می‌کند، زیرا پورت‌های منتشر شده Docker توسط ufw فیلتر نمی‌شوند: به دلیل عبور پورت‌های منتشر شده Docker از ufw مراجعه کنید. راه‌اندازی خود تونل در یک VPN WireGuard روی VPS شخصی توضیح داده شده است.

/opt/ccmetrics/collector.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml. پورت 8889 هرگز روی host منتشر نمی‌شود، زیرا Prometheus از طریق شبکه Compose و با استفاده از نام سرویس به collector دسترسی پیدا می‌کند:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]
cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

لاگ collector باید با Everything is ready. Begin running and processing data. پایان یابد. لاگی که به دلیل خطای پیکربندی متوقف می‌شود، به این معنی است که فایل YAML تجزیه نشده و container در یک حلقه بازراه‌اندازی (restart loop) قرار می‌گیرد.

اکنون Claude Code را به آن متصل کنید. روی هر ماشینی که Claude Code را اجرا می‌کند، این مورد را به ~/.claude/settings.json اضافه کنید:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

یک نشست (session) را شروع کنید، یک prompt بفرستید، به اندازه بازه زمانی export (در اینجا 10 ثانیه، به‌طور پیش‌فرض 60 ثانیه) صبر کنید، سپس از Prometheus بپرسید چه چیزی دریافت کرده است:

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

شما باید چندین نام که با claude_code_ شروع می‌شوند را دریافت کنید. صادرکننده (exporter) نقاط را به زیرخط (underscore) تبدیل کرده و واحد را به انتهای آن اضافه می‌کند، بنابراین رشته‌های دقیق به نسخه collector شما بستگی دارند. نتیجه خالی به این معنی است که چیزی دریافت نشده است. بررسی کنید که پروتکل و پورت با هم مطابقت داشته باشند، زیرا http/protobuf به 4318 و grpc به 4317 متصل می‌شود و عدم تطابق باعث شکست بی‌سروصدا می‌شود. دستور claude --debug-file /tmp/claude-debug.log را اجرا کنید و در آن فایل به دنبال خطوط [3P telemetry] بگردید؛ اینجاست که Claude Code خطاهای export مربوط به OTel را گزارش می‌کند.

برای یک ماشین و بدون سرور، از تمام مراحل بالا صرف‌نظر کنید. CLAUDE_CODE_ENABLE_TELEMETRY=1 و OTEL_METRICS_EXPORTER=prometheus را تنظیم کنید تا Claude Code یک scrape endpoint را در http://localhost:9464/metrics توسط خود برنامه ارائه دهد. هنگامی که prometheus تنها صادرکننده فهرست شده باشد، Claude Code واحدهای USD، tokens و s را از معیارهای صادر شده حذف می‌کند تا scrape با فرمت متنی استاندارد Prometheus معتبر باقی بماند. نام معیارها تغییر نمی‌کند و تنظیمی که صادرکننده‌ها را ترکیب می‌کند، مانند otlp,prometheus، واحدها را حفظ می‌کند.

یک تصمیم حریم خصوصی با این ساختار همراه است. به‌طور پیش‌فرض فقط شمارش‌ها و متادیتا از ماشین خارج می‌شوند، نه متن prompt و نه خروجی ابزارها. OTEL_LOG_USER_PROMPTS=1 متن prompt را به رویدادهای صادر شده اضافه می‌کند و همچنین در صورتی که OTEL_LOG_ASSISTANT_RESPONSES=0 آن را لغو نکند، متن پاسخ دستیار را نیز فعال می‌کند. OTEL_LOG_TOOL_CONTENT=1 خروجی ابزار انتخاب‌شده را به trace spans اضافه می‌کند، با استثناها و برش در محدودیت محتوا که به‌طور پیش‌فرض 60 KB است. این پرچم‌ها می‌توانند کد منبع و اسرار را در محتوایی که انتخاب می‌کنند افشا کنند؛ آن‌ها به‌طور خودکار همه چیز را در context صادر نمی‌کنند. بدنه کامل گفتگوها به تنظیم جداگانه OTEL_LOG_RAW_API_BODIES نیاز دارد. این موارد را آگاهانه فعال کنید و ابتدا دور نگه داشتن اسرار از context عامل را مطالعه کنید.

ردیابی هزینه‌ها برای اجراهای اسکریپتی و CI

اجراهای غیرتعاملی (non-interactive) همان مواردی هستند که کاربران را غافلگیر می‌کنند، زیرا کسی صفحه نمایش را مشاهده نمی‌کند. claude -p با استفاده از --output-format json، هزینه آن اجرا را در payload نتیجه گزارش می‌دهد:

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

این payload شامل total_cost_usd به همراه تفکیک هزینه به ازای هر مدل است، بنابراین یک job در CI می‌تواند بدون نیاز به داشبورد، هزینه خود را ثبت کند. مانند هر عدد محلی دیگری، این یک تخمین سمت کلاینت است و اجرایی که مکالمه‌ای را با --continue یا --resume ادامه می‌دهد، مجموع هزینه کل مکالمه، شامل اجراهای قبلی را گزارش می‌کند. مقدار را به یک فایل اضافه کنید (append) یا آن را به عنوان یک متریک به collector ذکر شده در بالا ارسال نمایید. این ارزان‌ترین روش ردیابی هزینه موجود است و تنها به یک فراخوانی jq در هر اجرا نیاز دارد.

حالت‌های شکست و آنچه مشاهده خواهید کرد

گزارش خالی است. npx ccusage@latest daily عدم نمایش ردیف‌ها به این معناست که ابزار در حال خواندن داده‌ها از مسیری که Claude Code در آن می‌نویسد نیست. CLAUDE_CONFIG_DIR آن مکان را تغییر می‌دهد و ccusage نیز همان متغیر را می‌خواند، بنابراین هر دو را با مقدار یکسان اجرا کنید. اگر نشست‌های قدیمی وجود ندارند، cleanupPeriodDays را بررسی کنید: نشست‌های ترمینال به‌طور پیش‌فرض پس از 30 روز عدم فعالیت پاک می‌شوند، در حالی که رونوشت‌های Desktop و Cowork معمولاً فراتر از آن دوره نگهداری می‌شوند.

دو دستگاه مجموع‌های متفاوتی را گزارش می‌کنند. این مورد انتظار است و باگ محسوب نمی‌شود. تفکیک /usage و هر تحلیل‌گر لاگ، فقط تاریخچه نشست‌های محلی را می‌خوانند، بنابراین میزان مصرف از دستگاه دیگر یا از claude.ai در هر دو غایب است.

مجموع محلی با صورت‌حساب مطابقت ندارد. ارقام محلی بر اساس تعداد توکن‌ها با نرخ‌های لیست استاندارد محاسبه می‌شوند، مگر اینکه نرخ‌های قراردادی را پیکربندی کنید: یک جدول modelPricing در تنظیمات مدیریت‌شده برای /usage، یا pricingOverrides برای ccusage. در یک اشتراک، مصرف داخل محدودیت طرح اصلاً به ازای هر توکن صورت‌حساب نمی‌شود و فقط اعتبارهای مصرف محاسبه می‌شوند. صفحه هزینه در Console مرجع اصلی برای صورت‌حساب API است.

هزینه در حالی که همان کار را انجام می‌دادید افزایش یافته است. پیش از هر چیز ستون‌های کش را بررسی کنید. یک نشست طولانی کل تاریخچه خود را در هر نوبت دوباره ارسال می‌کند؛ اگر کش گرم باشد با نرخ کش و اگر سرد شود با نرخ کامل ورودی قیمت‌گذاری می‌شود، بنابراین یک وقفه طولانی باعث پردازش مجدد کل گفتگو می‌گردد. این موضوع به صورت یک عدد ورودی بزرگ در کنار یک عدد خروجی کوچک نمایش داده می‌شود و قیمت‌گذاری توکن ورودی در برابر خروجی توضیح می‌دهد که چرا این دو به‌طور مستقل تغییر می‌کنند.

یک روز با subagentها غیرممکن به نظر می‌رسد. هر subagent پنجره کانتکست (context window) خاص خود را اجرا می‌کند، بنابراین مصرف توکن با تعداد دفعات اجرا و مدت زمان هر کدام مقیاس می‌شود. در یک طرح، انتساب /usage سهم subagent برای این دستگاه را به صورت درصدی ارائه می‌دهد. برای جزئیات هر درخواست، داده‌های OTel آن‌ها را از طریق ویژگی query_source در claude_code.token.usage جدا می‌کنند. یک تحلیل‌گر لاگ فقط مجموع را به شما نشان می‌دهد و شما را در حدس زدن باقی می‌گذارد.

FAQ

آیا ccusage نشان می‌دهد که من دقیقاً برای چه چیزی در طرح Max صورت‌حساب دریافت می‌کنم؟

خیر. استفاده در محدوده سقف طرح اشتراک، بر اساس هر توکن محاسبه نمی‌شود. بنابراین، یک تحلیل‌گر لاگ، توکن‌های شما را با نرخ‌های استاندارد لیست API قیمت‌گذاری می‌کند و نشان می‌دهد که همان کار از طریق API چقدر هزینه داشته است. این یک معیار نسبی مناسب برای سنجش میزان سنگینی یک روز کاری است و برای مقایسه پروژه‌ها یا مدل‌ها با یکدیگر مفید است. برای اطلاع از مبلغ بدهی، صفحه Cost در Console هزینه‌های API و صفحه plan billing هزینه اشتراک را پوشش می‌دهد. اگر اعتبار مصرف (usage credits) فعال باشد، استفاده فراتر از سقف مجاز با نرخ‌های استاندارد API محاسبه می‌شود و claude.ai این هزینه‌ها را در مسیر Settings > Usage نمایش می‌دهد.

Claude Code فایل‌های نشست (session) که این ابزارها می‌خوانند را کجا ذخیره می‌کند؟

در ~/.claude/projects/<project>/<session-id>.jsonl، که در آن <project> مسیر دایرکتوری کاری است که کاراکترهای غیرالفبایی آن با - جایگزین شده‌اند. هر خط یک شیء JSON برای یک پیام، استفاده از ابزار یا ورودی متادیتا است. CLAUDE_CONFIG_DIR کل دایرکتوری را جابه‌جا می‌کند و cleanupPeriodDays در settings.json مدیریت نگهداری را کنترل می‌کند که به‌صورت پیش‌فرض روی 30 روز عدم فعالیت برای نشست‌های ترمینال تنظیم شده است؛ رونوشت‌های Desktop و Cowork معمولاً فراتر از این دوره نگهداری می‌شوند. Anthropic فرمت ورودی را به‌عنوان داخلی و در معرض تغییر بین نسخه‌ها مستند کرده است، بنابراین آن را با ابزاری که نگهداری می‌شود تحلیل کنید، نه با اسکریپت شخصی خودتان.

آیا می‌توانم تله‌متری Claude Code را به Langfuse ارسال کنم؟

با تله‌متری پیش‌فرض خیر. نقطه پایانی OTLP در Langfuse تریس‌ها (traces) را می‌پذیرد و Claude Code به‌صورت پیش‌فرض متریک‌ها و رویدادهای لاگ را صادر می‌کند، نه اسپن‌ها (spans)؛ بنابراین داده‌ها جایی برای ثبت ندارند. صادرات اسپن یک ویژگی بتا است که باید آن را فعال کنید و ادغام Claude Code در Langfuse از یک Stop hook استفاده می‌کند که رونوشت‌های نشست را به تریس تبدیل می‌کند. برای مجموع هزینه‌ها، متریک‌های Claude Code را به یک جمع‌آوری‌کننده OpenTelemetry ارسال کرده و آن‌ها را در Prometheus ذخیره کنید. از Langfuse برای ایجنت‌هایی استفاده کنید که خودتان روی API می‌سازید، جایی که کد شما اسپن‌هایی تولید می‌کند که شامل پرامپت، مدل و هزینه هستند.

چرا اعداد محلی من با صفحه استفاده در Console مطابقت ندارند؟

زیرا آن‌ها به روش‌های متفاوتی محاسبه می‌شوند. /usage و تحلیل‌گرهای لاگ، تعداد توکن‌ها را از فایل‌های نشست روی دستگاهی که پشت آن نشسته‌اید جمع می‌زنند و سپس آن‌ها را با نرخ‌های استاندارد لیست قیمت‌گذاری می‌کنند، مگر اینکه نرخ‌های قراردادی از طریق modelPricing در تنظیمات مدیریت‌شده برای /usage یا pricingOverrides برای ccusage پیکربندی شده باشند. Console استفاده سازمان شما در تمامی دستگاه‌ها و کلیدها را پوشش می‌دهد؛ برای هزینه‌های واقعی API از صفحه Cost آن استفاده کنید، زیرا ارقام هزینه در داشبورد تحلیل Claude Code تخمینی هستند. عدم تطابق عادی است. تفاوت بسیار بزرگ معمولاً به معنای استفاده از دستگاه دوم، یک CI runner یا عضو دیگری از تیم است که از همان حساب برای پرداخت استفاده می‌کند.

چگونه هزینه اجرای یک claude -p را در CI ردیابی کنم؟

آن را با --output-format json اجرا کنید و total_cost_usd را از نتیجه بخوانید، برای مثال با استفاده از claude -p "..." --output-format json | jq '.total_cost_usd'. همان payload شامل تفکیک هزینه به تفکیک مدل و شناسه نشست است. آن مقدار را برای هر job ثبت کنید تا هزینه هر خط لوله (pipeline) را بدون نیاز به ایجنت، داشبورد یا سرویس اضافی در اختیار داشته باشید.

آیا این مقاله مفید بود؟