استفاده از ابزار «ردیابی»

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید.
اطلاعات

ابزار Trace چیست؟

Trace ابزاری برای عیب‌یابی و پایش پراکسی‌های API است که در Apigee Edge اجرا می‌شوند. Trace به شما امکان می‌دهد جزئیات هر مرحله را ازطریق جریان پراکسی API بررسی کنید.

برای آشنایی با ابزار Trace، این ویدیو را تماشا کنید.

نحوه استفاده از Trace

استفاده از Trace آسان است. جلسه ردیابی را شروع می‌کنید، سپس فراخوانی میانای برنامه‌سازی کاربردی به پلاتفرم Edge انجام می‌دهید، و نتایج را می‌خوانید.

  1. به صفحه پراکسی‌های میانای برنامه‌سازی کاربردی دسترسی پیدا کنید، همان‌طور که در زیر توضیح داده شده است.

    Edge

    برای دسترسی به صفحه پراکسی‌های API بااستفاده از میانای کاربر Edge:

    1. به سیستم apigee.com/edge وارد شوید.
    2. توسعه > پراکسی‌های API را در نوار پیمایش سمت راست انتخاب کنید.

    میانای کاربر Edge جدید (ابر خصوصی)

    برای دسترسی به صفحه پراکسی‌های میانای برنامه‌سازی کاربردی بااستفاده از میانای کاربر New Edge:

    1. به سیستم New Edge UI در http://host:3001/edge وارد شوید، که در آن host نشانی IP یا نام ساناد میزبان اجراکننده New Edge UI است.
    2. توسعه > پراکسی‌های API را در نوار پیمایش سمت راست انتخاب کنید.
  2. یک پراکسی میانای برنامه‌سازی کاربردی را از صفحه «پراکسی‌های میانای برنامه‌سازی کاربردی» انتخاب کنید.
  3. مطمئن شوید میانای برنامه‌سازی کاربردی‌ای که می‌خواهید ردیابی کنید مستقر شده باشد.
  4. روی ردگیری کلیک کنید تا به نمای ابزار «ردگیری» بروید.
  5. از منوِ کرکره‌ای استقرار برای ردیابی برای انتخاب محیط استقرار و نسخه پراکسی موردنظر برای ردیابی استفاده کنید.
  6. روی شروع جلسه ردیابی کلیک کنید. وقتی جلسه Trace فعال است، پراکسی API جزئیات هر مرحله را در خط لوله پردازش ضبط می‌کند. وقتی جلسه «ردگیری» درحال اجرا است، پیام‌ها و داده‌های زمینه‌ای از ترافیک زنده ضبط می‌شود.

  7. اگر ترافیک زنده‌ای ازطریق پراکسی شما جریان ندارد، کافی است درخواستی به API ارسال کنید. می‌توانید از هر ابزاری که مایلید برای ارسال درخواست استفاده کنید، مانند curl،‏ Postman، یا هر ابزار آشنای دیگری. یا می‌توانید درخواست را مستقیماً از خود ابزار Trace ارسال کنید. کافی است نشانی وب را وارد کنید و روی ارسال کلیک کنید. توجه: فقط می‌توانید درخواست GET را از ابزار Trace ارسال کنید، اما درخواست POST را نمی‌توانید ارسال کنید.

    توجه: یک جلسه Trace می‌تواند ۱۰ تراکنش درخواست/پاسخ را برای هر پردازشگر پیام ازطریق پراکسی API انتخاب‌شده پشتیبانی کند. در Edge cloud، با ۲ پردازشگر پیام که ترافیک را مدیریت می‌کنند، ۲۰ تراکنش درخواست/پاسخ پشتیبانی می‌شود. اگر جلسه ردیابی را به‌طور دستی متوقف نکنید، پس‌از ۱۰ دقیقه به‌طور خودکار متوقف می‌شود.
  8. وقتی تعداد کافی درخواست ضبط کردید، روی توقف جلسه ردیابی کلیک کنید.
  9. فهرستی از تراکنش‌های درخواست/پاسخ ضبط‌شده در منوِ سمت راست نمایش داده می‌شود. برای مشاهده نتایج دقیق، روی هریک از تراکنش‌ها کلیک کنید.

