الگوی بد: فراخوانی خط‌مشی MessageLogging چند بار در یک پراکسی API

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

خط‌مشی MessageLogging در Apigee Edge به توسعه‌دهندگان «پراکسی API» اجازه می‌دهد پیام‌های سفارشی را در syslog یا در دیسک (فقط Edge for Private Cloud) ثبت کنند. هرگونه اطلاعات مهم مربوط به درخواست API مانند پارامترهای ورودی، بار درخواست، کد پاسخ، پیام‌های خطا (درصورت وجود)، و غیره، می‌تواند برای ارجاع بعدی یا اشکال‌زدایی ثبت شود. اگرچه خط‌مشی از فرایند پس‌زمینه‌ای برای انجام گزارش استفاده می‌کند، اما استفاده از این خط‌مشی ملاحظاتی دارد.

الگوی بد

خط‌مشی MessageLogging روشی کارآمد برای دریافت اطلاعات بیشتر درباره درخواست میانای برنامه‌سازی کاربردی و اشکال‌زدایی کردن مشکلات مربوط به درخواست میانای برنامه‌سازی کاربردی ارائه می‌دهد. بااین‌حال، استفاده از خط‌مشی MessageLogging یکسان بیش‌از یک بار یا داشتن چندین خط‌مشی MessageLogging که داده‌ها را به‌صورت تکه‌ای در همان پراکسی API در جاری‌سازی‌های غیر از PostClientFlow ثبت می‌کنند، ممکن است پیامدهای نامطلوبی داشته باشد. دلیل این امر این است که Apigee Edge برای خط‌مشی MessageLogging، اتصالی به سرور syslog خارجی باز می‌کند. اگر خط‌مشی از «امنیت لایه انتقال» روی TCP استفاده کند، سربار اضافی برای ایجاد اتصال «امنیت لایه انتقال» وجود دارد.

بیایید این را با کمک یک پراکسی API نمونه توضیح دهیم.

پراکسی میانای برنامه‌سازی کاربردی

در مثال زیر، خط‌مشی MessageLogging به‌نام «LogRequestInfo» در جریان «درخواست» قرار می‌گیرد و خط‌مشی MessageLogging دیگری به‌نام «LogResponseInfo» به جریان «پاسخ» اضافه می‌شود. هر دو در ProxyEndpoint PreFlow هستند. خط‌مشی LogRequestInfo به‌محض اینکه کارگزار API درخواست را دریافت می‌کند در پس‌زمینه اجرا می‌شود، و خط‌مشی LogResponseInfo پس‌از اینکه کارگزار پاسخی از سرور هدف دریافت کرد اما پیش‌از اینکه کارگزار پاسخ را به مشتری API برگرداند اجرا می‌شود. این کار منابع سیستم اضافی را مصرف می‌کند زیرا احتمالاً دو اتصال «امنیت لایه انتقال» برقرار می‌شود.

علاوه‌براین، خط‌مشی MessageLogging به‌نام «LogErrorInfo» وجود دارد که فقط درصورتی اجرا می‌شود که درطول اجرای پراکسی API خطایی رخ دهد.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  ...
<FaultRules>
    <FaultRule name="fault-logging">
        <Step>
            <Name>LogErrorInfo</Name>
        </Step>
    </FaultRule>
</FaultRules>
<PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>LogRequestInfo</Name>
      </Step>
    </Request>
  </PreFlow>
  <PreFlow name="PreFlow">
    <Response>
      <Step>
        <Name>LogResponseInfo</Name>
      </Step>
    </Response>
  </PreFlow>
  ...
</ProxyEndpoint>

خط‌مشی «گزارش پیام»

در پیکربندی‌های خط‌مشی مثال زیر، داده‌ها بااستفاده از TLS ازطریق TCP در سرورهای گزارش شخص ثالث ثبت می‌شوند. اگر بیش‌از یک مورد از این خط‌مشی‌ها در یک پراکسی API استفاده شود، سربار ایجاد و مدیریت اتصالات TLS حافظه سیستم و چرخه‌های CPU بیشتری را اشغال می‌کند که در مقیاس بزرگ منجر به مشکلات عملکرد می‌شود.

