next axiom

المحور التالي

Axiom يفتح الملاحظة على أي مقياس.

• الاستيعاب بسهولة ، تخزين بدون حدود: يتيح شريط بيانات الجيل التالي من Axiom تناول البطن من البيانات مع الكفاءة النهائية. سجلات السفن من Kubernetes و AWS و Azure و Google Cloud و Digitalocean و Nomad وغيرها.
• الاستعلام عن كل شيء ، طوال الوقت: سواء كان DevOps أو Secops أو EverythingOps ، استعل جميع بياناتك بغض النظر عن عمرها. لا يوجد توفير ، لا توجد بيانات متحركة من البرد/الأرشيف إلى "الساخنة" ، ولا تقلق بشأن الاستعلامات البطيئة. كل بياناتك ، كل شيء. ال. وقت.
• لوحات المعلومات القوية ، من أجل الملاحظة المستمرة: بناء لوحات معلومات لجمع الاستعلامات ذات الصلة وتقديم المعلومات التي تسهل هضمها لك ولعلك. يمكن أن تبقى لوحات المعلومات خاصة أو مشتركة مع الآخرين ، وهي الطريقة المثالية لجمع البيانات من مصادر مختلفة.

لمزيد من المعلومات ، تحقق من الوثائق الرسمية.

مقدمة

تتيح لك هذه المكتبة إرسال شبكة الإنترنت على الويب بالإضافة إلى سجلات منظمة من تطبيق Next.js إلى Axiom.

باستخدام جهاز توجيه الصفحات؟ استخدم الإصدار 0.* الذي يستمر في تلقي تصحيحات الأمان. ها هي readme لـ 0.x

المتطلبات الأساسية

• إنشاء حساب axiom.
• قم بإنشاء مجموعة بيانات في Axiom حيث ترسل بياناتك.
• قم بإنشاء رمز API في axiom مع أذونات لإنشاء مجموعات البيانات وقراءتها وتحديثها وحذفها.
• تطبيق Next.js جديد أو موجود.

تثبيت المحور التالي

1. في المحطة الخاصة بك ، انتقل إلى المجلد الجذري لتطبيق Next.js الخاص بك ، ثم قم بتشغيل npm install --save next-axiom لتثبيت أحدث إصدار من المحاور التالية.
2. أضف متغيرات البيئة التالية إلى تطبيق Next.js الخاص بك. لمزيد من المعلومات ، راجع وثائق Vercel.
   • NEXT_PUBLIC_AXIOM_DATASET هو اسم مجموعة بيانات Axiom حيث تريد إرسال البيانات.
   • NEXT_PUBLIC_AXIOM_TOKEN هو رمز Axiom API الذي أنشأته.
3. في ملف next.config.ts ، قم بلف تكوين NEXT.JS في withAxiom :

 const { withAxiom } = require ( 'next-axiom' ) ;

module . exports = withAxiom ( {
  // Your existing configuration.
} ) ; 

التقاط طلبات حركة المرور

لالتقاط طلبات حركة المرور ، قم بإنشاء ملف middleware.ts في المجلد الجذري لتطبيق Next.js الخاص بك:

 import { Logger } from 'next-axiom'
import { NextResponse } from 'next/server'
import type { NextFetchEvent , NextRequest } from 'next/server'

