إرسال البيانات
يستقبل Instatus السجلات والتتبعات والمقاييس عبر OpenTelemetry (OTLP عبر HTTPS). هناك طريقتان لربط تطبيق. اختر واحدة.
الطريقة 1: انسخ موجّهًا
الطريقة الأسرع إذا كنت تستخدم وكيل برمجة مثل Claude Code أو Cursor أو Copilot.
- افتح Observability في صفحة الحالة.
- ضمن تضمين، حدّد ما تريد إرساله: السجلات والتتبعات والمقاييس. حدّد أيضًا لوحة معلومات أولية إذا أردت لاحقًا لوحات معلومات جاهزة لخدماتك.
- انقر على نسخ الموجّه.
- الصقه في وكيل البرمجة داخل مشروع تطبيقك.
- ضع مفتاح API في متغير البيئة
INSTATUS_API_KEY، ثم شغّل الاختبار الذي يقترحه الوكيل.

يطلب الموجّه من الوكيل استخدام حزمة OpenTelemetry SDK الرسمية للغتك، والإبقاء على مكتبة السجلات الحالية، وقراءة المفتاح من متغير بيئة وعدم إيداعه في المستودع أبدًا. معرّف صفحتك موجود فيه مسبقًا.
الطريقة 2: الإعداد يدويًا
- افتح Observability في صفحة الحالة.
- انقر على الإعداد يدويًا.
- اختر لغتك: Node.js أو Python أو Go أو Java أو .NET أو Ruby أو PHP أو OpenTelemetry Collector.
- انسخ أمر التثبيت وشغّله، ثم انسخ شيفرة الإعداد إلى تطبيقك.
- اضبط متغير البيئة
INSTATUS_API_KEYعلى مفتاح API وشغّل تطبيقك.

الشيفرة في لوحة التحكم تحتوي على معرّف صفحتك مسبقًا. الأمثلة نفسها موجودة أدناه إن أردت نسخها من هنا.
ما يحتاجه كل طلب
| العنصر | القيمة |
|---|---|
| نقطة النهاية | https://otel.instatus.com. تُرسل السجلات إلى /v1/logs، والتتبعات إلى /v1/traces، والمقاييس إلى /v1/metrics. |
Authorization | Bearer <API_KEY> بمفتاح مالك الصفحة أو مسؤولها أو محررها. |
X-Instatus-Site-Id | معرّف صفحة الحالة التي تنتمي إليها البيانات. |
| البروتوكول | OTLP عبر HTTP، بصيغة protobuf أو JSON. إذا كانت حزمة SDK تستخدم gRPC افتراضيًا، فحوّلها إلى HTTP. |
يمنح مفتاح API الوصول إلى حسابك بالكامل. احفظه على خوادمك في متغير بيئة. لا تضعه أبدًا في متصفح أو تطبيق جوال أو مستودع عام.
اعثر على مفتاح API
افتح قائمة الصورة الرمزية، واختر إعدادات المستخدم ثم المطوّر، أو انتقل مباشرةً إلى إعدادات المطوّر. انقر على نسخ بجانب المفتاح.

اعثر على معرّف صفحتك
نادرًا ما تحتاج إليه: فالموجّه والشيفرة في لوحة التحكم يحتويانه مسبقًا. لنسخه بنفسك، انقر بزر الفأرة الأيمن على اسم المشروع أعلى لوحة التحكم واختر Copy Project ID.

