پایا

این سند پاکت و قالب های مورد استفاده Sentry را برای مصرف داده ، حمل و نقل و ذخیره آفلاین تعریف می کند. مخاطبان هدف این سند توسعه دهندگان Sentry SDK و نگهدارنده خط لوله مصرف هستند.

سازگاری به عقب

پاکت نامه ها به رله نیاز دارند ، که در Sentry v20. 6. 0 معرفی شده است. نسخه های اولیه Sentry از پاکت نامه ها پشتیبانی نمی کنند و با خطای HTTP 404 که برای بارگذاری های پاکت یافت نمی شود ، پاسخ می دهند. به همین ترتیب ، رله برای پاکت نامه های بالادست به پشتیبانی نیاز دارد و با نسخه های قدیمی تر از Sentry قابل استفاده نیست.

پاکت نامه ها یک قالب داده شبیه به داده های فرم HTTP هستند که شامل هدرهای مشترک و مجموعه ای از موارد با هدرهای مخصوص خود و بارهای خاص خود هستند. پاکت نامه ها برای تجزیه سریع و خوانایی انسان بهینه شده است. آنها از ترکیبی از چندین مورد در یک بار واحد پشتیبانی می کنند ، مانند:

• رویدادها را با پیوست های باینری بزرگ ارسال کنید.
• ارتباط بین هاپ ، به عنوان مثال ، بین SDK های مختلف (بومی و موبایل ، واکنش دهنده و اندرویدی) و بین رله ها را فعال کنید.
• اجازه دهید دسته های خاصی را در یک ارسال واحد قرار دهید.
• ذخیره آفلاین برای ارسال معوق پس از مشکلات اتصال.

Sentry یک نقطه پایانی اختصاصی را برای مصرف پاکت ها مشخص می کند:

• مورد نیاز: در صورت وجود این قسمت ، اجرای ممکن است خطایی را منتشر کند.
• توصیه می شود: این زمینه باید هنگام نوشتن منتشر شود ، اما می تواند در حین خواندن از بین برود.
• اختیاری: می تواند در حین نوشتن آزادانه حذف شود و در حین خواندن می تواند از دست بدهد.

در این بخش فرمت داده پاکت و سریال سازی تعریف شده است. برای جزئیات بیشتر در مورد یکپارچگی داده ها و لیستی از انواع موارد معتبر به مدل داده بخش بعدی مراجعه کنید.

این تعاریف برای تمام قسمت های قالب داده پاکت اعمال می شود:

1. Newlines به عنوان Unix Newlines تعریف شده است ، که توسط کد n و ASCII 10 نشان داده شده است.
2. UUID ها به عنوان 32 رشته hexadecimal شخصیت بدون لکه ها اعلام می شوند ("12C2D058D58442709AA2ECA08BF20986") ، یا 36 رشته کاراکتر با dashes "."توصیه می شود در همه موارد از خطوط و استفاده از UUID V4 استفاده کنید.
3. پاکت ها مکانیسم فشرده سازی را ارائه نمی دهند. با این حال ، یک پاکت کامل ممکن است فشرده یا فشرده شده به روش تعریف شده توسط هر یک از پاکت های کنترل مؤلفه باشد. به عنوان مثال ، مصرف آن از طریق رمزگذاری محتوا ، فشرده سازی را امکان پذیر می کند.

پاکت نامه ها حاوی هدر در چندین مکان است. هدرها اشیاء رمزگذاری شده JSON (نقشه های ارزش کلیدی) هستند که از این قوانین پیروی می کنند:

• همیشه در UTF-8 رمزگذاری می شود
• باید JSON معتبر باشد
• باید در یک خط واحد اعلام شود. بدون خط جدید
• همیشه توسط یک خط جدید ( n) یا پایان پرونده دنبال می شود
• نباید توسط فضای سفید پیشرو یا دنباله دار شود
• باید در جمع و جور ترین شکل آنها بدون فضای سفید اضافی سریال شود. فضای سفید در هدرهای JSON مجاز است ، اگرچه دلسرد می شود.
• ویژگی های ناشناخته مجاز است و باید توسط همه پیاده سازی ها حفظ شود. با این حال ، ویژگی هایی که در این مشخصات پوشیده نشده است نباید به طور فعال توسط هیچ عملی منتشر شود.
• تمام عناوین شناخته شده و انواع داده های آنها می توانند با اجرای آن تأیید شوند. در صورت عدم موفقیت ، پاکت نامه ممکن است به عنوان ناقص رد شود.
• هدرهای خالی<>از نظر فنی معتبر هستند

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

• هدرها یک خط واحد هستند که حاوی یک شیء JSON است ، همانطور که در بخش هدر تعریف شده است. ویژگی های تعریف شده در هدر پاکت نامه محتوای پاکت نامه و می توان به عنوان استفاده از همه موارد تصور کرد.
• بر اساس محتویات پاکت ، ممکن است به ویژگی های خاص هدر نیاز باشد. برای مشخصات ویژگی های مورد نیاز به مدل داده مراجعه کنید.
• موارد شامل هدرهای مخصوص خود و بار خود هستند. در یک پاکت که توسط یک خط جدید از هم جدا شده است ، می توانید تعداد دلخواه از موارد وجود داشته باشد. یک اجرای باید موارد را تا پایان پرونده مصرف کند.
• پاکت نامه ها باید با یک خط دنباله دار خاتمه یابد. این خط جدید اختیاری است. پس از خط نهایی نهایی ، هیچ فضای سفیدی مجاز نیست.
• پاکت نامه ها ممکن است خالی باشد و بلافاصله پس از هدرها خاتمه یابد.
• پایان پرونده (EOF) در صورت پیش بینی داده های بیشتر ، مانند بار ، به طور ضمنی پاکت را خاتمه نمی دهد.