نحوه خواندن ردگیری

ابزار ردیابی دو بخش اصلی دارد: نقشه تراکنش و جزئیات فاز:

  • نقشه تراکنش از نمادها برای علامت‌گذاری هر مرحله قابل‌توجهی که درطول تراکنش پراکسی میانای برنامه‌سازی کاربردی رخ می‌دهد استفاده می‌کند، ازجمله اجرای خط‌مشی، مراحل شرطی، و انتقال‌ها. نشانگر را روی هر نمادی نگه دارید تا اطلاعات خلاصه را ببینید. مراحل جریان درخواست در بالای نقشه تراکنش و مراحل جریان پاسخ در پایین آن نشان داده می‌شود.
  • بخش جزئیات فاز ابزار، اطلاعات مربوط به پردازش داخلی پراکسی را فهرست می‌کند، ازجمله متغیرهایی که تنظیم یا خوانده شده‌اند، سرایندهای درخواست و پاسخ، و موارد دیگر. روی هر نمادی کلیک کنید تا جزئیات فاز آن مرحله را ببینید.

در اینجا نمونه‌ای از نقشه ابزار ردیابی با برچسب‌گذاری بخش‌های اصلی پردازش پراکسی آورده شده است:

نقشه تراکنش ابزار Trace

راهنمای نقشه تراکنش

جدول زیر هدف نمادهایی را که در نقشه تراکنش خواهید دید شرح می‌دهد. این نمادها هریک از مراحل پردازش قابل‌توجه را در سراسر جریان پراکسی علامت‌گذاری می‌کنند.

نمادهای نقشه تراکنش

برنامه کارخواهی که درخواستی را به ProxyEndpoint پراکسی API ارسال می‌کند.
دایره‌ها نقاط پایانی انتقالی را در جریان پراکسی نشان می‌دهند. این خط‌مشی‌ها زمانی وجود دارند که درخواستی از مشتری دریافت می‌شود، زمانی که درخواست به هدف ارسال می‌شود، زمانی که پاسخ از هدف بازمی‌گردد، و زمانی که پاسخ به مشتری بازمی‌گردد.

میله‌های بلند نشان‌دهنده شروع بخش جریان در جریان پراکسی میانای برنامه‌سازی کاربردی است. بخش‌های جریان عبارت‌اند از: درخواست ProxyEndpoint، درخواست TargetEndpoint، پاسخ TargetEndpoint، و پاسخ ProxyEndpoint. یک بخش شامل PreFlow،‏ Conditional Flows، و PostFlow است.

برای اطلاعات بیشتر، به پیکربندی جریان‌ها مراجعه کنید.

نشان می‌دهد که کنش‌های Analytics در پس‌زمینه رخ داده است.

جریان شرطی که نتیجه ارزیابی آن درست است. برای آشنایی با جریان‌های شرطی، پیکربندی جریان‌ها را ببینید.

توجه داشته باشید که برخی‌از شرایط توسط Edge تولید شده‌اند. برای مثال، عبارت زیر عبارتی است که Edge برای بررسی اینکه آیا خطایی در ProxyEndpoint رخ داده است یا نه استفاده می‌کند:

((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))

جریان شرطی که نتیجه ارزیابی آن نادرست است. برای آشنایی با جریان‌های شرطی، پیکربندی جریان‌ها را ببینید.

توجه داشته باشید که برخی‌از شرایط توسط Edge تولید شده‌اند. برای مثال، عبارت زیر عبارتی است که Edge برای بررسی اینکه آیا خطایی در TargetEndpoint رخ داده است یا نه استفاده می‌کند:

(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))

خط‌مشی‌ها. هر نوع خط‌مشی نماد یکتایی دارد. این مورد برای خط‌مشی AssignMessage است. این نمادها به شما امکان می‌دهند ببینید خط‌مشی‌ها کجا به‌ترتیب مناسب اجرا می‌شوند و آیا موفقیت‌آمیز هستند یا نه. می‌توانید روی نماد خط‌مشی کلیک کنید تا نتایج اجرای آن را ببینید و متوجه شوید که آیا نتایج مطابق انتظار هستند یا نه. برای مثال، می‌توانید ببینید که آیا پیام به‌درستی تبدیل شده است یا در حافظه پنهان ذخیره می‌شود.

خط‌مشی‌های به‌درستی اجراشده با علامت‌های تیک به‌وضوح نشان داده شده‌اند. درصورت بروز خطا، علامت تعجب قرمز روی نماد نمایش داده می‌شود.

نکته: به نکته‌ابزار یا خط زمان توجه کنید تا ببینید آیا خط‌مشی‌ای بیشتر از حد انتظار طول می‌کشد یا نه.

وقتی هدف پس‌زمینه برنامه Node.js باشد، ظاهر می‌شود. نمای کلی Node.js در Apigee Edge را ببینید.
هدف زیرینه که توسط پراکسی میانای برنامه‌سازی کاربردی فراخوانی شده است.
خط زمان نشان می‌دهد که زمان پردازش چقدر (به میلی‌ثانیه) طول کشیده است تا تکمیل شود. مقایسه بخش‌های زمان سپری‌شده به شما کمک می‌کند خط‌مشی‌هایی را که اجرای آن‌ها بیشترین زمان را می‌برد و باعث کند شدن تماس‌های میانای برنامه‌سازی کاربردی شما می‌شود جدا کنید.
اپسیلون نشان‌دهنده بازه زمانی کوچک‌تر از یک میلی‌ثانیه است.

غیرفعال. وقتی خط‌مشی‌ای غیرفعال باشد، روی نماد خط‌مشی نشان داده می‌شود. خط‌مشی را می‌توان با میانای برنامه‌سازی کاربردی عمومی غیرفعال کرد. مرجع پیکربندی پراکسی میانای برنامه‌سازی کاربردی را ببینید.

خطا. وقتی شرط «مرحله خط‌مشی» نادرست ارزیابی شود، روی نماد خط‌مشی نشان داده می‌شود (به متغیرها و شرایط جریان مراجعه کنید)، یا هرگاه خط‌مشی RaiseFault اجرا شود، روی نماد خط‌مشی RaiseFault نشان داده می‌شود.
رد شد. وقتی خط‌مشی اجرا نشده باشد، روی نماد خط‌مشی نشان داده می‌شود چون شرط مرحله نادرست ارزیابی شده است. برای اطلاعات بیشتر، متغیرها و شرایط جریان را ببینید.

درک کردن جزئیات فاز

بخش جزئیات فاز ابزار اطلاعات زیادی درباره وضعیت پراکسی شما در هر مرحله پردازش ارائه می‌دهد. در اینجا برخی‌از جزئیات ارائه‌شده در «جزئیات فاز» آمده است. روی هر نمادی در ابزار ردیابی کلیک کنید تا جزئیات مرحله انتخاب‌شده را ببینید، یا از دکمه‌های بعدی/قبلی برای رفتن از یک مرحله به مرحله دیگر استفاده کنید.

جزئیات فاز شرح
نقطه پایان پراکسی نشان می‌دهد کدام جریان ProxyEndpoint برای اجرا انتخاب شده است. یک پراکسی API می‌تواند چندین نقطه پایانی پراکسی نام‌گذاری‌شده داشته باشد.
متغیر

متغیرهای جریان را که توسط خط‌مشی خوانده شده و مقداری به آن‌ها اختصاص داده شده است فهرست می‌کند، همچنین به مدیریت وضعیت پراکسی با متغیرهای جریان مراجعه کنید.