export async function middleware ( request : NextRequest , event : NextFetchEvent ) {
    const logger = new Logger ( { source : 'middleware' } ) ; // traffic, request
    logger . middleware ( request )

    event . waitUntil ( logger . flush ( ) )
    return NextResponse . next ( )

// For more information, see Matching Paths below
export const config = {
}

logger.middleware يقبل كائن التكوين كوسيطة ثانية. يمكن أن يحتوي هذا الكائن على الخصائص التالية:

• logRequestDetails : يقبل منطقية أو مجموعة من المفاتيح. إذا قمت بتمرير true ، فستضيف جميع تفاصيل الطلب إلى السجل (الطريقة ، URL ، الرؤوس ، إلخ). إذا قمت بتمرير مجموعة من الأوتار ، فستضيف فقط المفاتيح المحددة. راجع طلب و Nextrequest للوثائق على المفاتيح المتاحة. إذا تم تمكين logRequestDetails ، فستقوم الوظيفة بإرجاع وعد يحتاج إلى انتظار.

 export async function middleware ( request : NextRequest , event : NextFetchEvent ) {
  const logger = new Logger ( { source : "middleware" } ) ;
  await logger . middleware ( request , { logRequestDetails : [ "body" , "nextUrl" ] } ) ;

  event . waitUntil ( logger . flush ( ) ) ;
  return NextResponse . next ( ) ;
} 

حيويات الويب

لإرسال شبكة الإنترنت إلى Axiom ، أضف مكون AxiomWebVitals من المحور التالي إلى ملف app/layout.tsx :

 import { AxiomWebVitals } from 'next-axiom' ;

export default function RootLayout ( ) {
  return (
    < html >
      ...
      < AxiomWebVitals / >
      < div > ... < / div >
    < / html >
  ) ;
}

يتم إرسال شبكة الإنترنت على شبكة الإنترنت فقط من عمليات نشر الإنتاج.

سجلات

إرسال سجلات إلى Axiom من أجزاء مختلفة من التطبيق الخاص بك. تأخذ كل استدعاء دالة السجل رسالة وكائن fields اختياري.

 log . debug ( 'Login attempt' , { user : 'j_doe' , status : 'success' } ) ; // Results in {"message": "Login attempt", "fields": {"user": "j_doe", "status": "success"}}
log . info ( 'Payment completed' , { userID : '123' , amount : '25USD' } ) ;
log . warn ( 'API rate limit exceeded' , { endpoint : '/users/1' , rateLimitRemaining : 0 } ) ;
log . error ( 'System Error' , { code : '500' , message : 'Internal server error' } ) ;

معالجات الطريق

لف معالجات الطريق الخاصة بك في withAxiom لإضافة مسجل إلى طلبك وتسجيل استثناءات السجل تلقائيًا:

 import { withAxiom , AxiomRequest } from 'next-axiom' ;

export const GET = withAxiom ( ( req : AxiomRequest ) => {
  req . log . info ( 'Login function called' ) ;

  // You can create intermediate loggers
  const log = req . log . with ( { scope : 'user' } ) ;
  log . info ( 'User logged in' , { userId : 42 } ) ;

  return NextResponse . json ( { hello : 'world' } ) ;
} ) ;

تقبل معالجات الطريق كائن التكوين كوسيطة ثانية. يمكن أن يحتوي هذا الكائن على الخصائص التالية:

• logRequestDetails : يقبل منطقية أو مجموعة من المفاتيح. إذا قمت بتمرير true ، فستضيف جميع تفاصيل الطلب إلى السجل (الطريقة ، URL ، الرؤوس ، إلخ). إذا قمت بتمرير مجموعة من الأوتار ، فستضيف فقط المفاتيح المحددة. راجع طلب و Nextrequest للوثائق على المفاتيح المتاحة.

• NotFoundLogLevel : تجاوز مستوى السجل للأخطاء not_found. الافتراضات warn .

• RedirectLogLevel : تجاوز مستوى السجل للأخطاء next_redirect. الإعدادات الافتراضية info .

مثال التكوين:

 export const GET = withAxiom (
  async ( ) => {
    return new Response ( "Hello World!" ) ;
  } ,
  { 
    logRequestDetails : [ 'body' , 'nextUrl' ] , // { logRequestDetails: true } is also valid
    NotFoundLogLevel : 'error' ,
    RedirectLogLevel : 'debug' ,
  }
) ;

مكونات العميل

لإرسال سجلات من مكونات العميل ، أضف useLogger من المحور التالي إلى المكون الخاص بك:

 'use client' ;
import { useLogger } from 'next-axiom' ;

export default function ClientComponent ( ) {
  const log = useLogger ( ) ;
  log . debug ( 'User logged in' , { userId : 42 } ) ;
  return < h1 > Logged in < / h1 > ;
}

مكونات الخادم

لإرسال سجلات من مكونات الخادم ، أضف Logger من المحور التالي إلى المكون الخاص بك ، واتصل بالتدفق قبل العودة:

 import { Logger } from 'next-axiom' ;

export default async function ServerComponent ( ) {
  const log = new Logger ( ) ;
  log . info ( 'User logged in' , { userId : 42 } ) ;

  // ...

  await log . flush ( ) ;
  return < h1 > Logged in < / h1 > ;
}

مستويات السجل

يحدد مستوى السجل أدنى مستوى من السجلات المرسلة إلى Axiom. اختر أحد المستويات التالية (من أدنى إلى الأعلى):

• debug هو الإعداد الافتراضي. وهذا يعني أنك ترسل جميع السجلات إلى axiom.
• info
• warn
• error يعني أنك ترسل فقط سجلات أعلى مستوى إلى Axiom.
• يعني off أنك لا ترسل أي سجلات إلى Axiom.

على سبيل المثال ، لإرسال جميع السجلات باستثناء سجلات التصحيح إلى Axiom:

 export NEXT_PUBLIC_AXIOM_LOG_LEVEL=info

أخطاء التقاط

لالتقاط أخطاء التوجيه ، استخدم آلية معالجة الأخطاء لـ NEXT.JS:

1. انتقل إلى مجلد app .
2. إنشاء ملف error.tsx .
3. داخل وظيفة المكون الخاص بك ، أضف useLogger من المحور التالي لإرسال الخطأ إلى axiom. على سبيل المثال:

 "use client" ;

import { useLogger , LogLevel } from "next-axiom" ;
import { usePathname } from "next/navigation" ;

export default function ErrorPage ( {
  error ,
} : {
  error : Error & { digest ?: string } ;
} ) {
  const pathname = usePathname ( )
  const log = useLogger ( { source : "error.tsx" } ) ;
  let status =  error . message == 'Invalid URL' ? 404 : 500 ;

  log . logHttpRequest (
    LogLevel . error ,
    error . message ,
    {
      host : window . location . href ,
      path : pathname ,
      statusCode : status ,
    } ,
    {
      error : error . name ,
      cause : error . cause ,
      stack : error . stack ,
      digest : error . digest ,
    } ,
  ) ;

  return (
    < div className = "p-8" >
      Ops ! An Error has occurred : { " " }
      < p className = "text-red-400 px-8 py-2 text-lg" > `{error.message}` < / p>
      < div className = "w-1/3 mt-8" >
        < NavTable / >
      < / div >
    < / div >
  ) ;
} 

الترقية إلى جهاز توجيه التطبيق

تحول المحور التالي لدعم جهاز توجيه التطبيق بدءًا من الإصدار 1.0. إذا كنت تقوم بترقية تطبيق Router Pages باستخدام AXIOM V0.x التالي ، فستحتاج إلى إجراء التغييرات التالية:

• ترقية المحور التالي إلى الإصدار 1.0.0 أو أعلى
• تأكد من أن المتغيرات المصدرة لديها prefix NEXT_PUBLIC_ على سبيل المثال: NEXT_PUBLIC_AXIOM_TOKEN
• استخدم خطاف useLogger في مكونات العميل بدلاً من log الدعامة
• بالنسبة للمكونات الجانبية للخادم ، ستحتاج إلى إنشاء مثيل من Logger وطرح السجلات قبل إرجاع المكون.
• بالنسبة إلى حركات الويب ، قم بإزالة reportWebVitals() وبدلاً من ذلك إضافة مكون AxiomWebVitals إلى تخطيطك.

التعليمات

كيف يمكنني إرسال سجلات من عمليات نشر Vercel Preview؟

يقوم تكامل Axiom Vercel بإعداد متغير بيئة يسمى NEXT_PUBLIC_AXIOM_INGEST_ENDPOINT ، والذي يتم تمكينه افتراضيًا فقط لبيئة الإنتاج. لإرسال سجلات من عمليات النشر المعاينة ، انتقل إلى إعدادات موقعك في Vercel وتمكين عمليات النشر المعاينة لمتغير البيئة هذا.

كيف يمكنني تمديد المسجل؟

يمكنك استخدام log.with لإنشاء مسجل وسيطة ، على سبيل المثال:

 const logger = userLogger ( ) . with ( { userId : 42 } ) ;
logger . info ( 'Hi' ) ; // will ingest { ..., "message": "Hi", "fields" { "userId": 42 }} 

رخصة

موزعة تحت رخصة معهد ماساتشوستس للتكنولوجيا.