دليل OpenTelemetry مع AllStak

التثبيت

ثبّت المُصدِّر مع OpenTelemetry Node SDK والتجهيزات التلقائية.

npm install @allstak/otel @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

الإعداد

استخدم AllStakOtelExporter كـ traceExporter لـ NodeSDK.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { AllStakOtelExporter } from '@allstak/otel';

const sdk = new NodeSDK({
  traceExporter: new AllStakOtelExporter({
    apiKey: process.env.ALLSTAK_API_KEY!,
    environment: process.env.NODE_ENV ?? 'production',
    release: process.env.ALLSTAK_RELEASE,
    serviceName: 'api',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

مثال أساسي

يمكنك أيضًا استخدام المُصدِّر مباشرةً (يطبّق عقد SpanExporter لـ OTel).

const exporter = new AllStakOtelExporter({ apiKey: process.env.ALLSTAK_API_KEY!, serviceName: 'worker' });
exporter.export([span], (result) => {
  if (result.code !== 0) console.error(result.error);
});
await exporter.forceFlush();

التقاط الأخطاء

تحوّل هذه الحزمة spans الخاصة بـ OpenTelemetry وترسلها — وليس فيها واجهة بأسلوب captureException. وتأتي spans الأخطاء والطلبات من تجهيزات OpenTelemetry لديك (مثل auto-instrumentations-node)، ويرسلها المُصدِّر إلى AllStak.

تتبّع الطلبات

تنتج spans الطلبات/HTTP من تجهيزات OpenTelemetry التلقائية (تثبيت peer)، لا من هذه الحزمة — يحوّل المُصدِّر spans الخاصة بـ OTel إلى OTLP JSON ويرسلها إلى AllStak فقط.

أفضل الممارسات

• ثبّت OpenTelemetry SDK + التجهيزات التلقائية بجانب هذا المُصدِّر.
• وفّر مفتاح API عبر ALLSTAK_API_KEY.
• اضبط serviceName و environment و release على المُصدِّر.