Node.js | ClickHouse Docs

يستخدم ClickStack معيار OpenTelemetry لجمع بيانات القياس عن بُعد (السجلات والمقاييس والتتبعات والاستثناءات). تُنشأ التتبعات تلقائيًا عبر الرصد التلقائي، لذا لا يلزم إجراء رصد يدوي للاستفادة من التتبع.

يُكامل هذا الدليل ما يلي:

السجلات
المقاييس
التتبعات
الاستثناءات

بدء الاستخدام

ثبّت حزمة HyperDX OpenTelemetry الخاصة بالرصد

استخدم الأمر التالي لتثبيت حزمة ClickStack OpenTelemetry.

npm install @hyperdx/node-opentelemetry

yarn add @hyperdx/node-opentelemetry

تهيئة SDK

لتهيئة SDK، ستحتاج إلى استدعاء الدالة init في بداية نقطة الدخول الخاصة بتطبيقك.

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // احذف هذا الحقل في Managed ClickStack
    service: 'my-service'
});

import * as HyperDX from '@hyperdx/node-opentelemetry';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // احذف هذا الحقل في Managed ClickStack
    service: 'my-service'
});

سيؤدي ذلك تلقائيًا إلى التقاط بيانات التتبّع والمقاييس والسجلات من تطبيق Node.js الخاص بك.

إعداد جمع السجلات

افتراضيًا، تُجمَع سجلات console.* تلقائيًا. إذا كنت تستخدم logger مثل winston أو pino، فستحتاج إلى إضافة transport إلى logger لديك لإرسال السجلات إلى ClickStack. وإذا كنت تستخدم نوعًا آخر من logger، فتواصل معنا أو اطّلِع على أحد تكاملات منصتنا إن كان ذلك مناسبًا (مثل Kubernetes).

إذا كنت تستخدم winston كـ logger، فستحتاج إلى إضافة transport التالي إلى logger لديك.

    import winston from 'winston';
    import * as HyperDX from '@hyperdx/node-opentelemetry';

    const logger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        new winston.transports.Console(),
        HyperDX.getWinstonTransport('info', { // إرسال سجلات المستوى info وما فوق
          detectResources: true,
        }),
      ],
    });

    export default logger;

إذا كنت تستخدم pino كـ logger، فستحتاج إلى إضافة transport التالي إلى logger لديك وتحديد mixin لربط السجلات بالتتبعات.

import pino from 'pino';
import * as HyperDX from '@hyperdx/node-opentelemetry';

const logger = pino(
    pino.transport({
    mixin: HyperDX.getPinoMixinFunction,
    targets: [
        HyperDX.getPinoTransport('info', { // إرسال سجلات المستوى info وما فوق
        detectResources: true,
        }),
    ],
    }),
);

export default logger;

افتراضيًا، أساليب console.* مدعومة مباشرةً دون الحاجة إلى أي إعداد إضافي.

يمكنك تعطيل ذلك بتعيين متغير البيئة HDX_NODE_CONSOLE_CAPTURE إلى 0 أو بتمرير consoleCapture: false إلى الدالة init.

إعداد التقاط الأخطاء

يمكن لحزمة SDK الخاصة بـ ClickStack التقاط الاستثناءات والأخطاء غير المعالَجة تلقائيًا في تطبيقك، مع stack trace كامل وسياق الشيفرة.

لتمكين ذلك، ستحتاج إلى إضافة الكود التالي في نهاية البرمجية الوسيطة لمعالجة الأخطاء في تطبيقك، أو التقاط الاستثناءات يدويًا باستخدام الدالة recordException.

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // احذف هذا عند استخدام Managed ClickStack
    service: 'my-service'
});
const app = express();

// أضف المسارات الخاصة بك، وما إلى ذلك.

// أضف هذا بعد جميع المسارات،
// ولكن قبل تعريف أي برمجيات وسيطة أخرى لمعالجة الأخطاء
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // احذف هذا عند استخدام Managed ClickStack
    service: 'my-service'
});

const router = new Router();
const app = new Koa();

HyperDX.setupKoaErrorHandler(app);

// أضف المسارات الخاصة بك، وما إلى ذلك.

app.listen(3030);

const HyperDX = require('@hyperdx/node-opentelemetry');

function myErrorHandler(error, req, res, next) {
    // يمكن استخدام هذا في أي موضع داخل تطبيقك
    HyperDX.recordException(error);
}

استكشاف الأخطاء وإصلاحها

إذا كنت تواجه مشكلة في الـ SDK، يمكنك تفعيل التسجيل المطوّل عبر ضبط متغير البيئة OTEL_LOG_LEVEL على debug.

export OTEL_LOG_LEVEL=debug

التهيئة المتقدّمة للرصد