خط‌مشی LogRequestInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogRequestInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

خط‌مشی LogResponseInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogResponseInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Status: {response.status.code}, Response {response.content}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

خط‌مشی LogErrorInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogErrorInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Fault name: {fault.name}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>ERROR</logLevel>
</MessageLogging>

تأثیر

  • سربار شبکه به‌دلیل ایجاد اتصال به سرورهای گزارش چندین بار درطول جریان «پراکسی میانای برنامه‌سازی کاربردی» افزایش یافته است.
  • اگر سرور syslog کُند باشد یا نتواند حجم بالای ناشی از چندین تماس syslog را مدیریت کند، باعث ایجاد فشار برگشتی روی پردازشگر پیام می‌شود که درنتیجه پردازش درخواست کُند می‌شود و احتمالاً تأخیر زیاد یا خطاهای «مهلت درگاه ۵۰۴» رخ می‌دهد.
  • افزایش تعداد توصیفگرهای فایل هم‌زمان بازشده توسط پردازشگر پیام در راه‌اندازی‌های «ابر خصوصی» که از ثبت گزارش فایل استفاده می‌کنند.
  • اگر خط‌مشی MessageLogging در جاری‌سازی‌هایی غیراز جاری‌سازی PostClient قرار داده شود، احتمال دارد اطلاعات ثبت نشود، زیرا اگر قبل‌از اجرای این خط‌مشی خطایی رخ دهد، خط‌مشی MessageLogging اجرا نخواهد شد.

    در مثال ProxyEndpoint قبلی، اطلاعات در شرایط زیر ثبت نخواهد شد:

    • اگر هریک از خط‌مشی‌هایی که قبل‌از خط‌مشی LogRequestInfo در جریان درخواست قرار دارند ناموفق باشد.
      یا
    • اگر سرور هدف با هر خطایی (HTTP 4XX،‏ 5XX) ناموفق باشد. در این وضعیت، وقتی پاسخ موفقیت‌آمیز برگردانده نمی‌شود، خط‌مشی LogResponseInfo اجرا نخواهد شد.

    در هر دو مورد، خط‌مشی LogErrorInfo اجرا خواهد شد و فقط اطلاعات مربوط به خطا را ثبت خواهد کرد.

روال مطلوب

  • از خط‌مشی ExtractVariables یا خط‌مشی JavaScript برای تنظیم همه متغیرهای جاری‌سازی که باید ثبت شوند استفاده کنید و آن‌ها را برای خط‌مشی MessageLogging دردسترس قرار دهید.
  • از یک خط‌مشی MessageLogging برای ثبت همه داده‌های موردنیاز در PostClientFlow استفاده کنید، که بدون قیدوشرط اجرا می‌شود.
  • از پروتکل UDP استفاده کنید، جایی که تحویل تضمینی پیام‌ها به سرور syslog الزامی نیست و TLS/SSL اجباری نیست.

خط‌مشی MessageLogging به‌گونه‌ای طراحی شده است که از عملکرد واقعی API، ازجمله مدیریت خطا، جدا باشد. بنابراین، فراخوانی آن در PostClientFlow، که خارج از پردازش درخواست/پاسخ است، به این معنی است که داده‌ها همیشه ثبت خواهند شد، صرف‌نظر از اینکه «میانای برنامه‌سازی کاربردی» ناموفق بوده است یا نه.

در اینجا نمونه‌ای از فراخوانی «خط‌مشی ثبت پیام» در PostClientFlow آورده شده است:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 ...
<PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>LogInfo</Name>
            </Step>
        </Response>
</PostClientFlow>
 ...

در اینجا نمونه‌ای از خط‌مشی MessageLogging،‏ LogInfo، آورده شده است که همه داده‌ها را ثبت می‌کند:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {woeid} Status: {weather.response.code}, Response {weather.response}, Fault: {fault.name:None}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

ازآنجایی‌که متغیرهای پاسخ در PostClientFlow پس‌از «جریان خطا» دردسترس نیستند، مهم است که متغیرهای woeid و weather.response* را بااستفاده از خط‌مشی‌های ExtractVariables یا JavaScript به‌طور صریح تنظیم کنید.

مطالعه بیشتر