توجه:

  • علامت مساوی (=) نشان‌دهنده مقداری است که به متغیر اختصاص داده شده است.
  • علامت مساوی خط‌خورده (≠) نشان می‌دهد که نمی‌توان به متغیر مقدار اختصاص داد زیرا فقط خواندنی است یا خطایی در اجرای خط‌مشی وجود دارد.
  • فیلد خالی نشان می‌دهد که مقدار متغیر خوانده شده است.
سرایندهای درخواست سرصفحه‌های درخواست اچ‌تی‌تی‌پی را فهرست می‌کند.
درخواست محتوا بدنه درخواست HTTP را نشان می‌دهد.
مشخصات ویژگی‌ها نشان‌دهنده وضعیت داخلی پراکسی API هستند. این موارد به‌طور پیش‌فرض نشان داده نمی‌شوند.
نقطه پایان هدف نشان می‌دهد کدام TargetEndpoint برای اجرا انتخاب شده است.
سرصفحه‌های پاسخ سرصفحه‌های پاسخ HTTP را فهرست می‌کند.
محتوای پاسخ بدنه پاسخ‌های HTTP را نشان می‌دهد.
PostClientFlow اطلاعاتی درباره PostClientFlow نشان می‌دهد که پس‌از برگرداندن درخواست به برنامه کارخواه درخواست‌کننده اجرا می‌شود. فقط خط‌مشی‌های MessageLogging را می‌توان به PostClientFlow پیوست کرد. ‫PostClientFlow درحال‌حاضر عمدتاً برای اندازه‌گیری فاصله زمانی بین مُهرهای زمان شروع و پایان پیام پاسخ استفاده می‌شود.

پالایش کردن ضبط پیام بااستفاده از فیلترها

با مشخص کردن مقادیر پارامتر پُرسمان و/یا سرصفحه، می‌توانید درخواست‌هایی را که در ابزار «ردیابی» نشان داده می‌شود فیلتر کنید. فیلترها به شما امکان می‌دهند تماس‌های خاصی را که ممکن است باعث مشکل شوند هدف قرار دهید. برای مثال، ممکن است لازم باشد روی درخواست‌هایی که محتوای خاصی دارند یا درخواست‌هایی که از شرکا یا برنامه‌های خاصی می‌آیند تمرکز کنید. می‌توانید براساس موارد زیر فیلتر کنید:

  • سرایندهای HTTP - ردیابی را فقط به تماس‌هایی محدود کنید که حاوی سرایند خاصی هستند. این روش خوبی برای کمک به شما در عیب‌یابی مشکلات است. می‌توانید سرصفحه‌ای به توسعه‌دهنده برنامه‌تان ارسال کنید و از او بخواهید آن را در تماسی که باعث مشکل شده است قرار دهد. سپس Apigee Edge فقط تماس‌های دارای آن سرصفحه خاص را ضبط می‌کند تا بتوانید نتایج را بررسی کنید.
  • پارامترهای پُرسمان - فقط تماس‌هایی که مقدار خاصی از پارامتر را دارند ضبط خواهند شد.

نکاتی که باید درباره ویژگی «فیلتر» بدانید

  • پس‌از مشخص کردن پارامترهای فیلتر در فیلدهای فیلتر، باید جلسه Trace را بازراه‌اندازی کنید.
  • پارامترهای فیلتر باهم ترکیب شده‌اند. همه جفت‌های نام/مقدار سرصفحه و/یا پُرسمان مشخص‌شده باید در درخواست وجود داشته باشند تا مطابقت موفقیت‌آمیز باشد.
  • تطبیق الگو در ابزار «فیلترها» پشتیبانی نمی‌شود.
  • پارامترها و مقادیر فیلتر حروف‌حساس هستند.