پاکت نامه ها می توانند تعدادی از هدرها داشته باشند که در همه شرایط معتبر هستند:

رشته DSN ، توصیه می شود. یک پاکت نامه می تواند خود تأیید شود. این بدان معنی است که پاکت تمام اطلاعات لازم برای ارسال به Sentry را دارد. در این حالت DSN کامل باید در این کلید ذخیره شود.

شیء SDK ، توصیه می شود. این می تواند همان بار را با رابط SDK در بار بارگذاری بار حمل کند اما برای همه رویدادها قابل حمل است. این بدان معنی است که اطلاعات SDK را می توان برای minidumps ، داده های جلسه و سایر ارسال ها حمل کرد.

Sent_at String ، توصیه می شود. Timestamp هنگامی که این رویداد از SDK به عنوان رشته در RFC 3339 ارسال شد

قالبمورد استفاده برای تصحیح ساعت ساعت از زمان بندی رویداد. منطقه زمانی باید UTC باشد.

راهنمایی اجرای هدر sent_at

توصیه می شود همیشه هدر پاکت نامه sent_at را ارسال کنید. سعی نکنید تعیین کنید که آیا باید ارسال شود یا نه ، زیرا این تعیین می تواند در سمت دریافت انجام شود.

Timestamp باید تا حد امکان به انتقال رویداد تولید شود ، به طوری که تأخیر بین ارسال پاکت و دریافت آن در سمت سرور به حداقل می رسد. این امر معمولاً در سریال سازی عنوان پاکت نامه انجام می شود.

با این حال ، باید مراقب باشید که هدر فقط یک بار اعمال شود. اگر بیش از یک هدر sent_at نوشته شود ، Sentry کل پاکت را رد می کند. به عنوان مثال ، SDK هایی که ویژگی های ذخیره سازی را پیاده سازی می کنند ، باید هنگام ذخیره کردن روی دیسک ، از نوشتن عنوان SENT_AT جلوگیری کنند. فقط هنگام ارسال این رویداد به Sentry ، آن را بنویسید.

Timestamp را می توان توسط هر یک از موارد زیر (به عنوان مثال) تولید کرد:

JavaScript Date New (). toisostring ()

از DateTime. utcnow () استفاده نکنید ، زیرا منطقه زمانی را حذف می کند.

. net dateTime. utcnow. ToString ("O" ، CultureInfo. InvarianTculture) یا DateTimeOffset. utcnow. ToString ("O" ، CultureInfo. InvarianTculture)

همچنین توجه داشته باشید که هدر Sent_at جایگزین کلید Sentry_Timestamp که قبلاً در هدرهای مجوز تنظیم شده بود ، که اکنون کاملاً مستهلک شده است. شما فقط باید sent_at را ارسال کنید ، و نه sentry_timestamp.

موارد داده های یک پاکت را تأمین می کنند. بدون موارد ، یک پاکت خالی در نظر گرفته می شود و با خیال راحت می توان آن را دور ریخت.

برای هر مورد دو هدر عمومی وجود دارد:

رشته را تایپ کنید ، لازم است. نوع این مورد و محتوای آن را مشخص می کند. بر اساس نوع مورد ، هدرهای بیشتری ممکن است مورد نیاز باشد. برای لیستی از انواع موارد ، به مدل داده مراجعه کنید.

طول int ، توصیه می شود. طول بار در بایت. اگر طولی مشخص نشده باشد ، بار به طور ضمنی به خط جدید بعدی می رود. برای بارهای حاوی کاراکترهای Newline ، طول باید مشخص شود.

در مورد حذف "طول"

اگر پاکت نامه حاوی تعداد زیادی از موارد بسیار کوچک باشد ، حذف طول می تواند برای فشرده سازی مفید باشد. این مورد برای جلسات است.

مجری باید این موضوع را به صورت متناوب ارزیابی کند و صریحاً در مورد تصمیم استدلال کند.

یادداشت ها برای مجریان:

• هدر پاکت لازم است ، اما می تواند خالی باشد.
• پیاده سازی ها باید با ظرافت از نوع ناشناخته به همراه بار خود ، پرش و حفظ کنند.
• ویژگی های ناشناخته باید به بالادست منتقل شوند.
• بارهای پیش فرض طول باید با n یا EOF خاتمه یابد. خط جدید بخشی از بار در نظر گرفته نمی شود. هر شخصیت دیگر ، از جمله فضای سفید ، به این معنی است که پاکت نامه ناقص است.
• اگر طول قابل مصرف نباشد ، یعنی پاکت قبل از مصرف تعداد بایت ها ، EOF است ، پس پاکت نامه ناقص است.
• اگر یک مورد با طول ضمنی توسط r n خاتمه یابد ، r یک شخصیت دلخواه در نظر گرفته می شود که جزئی از خط جدید نیست و بنابراین بخشی از بار است.

این مثالها حاوی بارهای کامل پاکت است. خطوط جدید به صراحت با n مشخص شده است ، شخصیت های غیرقابل توصیف با x فرار می شوند<><>بشرهمه شخصیت های دیگر تحت اللفظی هستند.

پاکت با 2 مورد:

توجه داشته باشید که ضمیمه حاوی یک خط جدید ویندوز در انتهای بار خود است که طول آن درج شده است: < pan> اگر طول قابل مصرف نباشد ، یعنی پاکت نامه EOF قبل از مصرف تعداد بایت ها است ، پس پاکت ناسازگار استبشر