أرسل سجلًا تجريبيًا
يكفي طلب واحد من الطرفية للتحقق من المفتاح ومعرّف الصفحة:
curl -X POST https://otel.instatus.com/v1/logs \-H "Authorization: Bearer $INSTATUS_API_KEY" \-H "X-Instatus-Site-Id: $INSTATUS_PAGE_ID" \-H "Content-Type: application/json" \-d '{"resourceLogs": [{"resource": {"attributes": [{ "key": "service.name", "value": { "stringValue": "api" } }]},"scopeLogs": [{"logRecords": [{"timeUnixNano": "'$(date +%s)'000000000","severityText": "INFO","body": { "stringValue": "Hello from Instatus" }}]}]}]}'
الاستجابة 200 تعني أن السجل قُبل. افتح Observability ← السجلات وستجده خلال ثوانٍ.
أي لغة، دون تعديل الشيفرة
كل حزم OpenTelemetry SDK تقرأ متغيرات البيئة نفسها. بها يرسل القياس التلقائي التتبعات والمقاييس والسجلات دون المساس بشيفرتك:
export OTEL_SERVICE_NAME="api"export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.instatus.com"export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${INSTATUS_API_KEY},X-Instatus-Site-Id=${INSTATUS_PAGE_ID}"export OTEL_TRACES_EXPORTER="otlp"export OTEL_METRICS_EXPORTER="otlp"export OTEL_LOGS_EXPORTER="otlp"
تُكتب المسافة بعد Bearer على هيئة %20، لأن متغير الترويسات مُرمّز كعنوان URL. بعد ذلك شغّل تطبيقك مع القياس التلقائي الخاص بلغته:
# Node.jsnpm install @opentelemetry/api @opentelemetry/auto-instrumentations-nodenode --require @opentelemetry/auto-instrumentations-node/register app.js# Pythonpip install opentelemetry-distro opentelemetry-exporter-otlpopentelemetry-bootstrap -a installOTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py
لـ Java و.NET وGo وRuby وPHP قياس تلقائي خاص بها يقرأ المتغيرات نفسها. راجع أدلة OpenTelemetry دون شيفرة.
Node.js
لإرسال السجلات من شيفرتك، ثبّت حزمة السجلات:
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \@opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
اضبطها مرة واحدة عند بدء تشغيل التطبيق:
import { SeverityNumber } from '@opentelemetry/api-logs'import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'import { resourceFromAttributes } from '@opentelemetry/resources'import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs'const provider = new LoggerProvider({resource: resourceFromAttributes({ 'service.name': 'api' }),processors: [new BatchLogRecordProcessor(new OTLPLogExporter({url: 'https://otel.instatus.com/v1/logs',headers: {Authorization: `Bearer ${process.env.INSTATUS_API_KEY}`,'X-Instatus-Site-Id': process.env.INSTATUS_PAGE_ID}}))]})const logger = provider.getLogger('api')logger.emit({severityNumber: SeverityNumber.ERROR,severityText: 'ERROR',body: 'Payment failed: card declined',attributes: { 'customer.id': 'cus_123', route: '/v2/charges' }})process.on('beforeExit', () => provider.shutdown())
تستخدم pino أو winston بالفعل؟ أبقِ عليهما. ترسل pino-opentelemetry-transport و@opentelemetry/winston-transport كل سطر سجل موجود كما هو.
Python
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
ترتبط الحزمة بوحدة logging في Python، لذا تُرسل استدعاءات logging الحالية كما هي:
import loggingimport osfrom opentelemetry._logs import set_logger_providerfrom opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporterfrom opentelemetry.sdk._logs import LoggerProvider, LoggingHandlerfrom opentelemetry.sdk._logs.export import BatchLogRecordProcessorfrom opentelemetry.sdk.resources import Resourceprovider = LoggerProvider(resource=Resource.create({"service.name": "worker"}))provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter(endpoint="https://otel.instatus.com/v1/logs",headers={"Authorization": f"Bearer {os.environ['INSTATUS_API_KEY']}","X-Instatus-Site-Id": os.environ["INSTATUS_PAGE_ID"],},)))set_logger_provider(provider)logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=provider))logging.getLogger().setLevel(logging.INFO)logging.warning("Card declined for customer %s", "cus_123")
OpenTelemetry Collector
تشغّل OpenTelemetry Collector بالفعل؟ أضف Instatus كمُصدِّر واترك تطبيقاتك كما هي:
exporters:otlphttp/instatus:endpoint: https://otel.instatus.comheaders:Authorization: Bearer ${env:INSTATUS_API_KEY}X-Instatus-Site-Id: ${env:INSTATUS_PAGE_ID}service:pipelines:logs:receivers: [otlp]processors: [batch]exporters: [otlphttp/instatus]traces:receivers: [otlp]processors: [batch]exporters: [otlphttp/instatus]metrics:receivers: [otlp]processors: [batch]exporters: [otlphttp/instatus]
يضيف المُصدِّر /v1/logs و/v1/traces و/v1/metrics بنفسه، لذا تكون نقطة النهاية هي المضيف فقط. لإرسال ملفات السجلات، أضف مستقبِل filelog إلى مسار السجلات.
ما الذي ترسله
يقرأ Instatus هذه الحقول. كل ما عداها يُحفظ كسمة يمكنك البحث والتصفية بها.
| الحقل | يُستخدم في |
|---|---|
service.name (المورد) | عمود الخدمة وعامل التصفية الخاص به. اضبطه في كل تطبيق وعامل ومهمة. |
body | نص السجل، وهو ما يبحث فيه البحث النصي الحر. |
severityText أو severityNumber | المستوى: fatal أو error أو warn أو info أو debug أو trace. |
traceId و spanId | يربط السجل بتتبعه لتتنقل بينهما. |
| السمات | أي شيء تضيفه، مثل customer.id أو http.route. يصبح كلٌّ منها عامل تصفية. |
السمات التي تبدأ بـ instatus. محجوزة وتُستبدل عند وصول البيانات.
حل المشكلات
| ما تراه | الحل |
|---|---|
401 | تحقق من المفتاح ومن الترويسة X-Instatus-Site-Id. يجب أن يكون صاحب المفتاح مالك الصفحة أو مسؤولها أو محررها. |
400 | المحتوى ليس OTLP صالحًا. تحقق من Content-Type ومن بنية JSON في السجل التجريبي. |
429 | نفدت حصة البيانات لهذا الشهر. راجع الخطط والحدود. |
200 لكن لا يظهر شيء | انتظر بضع ثوانٍ، ثم تحقق من النطاق الزمني. السجل ذو الطابع الزمني في الماضي لا يظهر إلا إذا شمله النطاق. |
| لا شيء على الإطلاق | ترسل الحزم البيانات على دفعات. تأكد من أن تطبيقك يفرّغ المزوّد أو يغلقه قبل الخروج. |
عند إعادة إنشاء مفتاح API من إعدادات المطوّر يتوقف المفتاح القديم فورًا، لذا حدّث أولًا كل تطبيق يستخدمه.