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

Source: https://instatus.com/help/ar/observability/send-logs

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

| At a glance | Details |
| :-- | :-- |
| [الأسرع](https://instatus.com/help/ar/observability/send-logs#الطريقة-1-انسخ-موجّهًا) | انسخ موجّهًا لوكيل البرمجة لديك |
| [يدويًا](https://instatus.com/help/ar/observability/send-logs#الطريقة-2-الإعداد-يدويًا) | اختر لغتك والصق الشيفرة |
| [نقطة النهاية](https://instatus.com/help/ar/observability/send-logs#ما-يحتاجه-كل-طلب) | https://otel.instatus.com مع ترويستين |
| [اختبار](https://instatus.com/help/ar/observability/send-logs#أرسل-سجلًا-تجريبيًا) | طلب curl واحد |
| [لا يظهر شيء؟](https://instatus.com/help/ar/observability/send-logs#حل-المشكلات) | حلّ المشكلات الشائعة |

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

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

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

![بطاقة الإعداد مع السجلات والتتبعات والمقاييس المراد تضمينها وزر لنسخ الموجّه](https://instatus.com/help/observability/setup.png)

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

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

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

![الإعداد اليدوي مع اختيار Node.js، ويظهر أمر التثبيت وشيفرة الإعداد](https://instatus.com/help/observability/setup-by-hand.png)

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

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

| العنصر          | القيمة                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| نقطة النهاية      | `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

افتح قائمة الصورة الرمزية، واختر **إعدادات المستخدم** ثم **المطوّر**، أو انتقل مباشرةً إلى [إعدادات المطوّر](https://dashboard.instatus.com/developer). انقر على **نسخ** بجانب المفتاح.

![مفتاح API في إعدادات المطوّر مع زر النسخ](https://instatus.com/help/observability/api-key.png)

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

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

![Copy Project ID في قائمة اسم المشروع](https://instatus.com/help/observability/copy-page-id.png)

## أرسل سجلًا تجريبيًا

يكفي طلب واحد من الطرفية للتحقق من المفتاح ومعرّف الصفحة:

```bash
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 تقرأ متغيرات البيئة نفسها. بها يرسل القياس التلقائي التتبعات والمقاييس والسجلات دون المساس بشيفرتك:

```bash
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. بعد ذلك شغّل تطبيقك مع القياس التلقائي الخاص بلغته:

```bash
# 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 دون شيفرة](https://opentelemetry.io/docs/zero-code/).

## Node.js

لإرسال السجلات من شيفرتك، ثبّت حزمة السجلات:

```bash
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \
  @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
```

اضبطها مرة واحدة عند بدء تشغيل التطبيق:

```js
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`](https://www.npmjs.com/package/pino-opentelemetry-transport) و[`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) كل سطر سجل موجود كما هو.

## Python

```bash
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

ترتبط الحزمة بوحدة `logging` في Python، لذا تُرسل استدعاءات `logging` الحالية كما هي:

```python
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 كمُصدِّر واترك تطبيقاتك كما هي:

```yaml
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`                       | نفدت حصة البيانات لهذا الشهر. راجع [الخطط والحدود](https://instatus.com/help/ar/observability#الخطط-والحدود).                    |
| `200` لكن لا يظهر شيء | انتظر بضع ثوانٍ، ثم تحقق من النطاق الزمني. السجل ذو الطابع الزمني في الماضي لا يظهر إلا إذا شمله النطاق. |
| لا شيء على الإطلاق              | ترسل الحزم البيانات على دفعات. تأكد من أن تطبيقك يفرّغ المزوّد أو يغلقه قبل الخروج.                           |

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

- [السجلات](https://instatus.com/help/ar/observability/logs): ابحث في سجلاتك وصفِّها وتابعها مباشرةً
- [التتبعات](https://instatus.com/help/ar/observability/traces): اعرف أين يقضي كل طلب وقته