نحوه ایجاد فیلتر ردیابی

  1. اگر جلسه ردیابی درحال اجرا است، با کلیک کردن روی توقف جلسه ردیابی آن را متوقف کنید.
  2. روی فیلترها در گوشه بالا سمت راست ابزار «ردگیری» کلیک کنید تا فیلد «فیلترها» ازهم باز شود.

    در ابزار Trace، برچسب نوار کناری «فیلترها» با دایره مشخص شده است.
  3. در فیلد «فیلترها»، پارامتر پُرسمان و/یا مقادیر سرصفحه را که می‌خواهید فیلتر کنید مشخص کنید. در این مثال، دو پارامتر پُرسمان را برای فیلتر کردن مشخص می‌کنیم. برای مطابقت موفق، هر دو پارامتر باید در درخواست وجود داشته باشند.

    در ابزار Trace، در بخش «فیلترها»، در بخش «پارامتر پُرسمان»، دو نام و مقدار نمونه
     تنظیم شده است.
  4. جلسه ردیابی را شروع کنید.
  5. میاناهای برنامه‌سازی کاربردی‌تان را فراخوانی کنید. فقط درخواست‌هایی که شامل همه سرصفحه(ها) و/یا پارامتر(های) پُرسمان مشخص‌شده باشند تطابق موفقیت‌آمیز ایجاد می‌کنند.

در بخش «تراکنش‌ها»، چهار نتیجه نشان داده می‌شود که با دو پارامتر پُرسمان ازپیش‌تنظیم‌شده مطابقت دارد.

در مثال بالا، این فراخوانی میانای برنامه‌سازی کاربردی در Trace نشان داده خواهد شد:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

اما این کار باعث موارد زیر نخواهد شد:

http://docs-test.apigee.net/cats?name=Penny

اشکال‌زدایی با Trace

Trace به شما امکان می‌دهد جزئیات داخلی زیادی را درباره پراکسی میانای برنامه‌سازی کاربردی ببینید. برای مثال:

  • می‌توانید در یک نگاه ببینید کدام خط‌مشی‌ها به‌درستی اجرا می‌شوند یا ناموفق هستند.
  • فرض کنید ازطریق یکی از داشبوردهای Analytics متوجه شده‌اید که یکی از میاناهای برنامه‌سازی کاربردی شما کاهش غیرمعمولی در عملکرد دارد. اکنون می‌توانید از Trace برای کمک به شناسایی محل وقوع گلوگاه استفاده کنید. ردیابی زمان لازم برای تکمیل هر مرحله پردازش را برحسب میلی‌ثانیه ارائه می‌دهد. اگر متوجه شدید که یکی از مراحل بیش‌ازحد طول می‌کشد، می‌توانید اقدام اصلاحی انجام دهید.
  • با نگاه کردن به جزئیات فاز، می‌توانید سرصفحه‌هایی را که به پس‌بک ارسال می‌شوند بررسی کنید، متغیرهای تنظیم‌شده توسط خط‌مشی‌ها را مشاهده کنید، و غیره.
  • با درستی‌سنجی کردن مسیر پایه، می‌توانید مطمئن شوید که خط‌مشی پیام را به سرور صحیح هدایت می‌کند.

انتخاب گزینه‌های نما

گزینه‌های مشاهده را برای جلسه ردیابی انتخاب کنید.

