ایجنٹ کوڈنگ ٹولز جیسے کلاڈ کوڈ، اوپن اے آئی کوڈیکس، گوگل اینٹی گریویٹی، اور کرسر روزمرہ کے سافٹ ویئر کی تیاری میں بڑے پیمانے پر استعمال ہوتے ہیں۔
جیسے جیسے ایجنٹ کے نظام پختہ ہوتے ہیں، ڈویلپرز کے ذریعہ انجام دیا جانے والا زیادہ تر کام ایک وقت میں ایک ذیلی ایجنٹ کو سونپ دیا جاتا ہے۔ مزید برآں، بہت سی ٹیمیں مشترکہ، کثیر کرایہ دار ایجنٹ کے بنیادی ڈھانچے کی تلاش اور استعمال کر رہی ہیں جہاں لاگتیں کسی ایک مالک تک محدود نہیں ہیں۔ یہ وہ جگہ ہے جہاں بنیادی ڈھانچے کی لاگت کی نگرانی کے لیے مشاہداتی کلید بن جاتی ہے۔
اس گائیڈ میں، آپ یہ سیکھیں گے کہ مشاہدہ کیسے کام کرتا ہے، کلاڈ کوڈ کی بلٹ ان ٹیلی میٹری کو فعال کرنا اور میٹرکس، لاگز، اور نشانات کو جمع کرنے اور پڑھنے کے لیے بیک اینڈ چلانا۔ اس سے آپ کو اپنی ٹیم کے اخراجات کو بہتر طریقے سے ٹریک کرنے میں مدد ملے گی، اور آپ کی برآمد شدہ ٹیلی میٹری کے پختہ ہونے اور آپ کے سیشنز کے ساتھ زیادہ واضح طور پر تعلق کے ساتھ ہی بہتری آئے گی۔
میمو: اپنی موجودہ حالت میں، کلاڈ کوڈ سے خارج ہونے والی ٹیلی میٹری ایسی خصوصیات فراہم نہیں کرتی ہے جو نامزد سیشنز کو قابل اعتماد میپنگ کی اجازت دیتی ہیں۔ آپ استعمال کو ٹریک کرنے کے لیے session_id استعمال کر سکتے ہیں، لیکن یہ اب بھی طویل سیشنز کے لیے اناڑی ہے جس میں متعدد اشارے/مہارتیں مل جاتی ہیں۔
اس گائیڈ کے دائرہ کار میں شامل ہیں: Claude Codeمیٹرکس، لاگز اور ٹریسنگ کے لیے ٹیلی میٹری۔ یہ صرف لینکس اور میک او ایس پر لاگو ہوتا ہے۔
انڈیکس
OpenTelemetry کے ساتھ مشاہدہ
آبزرویبلٹی اس سے خارج ہونے والے ڈیٹا سے سسٹم کے رن ٹائم رویے کے بارے میں سوالات کا جواب دینے کی صلاحیت ہے۔ آپ ہڈ کے نیچے دیکھنے، ڈیبگر منسلک کرنے، سورس کوڈ کو پڑھنے، یا رویے کو دستی طور پر دوبارہ پیش کرنے کی کوشش کیے بغیر ایسا کر سکتے ہیں۔
یہاں، نظام کے رن ٹائم رویے سے مراد اس کے بیرونی طور پر دکھائی دینے والے رویے سے ہے۔ آپ سوالات پوچھ سکتے ہیں جیسے:
-
تمام درخواستوں میں سے 95% کے لیے یہ وقت لگتا ہے۔
-
موصول ہونے والی تمام درخواستوں کی ناکامی کی شرح کیا ہے؟
-
سروس کے ذریعے استعمال کیے جانے والے ان میموری کیش کے لیے کیش ہٹ ریٹ کیا ہے؟
-
سروس کے لیے ترتیب دی گئی نقلوں کی تعداد اور تعینات کردہ نقلوں کی تعداد کے درمیان فرق۔
کلاڈ کوڈ کے معاملے میں، داخلی کارروائیاں جو ناقابل رسائی ہیں یہ ہیں کہ یہ کس طرح سیاق و سباق کا انتظام کرتا ہے، یہ کس طرح کام کو متعدد LLM کالوں میں تقسیم کرتا ہے، اور یہ کس طرح ذیلی ایجنٹوں کو مربوط کرتا ہے۔ تاہم، آپ کلاڈ کے کوڈ سے خارج ہونے والی ٹیلی میٹری کو پڑھ سکتے ہیں اور سوالات کے جواب دے سکتے ہیں جیسے:
-
یہ وہ رقم ہے جو ایک ڈویلپر یا ٹیم ایک دن، ہفتے یا مہینے میں خرچ کرتی ہے۔
-
اس استعمال کو کس طرح تعاون یافتہ ماڈلز اور کام کے بوجھ کی سطحوں میں تقسیم کیا جاتا ہے۔
-
فی ڈالر کتنے ٹوکن استعمال کیے جاتے ہیں اور قسم (ان پٹ، آؤٹ پٹ، کیش ریڈ، کیش جنریشن) پر منحصر ہے۔
-
کمپیکشن ایونٹ کب شروع ہوا اور اس نے سیاق و سباق کے ٹوکن کے استعمال کو کتنا کم کیا۔
ان سوالوں کا جواب صرف آلاتی نظام ہی دے سکتے ہیں۔ انسٹرومینٹیشن ایک ڈویلپر کے ذریعہ شامل کردہ کوڈ کا ایک ٹکڑا ہے یا ایک ایسے ٹول میں بنایا گیا ہے جو پروگرام کے رن ٹائم رویے کو ریکارڈ کرتا ہے اور اسے ٹیلی میٹری کے طور پر برآمد کرتا ہے۔ مثال کے طور پر درج ذیل پیمائشیں ہیں۔ this request spent 100 tokens.
ٹیلی میٹری ڈیٹا وقت کے ساتھ نظام کے رویے کا ایک اچھی طرح سے ساختہ ڈیٹا ٹریس فراہم کرکے خاموش غلطیوں کو روکنے میں مدد کرتا ہے۔ مثال کے طور پر، یہاں GitHub کے 17 اگست 2026 کے آؤٹیج فالو اپ کا ایک چارٹ ہے، جو GitHub ایکشنز کو وقت کے ساتھ ~ 30M سے ~ 110M تک بڑھتے ہوئے ظاہر کرتا ہے:
ٹیلی میٹری ڈیٹا
برآمد شدہ ٹیلی میٹری ڈیٹا کی تین اقسام پر مشتمل ہے:
-
میٹرکس: ایک عددی پیمانہ جو وقت کی ایک مدت میں جمع ہوتا ہے، جیسے سوالات فی سیکنڈ (QPS)۔
-
لاگ: ٹائم اسٹیمپ کے ساتھ انفرادی واقعات کے تفصیلی ریکارڈ۔ ایک مثال کلاڈ کوڈ کا کمپریشن ایونٹ ہے۔
-
ثبوت: نظام کے ذریعے ایک واحد درخواست کا راستہ، وقت کے لحاظ سے نیسٹڈ درخواستوں میں تقسیم۔ مثال کے طور پر، ای کامرس ویب سائٹ پر آرڈر کی درخواست ظاہر کرتی ہے کہ درخواست کو مکمل کرنے کے لیے کن داخلی خدمات کو بلایا جاتا ہے۔
OpenTelemetry (https://opentelemetry.io/) ایک مشاہداتی فریم ورک ہے جو ان سگنلز کو پیدا کرنے، اکٹھا کرنے، اور بیک اینڈ پر ایکسپورٹ کرنے میں مدد کرتا ہے جو اسٹوریج، استفسار اور ویژولائزیشن کو ہینڈل کرتا ہے۔ اس تقسیم کو برقرار رکھنا یقینی بناتا ہے کہ بیک اینڈ ٹول/وینڈر ایگنوسٹک ہے، جو اوپن سورس یا ملکیتی ہو سکتا ہے۔ ہم کئی پروگرامنگ زبانوں کے لیے آلات SDKs فراہم کرتے ہیں۔
کلاڈ کوڈ کا آلہ
انسٹرومینٹیشن کوڈ عام طور پر آپ کی ایپلیکیشن کے ساتھ اس مقام پر چلتا ہے جو پیمائش کے لیے موزوں ترین ہے: مڈل ویئر جہاں کوئی درخواست آتی ہے، جواب آتا ہے، یا ٹوکن کی گنتی کی جاتی ہے۔
آپ کی درخواست سے جڑنے کے دو طریقے ہیں:
-
مشترکہ انسٹرومینٹیشن لائبریریاں: وہ ایپلیکیشنز جو اوپن سورس فریم ورک استعمال کرتی ہیں، انسٹرومینٹیشن لائبریریوں کو انحصار کے طور پر شامل کر سکتی ہیں اور انہیں ایپلی کیشن کے لائف سائیکل طریقوں سے منسلک کر سکتی ہیں۔ OpenTelemetry مختلف فریم ورکس (مثلاً اسپرنگ فریم ورک) کے لیے آلات کی لائبریریاں شائع کرتی ہے۔
-
ایپلیکیشن ڈویلپرز کے لیے حسب ضرورت عمل درآمد: ٹیلی میٹری ڈیٹا ایمیٹرز کو براہ راست کوڈ بیس میں OpenTelemetry SDK کا استعمال کرتے ہوئے شامل کیا جاتا ہے۔ بند سورس پروڈکٹس کے لیے، کوڈ نجی ہے لیکن پھر بھی ٹیلی میٹری ڈیٹا برآمد کر سکتا ہے جو OpenTelemetry معیار کے مطابق ہو۔
مثال: HTTP انسٹرومینٹیشن
HTTP پروسیسنگ میں مڈل ویئر تمام درخواستوں کے لیے عام کوڈ کا راستہ ہے اور اس لیے اسے ایپلیکیشن کی وسیع ترتیبات جیسے کہ تصدیق کے لیے منتخب کیا جاتا ہے۔ اسی وجہ سے، یہ انسٹرومینٹیشن کوڈ کے لیے ایک اچھی جگہ ہے۔ یعنی یہ ہینڈلر کو ایک بار لپیٹتا ہے اور ہر درخواست کی پیمائش کرتا ہے۔
آریھ درخواست کے راستے کے نسبت آلے کا مقام دکھاتا ہے۔
-
کلائنٹ کی درخواستیں ایپلی کیشن کے درخواست ہینڈلر اور ڈاؤن اسٹریم کالز تک پہنچنے سے پہلے HTTP مڈل ویئر سے گزرتی ہیں۔ مڈل ویئر ہینڈلر کے وقت، ریکارڈ کی مدت، حالت، اور شمار کی پیمائش کرنے کے لیے SDK کنفیگریشن کا استعمال کرتا ہے۔
-
پھر SDK ان پیمائشوں کو بفر کرتا ہے اور درخواست کے راستے سے باہر پس منظر کے دھاگے میں OTLP کو کلکٹر کی طرف دھکیلتا ہے۔
Claude Code دوسری بار ہے جب Anthropic ایک بنیادی ایپ اور ایک انسٹرومینٹیشن ماڈیول دونوں پیش کرتا ہے۔ اس میں ٹوکن کے استعمال، لاگت اور ٹول کالز کی پیمائش کرنے اور OTLP کے ذریعے OpenTelemetry برآمد کرنے کے لیے بلٹ ان کوڈ ہے۔ کلاڈ کوڈ استعمال کرنے والوں کو صرف ٹیلی میٹری کو فعال کرنے اور اسے وصول کرنے اور تجزیہ کرنے کے لیے بیک اینڈ تیار کرنے کی ضرورت ہے۔
میمو: OTLP ایک ٹیلی میٹری ڈیٹا ڈیلیوری پروٹوکول ہے جسے OpenTelemetry پروجیکٹ کے دائرہ کار میں ڈیزائن کیا گیا ہے۔ یہ گائیڈ OTLP کے ساتھ آخر سے آخر تک مطابقت رکھتا ہے۔ غیر موازن ٹیلی میٹری کو جوڑنا یا غیر موازن بیک اینڈ اجزاء کا استعمال غیر متوقع نتائج کا باعث بن سکتا ہے اور یہ دائرہ کار سے باہر ہیں۔
ٹیلی میٹری کو جمع کرنے، ذخیرہ کرنے اور پڑھنے کے لیے درج ذیل اجزاء کی ضرورت ہے:
-
اوپن ٹیلی میٹری کلیکٹر: ٹیلی میٹری ڈیٹا کو وصول کرنے، اس پر کارروائی کرنے اور برآمد کرنے کے طریقہ کار کا ایک وینڈر سے آزاد عمل۔ یہ اختیاری ہے، لیکن ذاتی نوعیت کے لیے بہت اچھا ہے۔ پیداوار کے استعمال کے معاملات میں ہونا ضروری ہے۔
-
Jaeger: اوپن سورس ٹول کے بطور Uber کے ذریعہ جاری کردہ ایک تقسیم شدہ ٹریکنگ بیک اینڈ۔
-
Prometheus: ٹائم سیریز کے ڈیٹا کے طور پر میٹرکس کو جمع اور اسٹور کریں۔
-
لوکی: گرافانا کا توسیع پذیر لاگ جمع کرنے کا نظام۔
-
گرافانا: لاگز، میٹرکس اور نشانات کے UI تصور کے لیے۔
پل بمقابلہ پش: ٹیلی میٹری آپ کی ایپ کو کیسے چھوڑتی ہے۔
ٹیلی میٹری ایپلیکیشن کو دو طریقوں میں سے ایک میں ختم کرتی ہے:
کھینچنا (کھنچنا): ایپ موجودہ میٹرکس کو HTTP کے اختتامی نقطہ پر ظاہر کرتی ہے، اور سکریپر (Prometheus) وقتاً فوقتاً اس اختتامی نقطہ کو پڑھتا ہے۔ ہر چلنے والی مثال کو اپنی بندرگاہ کی ضرورت ہوتی ہے، اور کھرچنے والے کو ان تمام پتوں کو پہلے سے جاننے کی ضرورت ہوتی ہے۔ ایپ غیر فعال ہے۔ سکریپر ڈیٹا کی نقل و حرکت کو چلاتے ہیں۔ یہ مستحکم پتوں کے ساتھ دیرپا عمل کے لیے موزوں ہے۔
OpenTelemetry میں پول پر مبنی سکریپنگ پر مشتمل ہے: OTEL_METRICS_EXPORTER=prometheus (جاری برآمدی قدروں کے لیے SDK ماحولیاتی متغیرات دیکھیں)
کنونشن کے مطابق، ایپس میٹرکس کو دستیاب کرتی ہیں: http://localhost:9464/metrics. یہ برآمد صرف میٹرکس پر کارروائی کرتی ہے۔
پش (OTLP): ایپ وقتا فوقتا ٹیلی میٹری وصول کرنے والے اختتامی نقطہ پر بھیجتی ہے۔ یہ زیادہ لچکدار ہے۔ آپ پہلے سے رجسٹریشن کے بغیر کسی بھی عمل کو ایک ہی اختتامی نقطہ پر دھکیل سکتے ہیں، آپ کو اپنی ایپ کو شروع کرنے اور روکنے کی آزادی فراہم کرتے ہوئے یہاں تک کہ اگر پتہ تبدیل ہو جائے۔
OpenTelemetry میں، ایک دھکا اس طرح ترتیب دیا گیا ہے: OTEL_METRICS_EXPORTER=otlpOTLP برآمد کنندگان کے ذریعے بھیج دیا گیا۔
پش ماڈل میٹرکس، لاگز اور ٹریس فراہم کر سکتا ہے۔
کلیکٹر چلاتے وقت
کلیکٹر کو اس وقت تعینات کیا جاتا ہے جب موجودہ اسٹیک سسٹم کے بڑھتے ہوئے سائز اور پیچیدگی کو سنبھالنے کے لیے کافی نہیں ہوتا ہے۔ یہ درج ذیل طریقوں سے آپ کی مدد کر سکتا ہے:
-
ایک برآمد کنفیگریشن: ہر پروڈیوسر اپنا بیک اینڈ مخصوص ایکسپورٹ سیٹ اپ کرنے کے بجائے کلکٹر کی طرف اشارہ کرتا ہے۔
-
صرف آؤٹ باؤنڈ کنکشن: کارپوریٹ نیٹ ورکس اکثر ان باؤنڈ کنکشن کو مسدود کردیتے ہیں جن کی ضرورت پل پر مبنی سکریپرز کو ہوتی ہے۔ کلکٹر کے ساتھ، آپ کو ان باؤنڈ ٹریفک کی اجازت دینے کی ضرورت نہیں ہے کیونکہ آپ کی ایپ کو کلکٹر کی طرف دھکیل کر آگے بڑھایا جاتا ہے۔
-
مداح اور ترجمہ: کلکٹر ٹیلی میٹری کو وینڈر کے سٹوریج کی شکل میں تبدیل کرتا ہے اور ایک سے زیادہ بیک اینڈ کو ایک ہی سگنل بھیج سکتا ہے۔
-
بفرنگ: اگر پسدید نیچے جاتا ہے تو، کلکٹر ڈیٹا کو محفوظ کرتا ہے اور عارضی غلطیوں کو جذب کرنے کی کوشش کرتا ہے۔
-
علاج: پروسیسرز کو ڈیٹا کے سٹوریج کے لیے چھوڑنے سے پہلے لاگو کیا جا سکتا ہے، جیسے کہ خصوصیات میں ترمیم کرنا۔
میمو: یہ گائیڈ پش بیسڈ کنفیگریشن چلانے کے لیے کلکٹر کا استعمال کرتی ہے، چاہے یہ سنگل یوزر سیٹ اپ ہو۔ اسٹیک میں تین بیک اینڈز ہیں جو ڈیٹا کو مختلف طریقے سے اسٹور اور استفسار کرتے ہیں، اور کلکٹر کو کلاڈ کوڈ کے OTLP کو ایک بار سننے اور ہر سگنل کو صحیح جگہ پر پہنچانا ایپ کو تینوں سے مربوط کرنے سے آسان ہے۔ اس لیے ٹولز کی فہرست اسے ذاتی استعمال کے لیے اختیاری لیکن پیداوار کے لیے ضروری قرار دیتی ہے۔ اس کی قیمت پروڈیوسرز اور بیک اینڈ کی تعداد کے ساتھ بڑھتی ہے۔
شرطیں
اس گائیڈ کا ہر سیکشن متعلقہ دستاویزات سے لنک کرتا ہے، لیکن اگر آپ نیچے بیان کردہ ٹولز اور استفسار کی زبان سے پہلے ہی واقف ہیں تو آپ مزید تیزی سے آگے بڑھ سکتے ہیں۔
آپ کی ضرورت ہے
علم جو مدد کرے گا۔
-
ڈوکر کمپوز: کمپوز فائل میں کنٹینرز کی تعریف حاصل کریں اور کنٹینر کی حیثیت اور لاگز پڑھیں۔
docker compose ...حکم -
باش اور کنفیگریشن فائلیں: ماحولیاتی متغیرات کو ترتیب دینا، JSON فائلوں میں ترمیم کرنا۔
-
PromQL (Prometheus): کاؤنٹر/گیجز، رینج سلیکٹر اور ان کا استعمال کیسے کریں۔
sum/increase/rate/by(لیبل) گروپ بندی۔ -
گرافانا: اعداد و شمار کے ذرائع کو دریافت کریں اور اعداد و شمار اور ٹائم سیریز پینلز کا استعمال کرتے ہوئے ڈیش بورڈز بنائیں۔ پینل کی تبدیلیاں اور عالمی متغیرات۔
-
لاگ کیو ایل (لوکی): اسٹریم سلیکٹر، لاگ ایف ایم ٹی، اور لیبل_فارمیٹ۔
-
Jaeger اور ٹریکنگ: Jaeger UI میں ٹریکنگ/اسکوپ ماڈل (والدین کے بچے کا دائرہ کار، اسکوپس کی تعداد، دورانیہ) اور ٹیگ کی تلاش۔
-
کلاڈ کوڈ کا عمل درآمد ماڈل: سیشنز، سب ایجنٹس، ٹیکنالوجیز، ٹولز، اور سیاق و سباق کمپریشن۔
-
کلاڈ بلنگ کی بنیادی باتیں: ٹوکن اور فوری کیشنگ پرتیں۔
ترتیب
ٹیسٹ مشاہداتی اسٹیک ڈوکر کمپوز کا استعمال کرتے ہوئے تعینات کیا گیا ہے۔ ٹیلی میٹری ایکسپورٹ کام کرنے کے لیے، کلاڈ کوڈ کو کلکٹر کے OTLP اینڈ پوائنٹ تک پہنچنے کے قابل ہونا چاہیے، جو کہ لوکل ہوسٹ:4317 (gRPC) یا لوکل ہوسٹ:4318 (HTTP) ہے جب ایک ہی مشین پر چل رہا ہے۔ تمام پسدید خدمات مستقل مزاجی کے لیے کنٹینرز میں ان کی اپنی ڈوکر والیوم کے ساتھ چلتی ہیں۔
خاکہ دکھاتا ہے کہ ٹیلی میٹری کے جو اجزاء ہم استعمال کرتے ہیں وہ کس طرح جڑے ہوئے ہیں۔
-
کلاڈ کوڈ کے علاوہ تمام اجزاء ڈوکر کمپوز کے زیر انتظام کنٹینرز میں چلتے ہیں۔
-
کسی بھی مشین (میزبان یا کلاؤڈ VM) پر چلنے والے کلاڈ کوڈ کی متعدد مثالیں اس وقت تک کلکٹر کو ٹیلی میٹری برآمد کرنے کے قابل ہوں گی جب تک کہ وہ مشین منسلک ہے (اگر یہ کلکٹر کنٹینر چلانے والے میزبان پر 4317/4318 بندرگاہوں سے جڑ سکتی ہے)۔
اوپر سے نیچے منتقل کریں:
-
کلاڈ کوڈ تینوں سگنل کلیکٹر کو OTLP کے ذریعے برآمد کرتا ہے۔
-
کلکٹر پھر اسے قسم کے لحاظ سے تقسیم کرتا ہے، نشانات کو جیگر کی طرف دھکیلتا ہے اور انہیں لوکی میں لاگ کرتا ہے، جبکہ پرومیتھیس کو کھرچنے کے لیے پورٹ 8889 پر میٹرکس کو بھی ظاہر کرتا ہے۔
-
جیگر، پرومیتھیس اور لوکی ہر ایک اپنی اپنی ڈوکر والیوم کو برقرار رکھتے ہیں۔
-
گرافانا تینوں کو ایک ہی ڈیش بورڈ پرت کے طور پر استفسار کرتا ہے۔
یہاں کا مقصد کلاڈ کوڈ سے ریئل ٹائم ٹیلی میٹری کا ایک سلسلہ ہے جو بیک اینڈ پر اسٹور کیا جاتا ہے اور مطالبہ پر، سیشن کے دوران، یا اس کے بعد کافی عرصے بعد استفسار کیا جا سکتا ہے۔ آپ کو دو چیزیں تیار رکھنے کی ضرورت ہے۔
-
کلاڈ کوڈ میں ٹیلی میٹری کو فعال کریں۔ انسٹرومینٹیشن بلٹ ان ہے، لیکن ٹیلی میٹری کے فعال ہونے تک کچھ بھی برآمد نہیں کیا جاتا اور متعلقہ OTLP ایکسپورٹ کلکٹر کی طرف اشارہ کرتا ہے۔
-
ایک مشاہداتی پس منظر چلاتا ہے۔ کلکٹر ہر سگنل پر کارروائی کرتا ہے اور استفسار کے لیے اسے پرومیتھیس، لوکی اور جیگر تک پہنچاتا ہے۔
پہلے ہم بیک اینڈ شروع کرتے ہیں تاکہ ہمارے پاس ٹیلی میٹری کرنے کی جگہ ہو۔
مشاہداتی پس منظر کے ساتھ شروع کرنا
Claude Code میں ٹیلی میٹری کو فعال کرنے سے پہلے، یقینی بنائیں کہ آپ کا اسٹیک ڈیٹا اکٹھا، پروسیس اور پڑھ سکتا ہے۔ ٹیسٹ آبزرویبلٹی بیک اینڈ کا کوڈ اس گیتھب ریپوزٹری میں ہے۔
ذخیرہ کی ساخت مندرجہ ذیل ہے:
.
├── README.md
└── compose
├── docker-compose.yml # Docker config for 5 containers in the observability stack. Applies pinned image versions, port mappings and named volumes for each service.
├── grafana
│ └── provisioning
│ ├── alerting
│ ├── dashboards
│ ├── datasources # datasources(Prometheus, Loki, Jaeger) and dashboards. Empty initially.
│ └── plugins
├── jaeger-config.yaml # Jaeger v2, badger (local-file) storage for traces. Ties to the user: root TIP below.
├── loki-config.yaml # single-binary Loki, filesystem storage. Near default settings.
├── otel-collector-config.yaml # receive/process/export pipeline: OTLP in on 4317/4318, traces out to Jaeger, logs to Loki, metrics exposed on :8889 for Prometheus.
└── prometheus.yml # a single scrape job against the Collector's :8889, 30s interval.
آپ کو صرف ضرورت ہے docker compose کنٹینر شروع کرنے کا حکم۔ یہ docker-compose.yml پڑھتا ہے اور کنٹینر کو شروع کرتا ہے، اس کنفیگریشن فائل سے منسلک ہوتا ہے۔
انٹر کنٹینر کنکشن:
تمام کنٹینرز ایک ہی ڈوکر نیٹ ورک کے اندر شروع کیے گئے ہیں، لہذا وہ کنٹینر کے ناموں کا استعمال کرتے ہوئے براہ راست بات چیت کر سکتے ہیں۔ مثال کے طور پر، کلکٹر کی ایکسپورٹ کنفیگریشن کنٹینر کا نام استعمال کرتی ہے۔
exporters:
otlp/jaeger:
endpoint: jaeger:4317
tls:
insecure: true
prometheus:
endpoint: 0.0.0.0:8889
otlphttp/loki:
endpoint: http://loki:3100/otlp
اس میں کوئی Prometheus کنفیگریشن نہیں ہے، کیونکہ Prometheus اسے کلکٹر سے سکریپ کرتا ہے جیسا کہ prometheus.yml میں ترتیب دیا گیا ہے۔
global:
scrape_interval: 30s
scrape_configs:
- job_name: otel-collector
static_configs:
- targets: ["otel-collector:8889"]
ڈوکر کمپوز کا استعمال کرتے ہوئے ایک کنٹینر شروع کریں۔
git clone https://github.com/ps-mir/otel-dev-stack.git
cd otel-dev-stack/compose
docker compose up -d
# Output
✔ Volume compose_loki_data Created 0.0s
✔ Volume compose_grafana_data Created 0.0s
✔ Volume compose_prometheus_data Created 0.0s
✔ Volume compose_jaeger_data Created 0.0s
✔ Network compose_default Created 0.1s
✔ Container compose-prometheus-1 Started 4.1s
✔ Container compose-loki-1 Started 4.2s
✔ Container compose-jaeger-1 Started 4.3s
✔ Container compose-otel-collector-1 Started 3.3s
✔ Container compose-grafana-1 Started 2.7s
کنٹینر کی حیثیت کو چیک کریں۔
# all five services should show "Up"
docker compose ps
# Output
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
compose-grafana-1 grafana/grafana:13.2.0 "/run.sh" grafana 3 minutes ago Up 3 minutes 0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp
compose-jaeger-1 cr.jaegertracing.io/jaegertracing/jaeger:2.20.0 "/go/bin/jaeger --co…" jaeger 3 minutes ago Up 3 minutes 0.0.0.0:16686->16686/tcp, [::]:16686->16686/tcp
compose-loki-1 grafana/loki:3.7.6 "/usr/bin/loki -conf…" loki 3 minutes ago Up 3 minutes 0.0.0.0:3100->3100/tcp, [::]:3100->3100/tcp
compose-otel-collector-1 otel/opentelemetry-collector-contrib:0.159.0 "/otelcol-contrib --…" otel-collector 3 minutes ago Up 3 minutes 0.0.0.0:4317-4318->4317-4318/tcp, [::]:4317-4318->4317-4318/tcp, 55679/tcp
compose-prometheus-1 prom/prometheus:v3.11.2 "/bin/prometheus --c…" prometheus 3 minutes ago Up 3 minutes 0.0.0.0:9090->9090/tcp, [::]:9090->9090/tcp
ٹپ: Jaeger مندرجہ ذیل کے طور پر چلتا ہے. user: root (فائل بنائیں) ایک بیجر ڈائرکٹری بنائیں۔ ورنہ ایک غلطی ہو جائے گی۔ mkdir /badger/key: permission denied. جیگر کو خود روٹ مراعات کی ضرورت نہیں ہے، لیکن ڈوکر والیوم کی ملکیت ہے: root:root پہلے پہاڑ پر۔
ٹیلی میٹری کو فعال کریں۔
ایک بار ایپلیکیشن میں شامل ہونے کے بعد، OpenTelemetry انسٹرومینٹیشن اس وقت تک غیر فعال رہتا ہے جب تک کہ مخصوص کنفیگریشن کو فعال نہ کیا جائے۔
کلاڈ کوڈ میں ٹیلی میٹری کو فعال کرنے کے دو طریقے ہیں:
1. ماحولیاتی متغیرات
کچھ ماحولیاتی متغیرات کو ترتیب دینا ٹیلی میٹری کی نسل کو قابل بناتا ہے۔ معیار سے آگے OTEL_* متغیرات، کلاڈ کوڈ خود کی وضاحت کرتا ہے۔ CLAUDE_CODE_* متغیر
یہ گائیڈ درج ذیل ترتیبات کا استعمال کرتا ہے:
# master switch: when unset or 0, Claude Code produces no telemetry at all
export CLAUDE_CODE_ENABLE_TELEMETRY=1
# opt into the beta enhanced-telemetry attributes and events (extra session and tool detail)
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
# per-signal exporter selection; "otlp" ships the signal over OTLP.
# other accepted values are "console" (print locally), "prometheus" (metrics only), and "none" (drop the signal)
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
# OTLP transport: "grpc" talks to the collector's 4317 port; "http/protobuf" would use 4318
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
# one endpoint for all three signals: the collector's OTLP listener on the local machine
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# how often metrics are flushed, in milliseconds; the default is 60000 (60s),
# shortened here so a manual check sees fresh data without a long wait
export OTEL_METRIC_EXPORT_INTERVAL=5000
# emit cumulative counters instead of delta (see "Aggregation Temporality" below)
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative
تاہم، ماحولیاتی متغیر عمل کے لحاظ سے وسیع ہیں اور Claude Code سے زیادہ متاثر کر سکتے ہیں۔ مثال کے طور پر،
-
آپ نے غلطی سے کسی اور ایپلیکیشن میں انسٹرومینٹیشن کو فعال کر دیا ہے۔
-
اگر آپ اپنا آلہ تیار کرتے ہیں یا OpenTelemetry SDK پر کام کرتے ہیں، تو یہ OpenTelemetry کوڈ/ٹیسٹنگ میں مداخلت کرے گا۔
2. کلاڈ کوڈ settings.json
OpenTelemetry Declarative Config کی وضاحت کرتا ہے، YAML پر مبنی کنفیگریشن جو ٹیلی میٹری کو فعال کرتی ہے، لیکن کلاڈ کوڈ اس کی حمایت نہیں کرتا ہے۔ لیکن آپ ایک ہی ماحول کے متغیرات کو ترتیب دے سکتے ہیں۔ ~/.claude/settings.json. یہ اعلانیہ ترتیب نہیں ہے، لیکن یہ شیل ماحول کے متغیر سے بہتر ہے کیونکہ یہ صرف کلاڈ کوڈ پر لاگو ہوتا ہے۔ ہاں:
{
"effortLevel": "medium",
"tui": "fullscreen",
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_TRACES_EXPORTER": "otlp",
"OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_METRIC_EXPORT_INTERVAL": "5000",
"OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "cumulative"
}
}
صرف env ٹیلی میٹری کے لیے بلاک کا مسئلہ۔ effortLevel اور tui یہ ایک غیر متعلقہ ترتیب ہے جو آپ کے پاس پہلے سے موجود ہو سکتی ہے۔ متغیرات اوپر بیان کردہ فہرست سے ملتے ہیں۔
مجموعی عارضی
پرومیتھیس کاؤنٹر ٹائپ میٹرکس وقت کے ساتھ بڑھتے ہیں۔ خام قدریں کارآمد نہیں ہیں، اس لیے ہم انہیں انکریمنٹ فی سیکنڈ میں پڑھتے ہیں (rate()) یا وقت کی ایک مدت میں کل نمو (increase())۔
ایگریگیشن عارضیت اس تعداد کا تعین کرتی ہے جو کاؤنٹر ہر ٹیلی میٹری ایکسپورٹ کے لیے رپورٹ کرتا ہے: پچھلی ایکسپورٹ (ڈیلٹا) کے بعد سے تبدیلی یا عمل شروع ہونے کے بعد سے مجموعی کل (مجموعی)۔
یہاں ایک مختصر مثال ہے۔ ہم کہتے ہیں کہ کلاڈ کوڈ 5 سیکنڈ کے ایکسپورٹ وقفے کے ساتھ ٹوکن کو چار بار استعمال کرتا ہے۔
| برآمد مقام | آخری برآمد کے بعد سے ٹوکن | ڈیلٹا ویلیو منتقل کی گئی۔ | مجموعی قدر بھیجی گئی۔ |
|---|---|---|---|
| 0 سیکنڈ (شروع) | — | — | 0 |
| 5 سیکنڈ | 100 | 100 | 100 |
| 10 سیکنڈ | 0 | 0 | 100 |
| 15 سیکنڈ | 250 | 250 | 350 |
| 20s | 50 | 50 | 400 |
پہلے سے طے شدہ طور پر، کلاڈ کوڈ درج ذیل میٹرکس کو خارج کرتا ہے: AggregationTemporality: Delta. درج ذیل کمانڈ کا استعمال کرتے ہوئے کلکٹر کے کنٹینر لاگ میں اس کا معائنہ اور تصدیق کی جا سکتی ہے۔
# Command only works from directory containing docker-compose.yml
docker compose logs otel-collector
میمو: کلکٹر میں تفصیلی لاگز کو فعال کرنے کے لیے debug کلکٹر کنفیگریشن میں ایکسپورٹ کریں۔
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlp/jaeger, debug]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [prometheus, debug]
پھر کنٹینر کو دوبارہ شروع کریں۔
# Command only works from directory containing docker-compose.yml
docker compose up -d --force-recreate otel-collector
آؤٹ پٹ لاگ کا استعمال کرتے ہوئے AggregationTemporality: Delta:
otel-collector-1 | Descriptor:
otel-collector-1 | -> Name: claude_code.active_time.total
otel-collector-1 | -> Description: Total active time in seconds
otel-collector-1 | -> Unit: s
otel-collector-1 | -> DataType: Sum
otel-collector-1 | -> IsMonotonic: true
otel-collector-1 | -> AggregationTemporality: Delta <---
otel-collector-1 | NumberDataPoints #0
ڈیلٹا مندرجہ ذیل Prometheus خصوصیات کے ساتھ اچھا نہیں کھیلتا: rate()/increase()کیونکہ آپ کو مجموعی اقدار کی توقع ہے۔
ماحول OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative برآمد شدہ میٹرکس کو ڈیلٹا سے مجموعی عارضی میں تبدیل کریں۔ اس گائیڈ میں استعمال ہونے والی env اور JSON کنفیگریشن دونوں میں شامل کیا گیا۔
پہلے کی طرح، آپ کو کلکٹر کنٹینر کے اثر میں آنے کے لیے کسی بھی ترتیب میں تبدیلی کے بعد اسے دوبارہ شروع کرنا چاہیے۔
ٹیلی میٹری نیویگیشن
ٹیلی میٹری بہاؤ آپ کو سوالات شروع کرنے کی اجازت دیتا ہے۔ ذیل کے تین حصے بڑی حد تک آزاد ہیں، جیسا کہ میٹرکس، لاگز، اور ٹریس ہر ایک کلاڈ کوڈ کے استعمال کے بارے میں مختلف قسم کے سوالات کے جوابات دیتے ہیں۔
اس کے پیچھے ڈیٹا دو جگہوں سے آتا ہے۔
-
میٹرکس اور لاگز سیکشن کلاؤڈ کوڈ کے استعمال کو بیک اینڈ پر جمع کرتا ہے، لہذا پینل اپنے سیشن دکھاتا ہے اور نمبر اسکرین شاٹ سے میل نہیں کھاتے ہیں۔ ان سے آپ کو بہت کچھ دکھانے کی توقع کرنے سے پہلے انہیں کچھ ہینڈ آن سیشن دیں۔
-
اس کے بجائے، ٹریکنگ سیکشن ایک بامقصد عمل کے ذریعے آپ کی رہنمائی کرتا ہے، ایک حسب ضرورت تکنیک جو میٹنگوں کے سلسلے کا خلاصہ کرتی ہے، اور اس کی پیروی کرنے کے لیے کافی تفصیلی ہے۔ اسے دوبارہ پیش کرنے کی ضرورت نہیں ہے۔
میٹرکس
میٹرکس کلاڈ کوڈ کے استعمال کا ایک مجموعی، تاریخی نظریہ ہے۔ مثالیں: کل لاگت، ٹوکن والیوم، اور ہر ایک وصف کے لیے رجحانات اور تجزیہ کے طریقے۔ model, effortاور ٹوکن type. اسے اپنے اخراجات کی نگرانی کے لیے استعمال کریں اور اپنے اخراجات میں تبدیلیوں کو دیکھیں۔
ہر میٹرک ایک عددی پیمائش ہے جو وقت کے ساتھ ریکارڈ کی جاتی ہے، ٹائم اسٹیمپڈ اقدار کی ایک ٹائم سیریز جو ظاہر یا جمع کی جا سکتی ہے۔ کلاڈ کوڈ کی میٹرکس رقم (کاؤنٹر) چل رہی ہیں، لہذا سوالات خام اقدار کے بجائے منتخب ونڈو میں تبدیلیوں کی اطلاع دیتے ہیں۔ یہ کیسے کام کرتا ہے اس کے لیے اوپر مجموعی عارضیت دیکھیں۔
Prometheus یہاں استعمال ہونے والا میٹرکس پسدید ہے۔ سکریپ کلیکٹر، اسٹور سیریز، اور PromQL میں لکھے گئے سوالات کا جواب دیں۔ گرافانا آپ کے ڈیش بورڈ کے لیے وہی ڈیٹا پڑھتا ہے۔ localhost:3000. میٹرکس اور ان کی خصوصیات کی مکمل فہرست کلاڈ کوڈ مانیٹرنگ دستاویزات میں مل سکتی ہے۔
اپنے براؤزر میں Prometheus کھولیں (localhost:9090) اور ٹائپ کریں: claude استفسار کا فیلڈ معاون میٹرکس دکھاتا ہے۔
ذیل میں ہر ایک میٹرک کے لیے، ہم پہلے اسے PromQL کا استعمال کرتے ہوئے دریافت کرتے ہیں اور پھر اسی سوال کا استعمال کرتے ہوئے اسے Grafana ڈیش بورڈ میں بطور پینل شامل کرتے ہیں۔
کل USD خرچ ہوا۔
claude_code_cost_usage_USD_total فی سیشن ٹریک کردہ مجموعی استعمال لاگت (USD) کی نشاندہی کرتا ہے۔ یہ آپ کے بجٹ کو منظم کرنے اور استعمال میں اچانک اضافے کو دریافت کرنے کے لیے مفید ہے۔
یہ ایک کلائنٹ سائیڈ تخمینہ ہے جس کی بنیاد اینتھروپک کے ماڈل کے ساتھ مخصوص، قسم کے مخصوص نرخوں اور مجموعی طور پر قیمت والے ٹوکنز کی تعداد پر ہے۔ کلاڈ کوڈ پلان کی سبسکرپشن لاگت سے تجاوز کرنا بالکل معمول کی بات ہے۔
میمو: اگر آپ فی خام API کال ادائیگی کرتے ہیں، تو یہ میٹرک زیادہ اہم ہے۔ سبسکرپشنز بڑھے ہوئے لیکن محدود شرح سے محدود استعمال کے الاؤنس فراہم کرتے ہیں۔
سب سے پہلے، Prometheus میں درج ذیل استفسار کی جانچ کریں (localhost:9090/query):
sum(increase(claude_code_cost_usage_USD_total[10m]))
increase(...[10m]) یہ پچھلے 10 منٹ میں کاؤنٹر میں اضافہ کو ظاہر کرتا ہے۔ sum(...) نہیں by شق وصف کے ذریعہ سیریز کو ختم کرتی ہے (model, effortاور دیگر) ایک نمبر میں۔
گرافانا پینلز کے لیے، فکسڈ پینل کو تبدیل کریں۔ [10m] کھڑکی $__range بلٹ ان متغیرات جن کی قدریں ڈیش بورڈ کے ٹائم چننے والے کی پیروی کرتی ہیں:
sum(increase(claude_code_cost_usage_USD_total[$__range]))
اسے پینل کے طور پر شامل کرنے کے لیے، نیویگیشن کھولیں، ڈیٹا سورس کے طور پر Prometheus کو منتخب کریں، اور استفسار کو چلائیں۔ آپ کے نتائج اس بات پر منحصر ہوں گے کہ آپ نے ونڈوز پر کتنا کلاڈ کوڈ استعمال کیا ہے۔
جب آپ اسے اپنے ڈیش بورڈ میں شامل کریں گے، تو آپ کو مزید پینل کے اختیارات نظر آئیں گے۔ منتخب کریں Stat پینل:
آپ کو اس پینل کو اپنے گرافانا ڈیش بورڈ میں شامل کرنے کی ضرورت ہوگی۔
ٹوکن کا کل استعمال
claude_code_token_usage_tokens_total USD لاگت کے اشارے کے برابر جوابی شکل والے ٹوکنز کی مجموعی تعداد۔ یہ دیکھنے کے لیے کہ آپ کن لیبلز کو جمع کر سکتے ہیں، پہلے پرومیتھیس کی ابتدائی سیریز پڑھیں۔ ایک واحد سلسلہ ہے:
claude_code_token_usage_tokens_total{effort="high", exported_job="claude-code", instance="otel-collector:8889", job="otel-collector", model="claude-sonnet-5", otel_scope_name="com.anthropic.claude_code", otel_scope_version="2.1.252", query_source="auxiliary", session_id="e0b9795b-4da3-4171-8fa6-a2866bf44d86", terminal_type="ssh-session", type="cacheCreation"} 213730
مندرجہ ذیل نمبر کاؤنٹر ویلیو ہے۔ اہم خصوصیات جن کے ساتھ آپ کام کریں گے وہ ہیں: type, modelاور effort. ٹوکن کے استعمال کا چارٹ بذریعہ قسم کے تحت گروپس type.
مدت کی رقم ٹوکن کاؤنٹر کا استعمال کرتے ہوئے کل USD خرچ کے برابر ایک سوال کی شکل میں ہے۔
sum(increase(claude_code_token_usage_tokens_total[$__range]))
ٹوکنز فی USD
پچھلی دو میٹرکس کے برعکس، یہ ایک اخذ کردہ نمبر ہے جسے وقت کے دوران کل ٹوکن/کل لاگت کے حساب سے شمار کیا جاتا ہے۔
sum(increase(claude_code_token_usage_tokens_total[$__range])) / sum(increase(claude_code_cost_usage_USD_total[$__range]))
یہ ایک نمبر تمام انتساب کے مجموعوں کو ایک واحد قدر میں سمیٹتا ہے۔ ہر منفرد امتزاج (مثال کے طور پر درمیانی کوشش میں ماڈل A اور اعلیٰ کوشش میں ماڈل B) اس کی اپنی ٹائم سیریز ہے، اور استفسار تمام مجموعوں پر مشتمل ہے۔
کسی مخصوص امتزاج کا تجزیہ کرنے کے لیے، انتساب کے لحاظ سے وہی فیصد چلائیں اور موازنہ کریں۔
sum by (model) (increase(claude_code_token_usage_tokens_total[$__range]))
/ sum by (model) (increase(claude_code_cost_usage_USD_total[$__range]))
تبادلہ model کے لیے effort یا type; باقی لیبلز اوپر کی خام سیریز میں درج ہیں۔
مکمل نتائج:
اعداد و شمار کا پینل (6 گھنٹے کی کھڑکی): کل خرچ USD ($4.28)، کل ٹوکن خرچ ہوئے (3.02M)، اور ٹوکن فی USD (707,000)۔
قسم کے لحاظ سے ٹوکن کا استعمال
آپ دیکھ سکتے ہیں کہ کس طرح claude_code_token_usage_tokens_total وقت کے ساتھ تبدیلیاں، درجہ بندی کے لحاظ سے type. ٹائم سیریز پینل کا استعمال کریں کیونکہ شکل ایک اعداد و شمار کے ذریعہ چھپی ہوئی ہے۔
کہ type پراپرٹی کی چار قدریں ہیں جن کی قیمتیں بہت مختلف ہیں۔
-
cacheRead: موجودہ کیش اندراج کے ذریعہ فراہم کردہ ایک ٹوکن۔ یہ طویل سیشنوں میں ٹوکن اخراجات پر غالب ہے اور بنیادی شرح سے سستا ہے۔ -
cacheCreation: پہلا سابقہ لوڈ کرتے وقت پرامپٹ کیشے پر لکھا ٹوکن۔ اس پر بہت خرچ آتا ہے۔ -
input: نیا، غیر محفوظ شدہ پرامپٹ ٹوکن۔ -
output: ماڈل تخلیق کا ٹوکن۔
ٹوٹل بھی دیکھنے کے لیے، حوالہ کے لیے دو استفسارات استعمال کریں: قسم کے لحاظ سے ٹوٹل اور غیر تقسیم شدہ ٹوٹل۔
# per-type breakdown
sum by (type) (increase(claude_code_token_usage_tokens_total[$__rate_interval]))
# total
sum(increase(claude_code_token_usage_tokens_total[$__rate_interval]))
__rate_interval ٹائم سیریز پینل کے لیے گرافانا کی مرحلہ وار ونڈو۔ __range اوپر اعداد و شمار کے پینل میں استعمال کیا گیا ہے۔
یہ وہ دو سوالات ہیں جو نیویگیشن کو پینل کے طور پر محفوظ کرنے سے پہلے چل رہے ہیں۔
اسے اپنے ڈیش بورڈ میں شامل کرنے کے بعد:
ہر سپائیک کلاڈ کوڈ کی سرگرمی کا ایک دھماکہ ہے، جبکہ یونیفارم میں اضافہ بیکار وقت ہے۔ جب آپ کسی نقطہ کی طرف اشارہ کرتے ہیں، تو کل کو چار اقسام میں تقسیم کیا جاتا ہے: یہاں کل تقریباً 1 ملین ٹوکن ہیں، جن میں سے cacheRead یہ تقریباً 925k (تقریباً 92%) ہے اور باقی کیش جنریشن، آؤٹ پٹ اور ان پٹ ہے۔
ٹپ: ٹوکن کی کھپت کا غلبہ ہے: cacheReadیہ بھی سب سے سستی قسم ہے۔
ماڈل اور کوشش پر مبنی ٹوکن کا استعمال
یہ تجزیہ کا ایک مخصوص ورژن ہے جو ٹوکن فی USD میں تجویز کیا گیا ہے۔ model اور effort جوڑی دراصل ٹوکن کھا رہی ہے۔
sum by (model, effort) (
increase(claude_code_token_usage_tokens_total[$__rate_interval])
)
یہاں ٹوکن کاؤنٹرز کو مندرجہ ذیل گروپ کیا گیا ہے: model اور effort وصف اس ونڈو میں، تمام سیریز claude-sonnet-5 کسی بھی طرح medium یا high کوشش، اور ایک دھماکہ medium 18:13 کے ارد گرد کی کوشش تقریباً 2.6 ملین ٹوکن تک پہنچ جاتی ہے۔ منفرد گروپ بندیوں کی تعداد منتخب کردہ وصف کی بنیادی حیثیت پر منحصر ہے۔
لاگ
لاگ ریکارڈز ٹائم اسٹیمپ والے واقعات ہوتے ہیں جن میں فیلڈز کا پورا سیٹ منسلک ہوتا ہے۔ جب آپ کوئی خاص واقعہ اور اس کے آس پاس کا سیاق و سباق چاہتے ہیں (کیا ہوا، کب ہوا اور کس قدر کے ساتھ)، آپ لاگ سے استفسار کرتے ہیں۔
میٹرکس ایک ہی سرگرمی کی پہلے سے جمع شدہ شکلیں ہیں۔ کوئی بھی چیز جس کا مطلب ہے حساب لگانا، خلاصہ کرنا، یا ایک سے زیادہ ریکارڈز میں پرسنٹائل لینا ایک میٹرک ہے۔ اگر آپ مجموعی لاگ آؤٹ پٹ ڈاؤن اسٹریم کرتے ہیں، تو وہ ڈیٹا شروع سے ہی ایک میٹرک ہونا چاہیے۔
لاگ ان کے لیے ایک بہترین ٹول ہیں:
-
واقعہ کے حوالے سے مخصوص سیاق و سباق: مجموعی تعداد کے بجائے کسی ایک واقعہ کی مکمل تفصیلات۔
-
مجرد یا بے قاعدہ واقعات: کومپیکشن ایگزیکیوشن، سیشن کا آغاز، یا API کی خرابی۔
-
حادثے کے بعد کی فرانزک: حقیقت کے بعد ڈیبگ کرتے ہوئے خام ریکارڈ کو دوبارہ پڑھیں۔
-
ٹریس ارتباط: ٹریس اور اسکوپ آئی ڈی کے ساتھ لاگ لائنز آپ کو اس درخواست پر لے جاتی ہیں جہاں سے اس کی ابتدا ہوئی تھی۔
یہاں استعمال ہونے والا لاگ بیک اینڈ Loki ہے، LogQL کے ساتھ استفسار کیا گیا ہے۔ اگر آپ اپنے نوشتہ جات کو اس طرح بیک اینڈ کے ذریعے چلاتے ہیں تو آپ کو ملے گا:
-
سٹرکچرڈ فیلڈز: ٹیکسٹ پر ریگولر ایکسپریشنز کی بجائے نامزد کیز کو فلٹر اور حساب لگائیں۔
-
فیلڈ انڈیکسنگ: لیبل کی تلاش تمام لائنوں کو اسکین کیے بغیر واپس کردی جاتی ہے۔
-
ٹریس اور رینج کا ارتباط: لاگ سے متعلقہ ٹریس تک محور یا ایک ٹریس کے لیے تمام لاگز حاصل کریں۔
-
وقتی سوالات: ہر سوال کا دائرہ ایک ونڈو تک ہوتا ہے، جس سے تلاشیں کم مہنگی ہوتی ہیں۔
گرافانا ڈیش بورڈ سے لوکی کو بالکل اسی طرح پڑھتا ہے جیسے یہ پرومیتھیس پڑھتا ہے۔
کمپریسڈ واقعات
کمپریشن وہ ہے جب کلاڈ کوڈ بہت بڑا ہو جاتا ہے، یہ اپنے سیاق و سباق کو کاٹ دیتا ہے۔ ہر کمپریشن لاگ ایونٹ کے ساتھ شروع ہوتا ہے (event_name="compaction") پہلے اور بعد میں ٹوکن کی تعداد رکھتا ہے (pre_tokens, post_tokens) اور span_id چونکہ یہ ذیل میں ہوا ہے، اس واقعہ کے لیے استفسار کرنا آپ کو بتائے گا کہ یہ کتنی بار ہوتا ہے اور ہر بار اسے کتنا یاد کیا جاتا ہے۔
Grafana Explore میں، Loki کو ڈیٹا سورس کے طور پر منتخب کریں اور LogQL کو نیچے چسپاں کریں۔ ایک کمپریسڈ ایونٹ منتخب کریں اور اس کے فیلڈز کو پارس کریں۔ logfmtایونٹ کے لیے مخصوص کمی کی شرح حاصل کرنے کے لیے استعمال کریں۔ label_format. فیلڈز صرف کمپریشن کے واقع ہونے کے بعد موجود ہیں، لہذا پہلے کچھ چیزوں کو متحرک کریں۔
{service_name="claude-code"} | event_name="compaction"
| logfmt
| label_format reduction_pct=`{{ printf "%.1f" (mulf (divf (subf .pre_tokens .post_tokens) .pre_tokens) 100) }}`
اخذ reduction_pct یہ یہاں ٹھیک ہے کیونکہ ہر ریکارڈ فی ایونٹ برقرار رکھا جاتا ہے۔ کمپریشنز میں چلنے والی اوسط میٹرک سے تعلق رکھتی ہے۔
کہ label_format لائن میں شامل کریں reduction_pct برانڈ اسے ٹیبل کے طور پر ظاہر کرنے کے لیے، پینل کو ٹیبل ویو میں تبدیل کریں اور تین گرافانا تبدیلیاں شامل کریں۔
-
لیبل آبجیکٹ سے فیلڈز نکالیں۔
-
وقت، pre_tokens، post_tokens، reduce_pct اور span_id رکھنے کے لیے فیلڈز کو نام سے فلٹر کریں۔
-
فیلڈ کی اقسام کو pre_tokens، post_tokens، اور reduce_pct کو عددی میں تبدیل کریں۔
ٹریسنگ
نشانات اس پورے راستے کی تفصیلی تصویر فراہم کرتے ہیں جو درخواست آپ کی درخواست کے ذریعے لی جاتی ہے، شروع سے تکمیل تک۔ ٹریکنگ کے بارے میں کچھ بنیادی تصورات یہ ہیں:
-
مدت: ایک وقتی آپریشن جو کام کی اکائی کی نمائندگی کرتا ہے۔ یہ ٹریکنگ کے لیے بلڈنگ بلاکس ہیں۔ تمام ٹریس ڈیٹا کو اسکوپس کی ایک سیریز کے طور پر ریکارڈ کیا جاتا ہے، ہر اسکوپ کی ایک قسم اور متعلقہ آپریشن کا نام ہوتا ہے۔
-
claude_code.interaction: ایک پرامپٹ اور کلاڈ کوڈ اس کا جواب دینے کے لیے سب کچھ کرتا ہے۔ یہ عام طور پر جڑ کا دائرہ کار ہے، لہذا ایک تعامل مؤثر طریقے سے ایک ٹریس ہے۔ -
claude_code.llm_request: تعامل کے اندر ایک واحد ماڈل کال۔ -
claude_code.tool: ایک تعامل کے اندر ایک ٹول کال (Bash,Write,Agentوغیرہ)۔
-
-
ٹریک: ایک دائرہ کار درخت جو شروع سے تکمیل تک درخواست کے راستے کی نمائندگی کرتا ہے۔
-
سیشن: ایک کلاڈ کوڈ پر عمل کریں جس کی نشاندہی کی گئی ہے۔
session.id. اس کے نتیجے میں بہت زیادہ تعامل اور ٹریکنگ ہو سکتی ہے۔ -
ذیلی ایجنٹ: نیسٹڈ کلاڈ کوڈ کی مثالیں شروع ہوئیں بذریعہ:
Agentایک ٹول جو اپنے تعاملات کو خود انجام دیتا ہے۔
Jaeger یہاں استعمال ہونے والا ٹریکنگ بیک اینڈ ہے۔ کلکٹر OTLP کے ذریعے کلکٹر کو دائرہ کار سے آگاہ کرتا ہے۔ جیگر ان کو ذخیرہ کر سکتا ہے اور سروس اور اسپین ٹیگز کے ذریعے نشانات حاصل کر سکتا ہے، ہر ایک کو اسپین ٹری کے طور پر جانچ کر۔ نیچے کی ہر چیز UI کا استعمال کرتی ہے۔ localhost:16686.
ٹریس بنائیں
ٹریکنگ ڈیٹا بنانے کے لیے، یہ گائیڈ ایک ایجنٹ بنانے اور کچھ متن تیار کرنے کے لیے ٹیسٹ پرامپٹ کا استعمال کرتا ہے۔ اس پرامپٹ کو سونیٹ 5 کا استعمال کرتے ہوئے اعتدال پسند کوشش کے ساتھ تجربہ کیا گیا۔
آپ پرامپٹ کو براہ راست کلاڈ کوڈ میں چسپاں کر سکتے ہیں۔
Spawn 4 subagents in parallel, one per topic below. Each subagent researches its topic from your own knowledge and returns a ~150-word summary with 3 key points. Do not have them read files or run commands.
Topics:
1. How TCP congestion control works
2. The CAP theorem
3. How DNS resolution works
4. What a Bloom filter is
Once all 4 return, combine the summaries into one markdown document and write it to summary.md
میمو: پرامپٹ مکمل ہونے کے بعد، اسی سیشن کے سیشن_آئی ڈی کے لیے کلاڈ کوڈ سے پوچھیں۔ یہ Jaeger متعلقہ نشانات تلاش کرنے کے لیے استعمال کرتا ہے۔
سیشن ID کے ذریعہ ٹریک کریں۔
فلٹر تلاش کریں: service = claude-code اور ٹیگ session.id=. یہ 6 نشانات واپس کرتا ہے، تمام جڑ۔ claude_code.interactionرینج 1 سے 20 ہے اور دورانیہ تقریباً 1 سے 33 سیکنڈ ہے۔
اکیلے فہرست آپ کو یہ نہیں بتاتی ہے کہ کس ٹریس نے کیا کیا۔ اگر آپ اسے خود دیکھتے ہیں، یا حقیقی سیشن کے لیے ٹریکنگ API کے خلاف اسکرپٹ کرتے ہیں، تو آپ کو ملتا ہے:
| # | ٹریکنگ کا نام | مدت | جاری رکھیں | llm_calls | سامان |
|---|---|---|---|---|---|
| 1 | include_code.interaction | 1 | 1.4 سیکنڈ | 0 | - |
| 2 | include_code.interaction | 3 | 4.6 سیکنڈ | 2 | - |
| 3 | include_code.interaction | 1 | 5.4 سیکنڈ | 0 | - |
| 4 | include_code.interaction | 1 | 2.5 سیکنڈ | 0 | - |
| 5 | include_code.interaction | 20 | 15.7 سیکنڈ | 7 | ایجنٹ (x4) |
| 6 | include_code.interaction | 15 | 32.5 سیکنڈ | 5 | جاگنے کا شیڈول (x2)، لکھیں (x1) |
چند مشاہدات:
-
آدھا ٹریس شور ہے۔ ٹریسز 1، 3، اور 4 سنگل اسکوپ کے تعاملات ہیں جن میں کوئی ماڈل کال یا ٹولز نہیں ہیں، اور بیکار سیشنز کو پنگ کیا جاتا ہے۔ ٹریس 2 ایک سادہ تبادلہ ہے۔ صرف نشانات 5 اور 6 چلائے جاتے ہیں۔
-
متوازی ترسیل ایک واحد تعامل ہے۔ ٹریس 5 رنز چاروں۔
Agentاندر سے کالclaude_code.interaction. نیسٹڈ ماڈل کالز (ہر ایک 7 سے 10 سیکنڈ) کے اوورلیپ کی وجہ سے، تعامل تقریباً 16 سیکنڈ میں مکمل ہو جاتا ہے، اس کے باوجود کہ مشترکہ ذیلی ایجنٹ ایل ایل ایم کا وقت تقریباً 35 سیکنڈ ہے۔ -
ہر ذیلی ایجنٹ کی ماڈل کالز اس ذیلی ایجنٹ کے نیچے واقع ہوتی ہیں۔
Agentاسپین اور لےagent_idان چاروں کو پہچانا جا سکتا ہے۔ -
agent_idیہ غیر واضح ہے۔ موجود نہیں ہےagent.nameیاskill.name. ٹریس ہمیں بتاتا ہے کہ چار ذیلی ایجنٹ کب بھاگے اور ہر ایجنٹ پر کتنا وقت صرف ہوا، بجائے اس کے کہ ہر ذیلی ایجنٹ نے کن موضوعات پر کام کیا۔ -
Span ٹوکن کی تعداد رکھتا ہے، لیکن کوئی USD لاگت نہیں ہے۔ ہر ایک
claude_code.llm_requestہےinput_tokens,output_tokens,cache_read_tokensاورcache_creation_tokensتاہم، کوئی USD کے اعداد و شمار نہیں ہیں۔ -
تحریر ایک الگ، بعد میں بات چیت ہے۔ ٹریس 6 ہے۔
Agentحد: ایکclaude_code.llm_requestتقریباً 23 سیکنڈ کا وقت ایک مشترکہ قیمت میں کمی پیدا کرتا ہے، اس کے بعد ایک مختصرWrite. دوScheduleWakeupاسپین ایک پس منظر کی ایڈجسٹمنٹ ہے۔
ٹپ: ٹریس میں، ہمیں ہر ایک میں 4 سبجینٹ کالز موصول ہوتی ہیں۔ agent_idٹوکن کی گنتی اور وقت ہے، لیکن یہ بتانے کی کوئی گنجائش نہیں کہ ذیلی ایجنٹ نے کس موضوع پر بات کی۔ اس کے برعکس، میٹرکس درج ذیل خصوصیات فراہم کر سکتے ہیں: model, effortاور ہنر۔
احتیاط: user_prompt پہلے سے طے شدہ طور پر، اس میں تعامل کے دائرہ کار میں ترمیم کی جاتی ہے۔ OTEL_LOG_USER_PROMPTS=1 اسے غیر فعال کرتا ہے اور خام پرامپٹ متن کو لاگ کرتا ہے۔ اسے ملٹی یوزر/کرایہ دار کے ماحول میں فعال نہ کریں کیونکہ یہ ٹیلی میٹری بیک اینڈ تک رسائی رکھنے والے کسی کے سامنے فوری مواد کو ظاہر کرتا ہے۔
نتیجہ
یہ گائیڈ کلاڈ کوڈ میں مشاہداتی صلاحیت کا ایک اختتام سے آخر تک واک تھرو ہے، ٹیلی میٹری کو فعال کرتا ہے اور تجزیہ کے لیے مقامی بیک اینڈ سے تینوں سگنلز میں سے ہر ایک کو جمع کرتا ہے۔
میٹرکس آپ کو ایک منتخب مدت کے دوران پراپرٹی کے لحاظ سے مجموعی لاگت اور استعمال کے اقدامات کا تجزیہ کرنے کی اجازت دیتا ہے۔ یہ مشترکہ یا کثیر کرایہ دار سیٹ اپ میں سب سے اہم ہے جہاں اخراجات کسی ایک مالک تک محدود نہیں ہوتے ہیں اور ان کے لیے کسی کو ذمہ دار ہونا چاہیے۔
لاگز انفرادی واقعات کا ریکارڈ ہوتے ہیں اور یہ کھودنے کے لیے مفید ہوتے ہیں کہ ایونٹ کے دوران کیا بدلا ہے، جیسے کمپریشن۔
ٹریس سے پتہ چلتا ہے کہ کس طرح ایک پرامپٹ اپنے متعلقہ ٹائمنگ اور ٹوکنز کی تعداد کا استعمال کرتے ہوئے ذیلی ایجنٹ اور ماڈل کالز میں پھیلتا ہے۔ یہ پیچیدہ یا ملٹی ایجنٹ پرامپٹس کو ڈیبگ کرنے یا سخت کرنے کا نقطہ آغاز ہے۔ تاہم، دائرہ کار ابھی تک اس پرامپٹ یا تکنیک کو ریکارڈ نہیں کرتا ہے جس کی وجہ سے مخصوص کال ہوئی۔
اس میں سے کچھ ٹیلی میٹری Enhanced Telemetry Beta کے پیچھے ہے، اس لیے دائرہ کار کے نام اور خواص بدلتے رہ سکتے ہیں، اور کال کے لیے مخصوص خصوصیات جیسے فرق بالغ ہوتے ہی بند ہو سکتے ہیں۔ ایک بار جب سطح مستحکم ہو جاتی ہے، تو یہ نگرانی کے دستاویزات کو دوبارہ چیک کرنے کے قابل ہو سکتا ہے۔