إرسال البيانات

يستقبل Instatus السجلات والتتبعات والمقاييس عبر OpenTelemetry (‏OTLP عبر HTTPS). هناك طريقتان لربط تطبيق. اختر واحدة.

الطريقة 1: انسخ موجّهًا

الطريقة الأسرع إذا كنت تستخدم وكيل برمجة مثل Claude Code أو Cursor أو Copilot.

  1. افتح Observability في صفحة الحالة.
  2. ضمن تضمين، حدّد ما تريد إرساله: السجلات والتتبعات والمقاييس. حدّد أيضًا لوحة معلومات أولية إذا أردت لاحقًا لوحات معلومات جاهزة لخدماتك.
  3. انقر على نسخ الموجّه.
  4. الصقه في وكيل البرمجة داخل مشروع تطبيقك.
  5. ضع مفتاح API في متغير البيئة INSTATUS_API_KEY، ثم شغّل الاختبار الذي يقترحه الوكيل.
بطاقة الإعداد مع السجلات والتتبعات والمقاييس المراد تضمينها وزر لنسخ الموجّه

يطلب الموجّه من الوكيل استخدام حزمة OpenTelemetry SDK الرسمية للغتك، والإبقاء على مكتبة السجلات الحالية، وقراءة المفتاح من متغير بيئة وعدم إيداعه في المستودع أبدًا. معرّف صفحتك موجود فيه مسبقًا.

الطريقة 2: الإعداد يدويًا

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

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

ما يحتاجه كل طلب

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

يمنح مفتاح API الوصول إلى حسابك بالكامل. احفظه على خوادمك في متغير بيئة. لا تضعه أبدًا في متصفح أو تطبيق جوال أو مستودع عام.

اعثر على مفتاح API

افتح قائمة الصورة الرمزية، واختر إعدادات المستخدم ثم المطوّر، أو انتقل مباشرةً إلى إعدادات المطوّر. انقر على نسخ بجانب المفتاح.

مفتاح API في إعدادات المطوّر مع زر النسخ

اعثر على معرّف صفحتك

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

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.js
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register app.js
# Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
OTEL_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 logging
import os
from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.resources import Resource
provider = 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.com
headers:
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 من إعدادات المطوّر يتوقف المفتاح القديم فورًا، لذا حدّث أولًا كل تطبيق يستخدمه.