گزینه شرح
نمایش خط‌مشی‌های غیرفعال‌شده هرگونه خط‌مشی غیرفعال را نشان دهید. خط‌مشی را می‌توان با میانای برنامه‌سازی کاربردی عمومی غیرفعال کرد. به مرجع پیکربندی پراکسی میانای برنامه‌سازی کاربردی مراجعه کنید.
نمایش فازهای ردشده هر مرحله‌ای را که رد شده است نشان دهید. مرحله ردشده زمانی رخ می‌دهد که خط‌مشی اجرا نشده باشد زیرا شرط مرحله نادرست ارزیابی شده است. برای اطلاعات بیشتر، متغیرها و شرایط جریان را ببینید.
نمایش همه FlowInfos انتقال‌ها را در بخش جریان نشان می‌دهد.
مقایسه خودکار فاز انتخاب‌شده فاز انتخاب‌شده را با فاز قبلی مقایسه می‌کند. این گزینه را خاموش کنید تا فقط فاز انتخاب‌شده را ببینید.
نمایش متغیرها متغیرهایی را که خوانده شده‌اند و/یا مقداری به آن‌ها اختصاص داده شده است نشان دهید یا پنهان کنید.
نمایش دارایی‌ها ویژگی‌ها نشان‌دهنده وضعیت داخلی پراکسی API هستند. (به‌طور پیش‌فرض پنهان است.)

درحال بارگیری نتایج ردگیری

می‌توانید فایل XML نتایج ردیابی خام را برای مشاهده و جستجو به‌صورت آفلاین در ویرایشگر نوشتار بارگیری کنید. این فایل جزئیات کامل جلسه شنود را نشان می‌دهد، ازجمله محتوای همه سرصفحه‌ها، متغیرها، و خط‌مشی‌ها.

برای بارگیری، روی بارگیری جلسه ردگیری کلیک کنید.

نمایش درخواست‌ها به‌صورت curl

پس‌از ردیابی فراخوانی API انجام‌شده به سرور هدف، می‌توانید درخواست را به‌صورت فرمان curl مشاهده کنید. این به‌ویژه برای اشکال‌زدایی به چند دلیل مفید است:

  • پراکسی میانای برنامه‌سازی کاربردی ممکن است درخواست را اصلاح کند، بنابراین مفید است که ببینید درخواست از پراکسی به سرور هدف چه تفاوتی با درخواست اصلی دارد. فرمان curl نشان‌دهنده درخواست اصلاح‌شده است.
  • برای محموله‌های پیام بزرگ‌تر، curl به شما امکان می‌دهد سرایندهای HTTP و محتوای پیام را در یک مکان ببینید. (درحال‌حاضر حد نویسه حدود ۱۰۰۰ نویسه است. برای نکته‌ای درباره عبور از این محدودیت، این پست انجمن را ببینید.)

برای امنیت، ویژگی curl سرصفحه «مجوز HTTP» را پنهان می‌کند.

برای دیدن درخواست‌ها به‌صورت curl پس‌از اینکه فراخوانی میانای برنامه‌سازی کاربردی در Trace انجام شد، مرحله «درخواست ارسال‌شده به سرور هدف» را در نمودار «نقشه تراکنش» انتخاب کنید، سپس روی دکمه نمایش curl در ستون «درخواست ارسال‌شده به سرور هدف» در قاب «جزئیات فاز» کلیک کنید.

حاشیه‌نویسی‌های تصویر دکمه «نمایش Curl» و یکی از دایره‌ها را در نمودار «نقشه تراکنش» نشان می‌دهد.

استفاده «پشتیبانی Apigee» از Trace

به طور پیش فرض، Apigee Edge به پشتیبانی Apigee اجازه می دهد تا از ابزار Trace در پراکسی های API شما برای ارائه پشتیبانی استفاده کند. شما می توانید این گزینه را در هر زمان غیرفعال کنید. با این حال، غیرفعال کردن این گزینه ممکن است توانایی Apigee Support را برای ارائه پشتیبانی به شما محدود کند.

برای غیرفعال کردن پشتیبانی Apigee از استفاده از ابزار Trace:

  1. به https://apigee.com/edge وارد شوید.
  2. Admin > Privacy & Security را در نوار ناوبری سمت چپ انتخاب کنید.
  3. برای غیرفعال کردن استفاده از ابزار Trace توسط پشتیبانی Apigee، روی دکمه فعال کردن پشتیبانی برای ردیابی Apigee کلیک کنید.