التقاط سجلات وحدة التحكم

افتراضيًا، تلتقط حزمة SDK الخاصة بـ ClickStack سجلات وحدة التحكم. يمكنك تعطيل ذلك عن طريق ضبط متغير البيئة HDX_NODE_CONSOLE_CAPTURE على 0.

export HDX_NODE_CONSOLE_CAPTURE=0

إرفاق معلومات المستخدم أو البيانات الوصفية

لتوسيم جميع الأحداث المرتبطة بسهولة بسمة أو معرّف معيّن (مثل: معرّف المستخدم أو البريد الإلكتروني)، يمكنك استدعاء الدالة setTraceAttributes، التي ستوسم كل سجل/‏span مرتبط بالتتبّع الحالي بعد الاستدعاء بالسمات المُعلنة. ويُوصى باستدعاء هذه الدالة في أقرب وقت ممكن ضمن طلب/‏trace معيّن (مثل: في أقرب مرحلة ممكنة ضمن مكدس Express للبرمجيات الوسيطة).

تُعد هذه طريقة عملية لضمان توسيم جميع السجلات/‏spans تلقائيًا بالمعرّفات الصحيحة لتسهيل البحث عنها لاحقًا، بدلًا من الاضطرار إلى توسيم المعرّفات وتمريرها يدويًا بنفسك.

ستؤدي userId وuserEmail وuserName وteamName إلى تعبئة واجهة الجلسات بالقيم المقابلة، لكن يمكن الاستغناء عنها. ويمكن تحديد أي قيم إضافية أخرى واستخدامها للبحث عن الأحداث.

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // Get user information from the request...

  // Attach user information to the current trace
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

تأكد من تفعيل وضع Beta عبر ضبط متغير البيئة HDX_NODE_BETA_MODE على 1 أو بتمرير betaMode: true إلى الدالة init من أجل تفعيل سمات التتبّع.

export HDX_NODE_BETA_MODE=1

Google Cloud Run

إذا كنت تشغّل تطبيقك على Google Cloud Run، فإن Cloud Trace يضيف تلقائيًا رؤوس أخذ العينات إلى الطلبات الواردة، مما يقيّد حاليًا التتبعات بحيث لا تُؤخذ منها عينات إلا بمعدل 0.1 طلب في الثانية لكل مثيل.

تضبط حزمة @hyperdx/node-opentelemetry معدل أخذ العينات على 1.0 بشكل افتراضي.

لتغيير هذا السلوك، أو لتهيئة عمليات تثبيت OpenTelemetry أخرى، يمكنك ضبط متغيرات البيئة يدويًا OTEL_TRACES_SAMPLER=parentbased_always_on و OTEL_TRACES_SAMPLER_ARG=1 من أجل تحقيق النتيجة نفسها.

لمعرفة المزيد، ولفرض التتبع لطلبات محددة، يُرجى الرجوع إلى وثائق Google Cloud Run.

المكتبات المزوّدة بأدوات الرصد تلقائيًا

سيضيف SDK التتبّع تلقائيًا إلى المكتبات التالية:

طريقة تثبيت بديلة

شغّل التطبيق باستخدام ClickStack OpenTelemetry CLI

بدلاً من ذلك، يمكنك تفعيل الرصد التلقائي لتطبيقك من دون أي تغييرات على الشيفرة باستخدام واجهة سطر الأوامر opentelemetry-instrument أو عبر الخيار --require في Node.js. يوفّر تثبيت CLI نطاقًا أوسع من المكتبات وأطر العمل المزوّدة بالرصد التلقائي.

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js

// استورد هذا في أعلى أول ملف يتم تحميله في تطبيقك
// ستظل بحاجة إلى تحديد مفتاح API عبر متغير البيئة `HYPERDX_API_KEY`
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // اختياري، default: true
    additionalInstrumentations: [], // اختياري، default: []
});

يُستخدم متغير البيئة OTEL_SERVICE_NAME للتعريف بخدمتك في تطبيق HyperDX، ويمكن أن يكون أي اسم تريده.

تمكين التقاط الاستثناءات

لتمكين التقاط الاستثناءات غير المعالَجة، عليك ضبط متغير البيئة HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE على القيمة 1.

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

بعد ذلك، لالتقاط الاستثناءات تلقائيًا من Express أو Koa، أو للتعامل مع الاستثناءات يدويًا، اتبع الإرشادات الواردة في قسم إعداد جمع الأخطاء أعلاه.

المكتبات التي تُزوَّد بأدوات الرصد تلقائيًا

سيتم تزويد المكتبات التالية بأدوات الرصد تلقائيًا (لتجميع التتبعات) باستخدام طرق التثبيت المذكورة أعلاه: