> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# دمج SDK لإرسال بيانات القياس عن بُعد من التطبيق

> اختر حزمة LogBrew SDK المناسبة لبيئة التشغيل، واضبط مفتاح الاستيعاب. أرسل بيانات القياس عن بُعد من التطبيق، وابحث عن الحدث التجريبي في مشروعك.

ثبّت حزمة LogBrew SDK الخاصة ببيئة التشغيل لديك. ينسّق الـ SDK الأحداث ويسلّمها.
وتسرد إرشادات الحزمة أنواع الأحداث والحدود وسلوك إعادة المحاولة.

نفّذ هذه الخطوات في كل عملية دمج:

1. ثبّت حزمة SDK الخاصة ببيئة التشغيل لديك.
2. أبقِ مفتاح الاستيعاب الخاص بالمشروع خارج نظام إدارة الشيفرة المصدرية.
3. اضبط قيمًا ثابتة للخدمة والبيئة والإصدار.
4. أرسل حدثًا تجريبيًا آمنًا واحدًا من التطبيق.
5. اقرأ نتيجة التسليم. ثم ابحث عن الحدث في LogBrew.

الدفعة المقبولة وصلت إلى LogBrew API. لكن عوامل التصفية قد تُخفي أحداثها. اختر
المشروع الصحيح والنطاق الزمني الصحيح. ثم طابِق الخدمة والبيئة والإصدار ونوع
الإشارة.

قبل أن تفعّل الالتقاط، [اختر الحقول المعتمدة واختبرها](/ar/guides/safe-capture).
لملء «التحليلات»، اتبع [التقاط أحداث المنتج](/ar/guides/product-events).

## <span id="item-types">الإشارات والسياق المشترك</span>

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

<CardGroup cols={2}>
  <Card title="log" icon="file-text">
    رسالة منظّمة لها خطورة ومصدر ووقت وسياق آمن.
  </Card>

  <Card title="trace_span" icon="route">
    عملية واحدة محددة التوقيت، مرتبطة بتتبّعها عبر معرّفَي التتبّع والـ Span.
  </Card>

  <Card title="issue" icon="bug">
    عطل ملتقَط، وخطورته، وتفاصيل الخطأ التي أرسلها التطبيق.
  </Card>

  <Card title="action" icon="mouse-pointer-click">
    إجراء في تطبيقك، مع كيان وجلسة وخصائص آمنة اختيارية.
  </Card>

  <Card title="metric" icon="chart-line">
    قياس رقمي واحد له اسم ونوع وقيمة ووحدة ونمط زمني (temporality).
  </Card>

  <Card title="الإصدار والبيئة" icon="tags">
    نسخة الشيفرة والبيئة المرفقتان بالأحداث اللاحقة في نطاق الـ SDK نفسه.
  </Card>
</CardGroup>

## <span id="severity-values">قيم الخطورة</span>

استخدم `info` أو `warning` أو `error` أو `critical` للسجلات والمشكلات. يمكن لحزم
SDK وبيئات التشغيل إرسال أسماء بديلة مثل `trace` أو `debug` أو `warn` أو `fatal`.
ويحوّل LogBrew الأسماء البديلة المقبولة إلى القيم المعيارية.

## <span id="package-manager-installs">التثبيت عبر مدير الحزم</span>

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

| بيئة التشغيل | التثبيت |
| - | - |
| JavaScript | `npm install @logbrew/sdk` |
| المتصفح | `npm install @logbrew/sdk @logbrew/browser` |
| Node.js | `npm install @logbrew/sdk @logbrew/node` |
| Express | `npm install @logbrew/sdk @logbrew/node @logbrew/express` |
| Fastify | `npm install @logbrew/sdk @logbrew/node @logbrew/fastify` |
| NestJS | `npm install @logbrew/sdk @logbrew/node @logbrew/nestjs` |
| React | `npm install @logbrew/sdk @logbrew/browser @logbrew/react` |
| Next.js | `npm install @logbrew/sdk @logbrew/node @logbrew/next` |
| Angular | `npm install @logbrew/sdk @logbrew/angular` |
| Vue | `npm install @logbrew/sdk @logbrew/vue` |
| Svelte | `npm install @logbrew/sdk @logbrew/browser @logbrew/svelte` |
| [React Native](/ar/guides/react-native) | `npm install @logbrew/sdk @logbrew/react-native` |
| Python | `python3 -m pip install logbrew-sdk` |
| FastAPI | `python3 -m pip install logbrew-fastapi` |
| Flask | `python3 -m pip install "logbrew-flask>=0.1.5,<0.2"` |
| Django | `python3 -m pip install logbrew-django` |
| Swift / Apple | أضف `https://github.com/LogBrewCo/sdk.git` عبر SwiftPM. |
| PHP | `composer require logbrew/sdk:^0.1.1` |
| Ruby | `gem install logbrew-sdk` |
| Go | `go get github.com/LogBrewCo/sdk/go/logbrew@latest` |
| Rust | `cargo add logbrew` |
| Java / Spring | أضف `co.logbrew:logbrew-sdk:0.1.10` من Maven Central. |
| .NET | `dotnet add package LogBrew --version 0.1.7` |
| ASP.NET Core | `dotnet add package LogBrew.AspNetCore --version 0.1.2` |
| C++ / CMake | حدّد النسخة `cpp/logbrew-cpp/v0.2.3` باستخدام `FetchContent` في CMake. |

### <span id="nodejs-request-tracing">تتبّع الطلبات في Node.js</span>

لربط التتبّع بجذر الطلب، استخدم `@logbrew/sdk` بالنسخة 0.1.16 أو أحدث،
و`@logbrew/node` بالنسخة 0.1.11 أو أحدث.

يتطلب Express الحزمة `@logbrew/express` بالنسخة 0.1.5 أو أحدث. ويتطلب Fastify
وNestJS حزمة LogBrew الخاصة بكل منهما بالنسخة 0.1.6 أو أحدث.

تنشئ عمليات الدمج هذه Span طلب واحدًا أو تكمله. يستخدم اسم الـ Span قالب المسار
المطابق. وترث السجلات والمشكلات والإجراءات والمقاييس داخل الطلب سياق التتبّع
والـ Span الخاص به. الحزمة الأحدث لا تضيف سياقًا إلى الأحداث التي أُرسلت قبل الترقية.

لا يلتقط دمج الطلبات الافتراضي نص الطلب أو الاستجابة، ولا سلاسل الاستعلام، ولا
الترويسات العشوائية، ولا قيم `traceparent` الخام.

### <span id="aspnet-core">ASP.NET Core</span>

تكتشف CLI بالنسخة v0.1.55 أو أحدث مشاريع .NET 10 التي تستخدم
`Microsoft.NET.Sdk.Web`. اعرض خطة الإعداد مسبقًا من جذر المشروع. هذا الأمر لا
يغيّر ملفاتك:

```bash theme={null}
logbrew setup --json
```

تثبّت الخطة المنشورة دمج المضيف:

```bash theme={null}
dotnet add package LogBrew.AspNetCore --version 0.1.2
```

اضبط `LOGBREW_SERVER_API_KEY` و`LOGBREW_SERVICE_NAME`
و`LOGBREW_ENVIRONMENT` و`LOGBREW_RELEASE` خارج نظام إدارة الشيفرة المصدرية. سجّل
LogBrew لدى المضيف، وضع الـ middleware الخاص به بعد التوجيه (routing):

```csharp theme={null}
using LogBrew;

var builder = WebApplication.CreateBuilder(args);
builder.AddLogBrew();

var app = builder.Build();
app.UseRouting();
app.UseLogBrew();
app.MapGet("/", () => "ok");
app.Run();
```

من دون `LOGBREW_SERVER_API_KEY`، لا يفعل استدعاءا التسجيل شيئًا، وهما آمنان. تحدد
[حزمة NuGet لـ ASP.NET Core](https://www.nuget.org/packages/LogBrew.AspNetCore/0.1.2)
دمج المضيف المنشور. وتغطي إرشادات الحزمة العامة دورة حياة المضيف، والتقاط الطلبات،
والتقاط المشكلات، وحدود الخصوصية، والتعافي.

### <span id="java-with-maven-or-gradle">Java مع Maven أو Gradle</span>

تكتشف CLI بالنسخة v0.1.54 أو أحدث الملفات `pom.xml` و`build.gradle`
و`build.gradle.kts`. اعرض خطة الإعداد مسبقًا من جذر المشروع. هذا الأمر لا يغيّر
ملفاتك:

```bash theme={null}
logbrew setup --json
```

مع Maven، أضف الحزمة المنشورة:

```xml theme={null}
<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.10</version>
</dependency>
```

مع Gradle Kotlin DSL، أضف ملف البناء نفسه من Maven Central:

```kotlin theme={null}
implementation("co.logbrew:logbrew-sdk:0.1.10")
```

استخدم Java 11 أو أحدث.

يمكن لتطبيقات Spring Boot 3 و4 أن توفّر bean من نوع `LogBrewClient` يملكه التطبيق.
ويفعّل هذا الـ bean عمليات دمج اختيارية للطلبات والاستثناءات وعميل HTTP وJDBC
والذاكرة المؤقتة.

التقاط Spring Kafka لا يعمل إلا إذا فعّلته صراحةً باستخدام
`logbrew.kafka.enabled=true`. ويستخدم اعتمادية Spring Kafka وbean العميل الموجودين
في التطبيق.

يحدد [ملف بناء Java SDK على Maven Central](https://central.sonatype.com/artifact/co.logbrew/logbrew-sdk/0.1.10)
الحزمة المنشورة. وتغطي إرشاداتها العامة التسليم المحدود عبر HTTP، والإيقاف،
والتسجيل، وإعدادات Spring، والربط مع Kafka، وحدود الخصوصية.

### <span id="c-with-cmake">C++ مع CMake</span>

يتطلب C++ SDK معيار C++17 وCMake 3.16 أو أحدث. تكتشف CLI بالنسخة v0.1.39 أو أحدث
ملف `CMakeLists.txt` في الجذر. شغّل `logbrew setup --json` لعرض خطة الإعداد هذه
مسبقًا دون تغيير ملفاتك:

```cmake theme={null}
include(FetchContent)
FetchContent_Declare(
  logbrew
  GIT_REPOSITORY https://github.com/LogBrewCo/sdk.git
  GIT_TAG cpp/logbrew-cpp/v0.2.3
  GIT_SHALLOW TRUE
  SOURCE_SUBDIR cpp/logbrew-cpp
)
FetchContent_MakeAvailable(logbrew)

target_link_libraries(your_app PRIVATE LogBrew::LogBrew)
```

الهدف الأساسي (core target) بلا اعتماديات. لإرسال الدفعات عبر ناقل libcurl
الاختياري، استبدل استدعاء `FetchContent_MakeAvailable` الأخير وربط الهدف السابق بما
يلي:

```cmake theme={null}
set(LOGBREW_BUILD_HTTP_TRANSPORT ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(logbrew)
target_link_libraries(your_app PRIVATE LogBrew::HttpTransport)
```

اضبط إعدادات التطبيق. ثم ابنِه لاختبار نسخة الـ SDK المختارة:

```bash theme={null}
cmake -S . -B build &&
cmake --build build
```

في عمليات البناء التي لا تستطيع جلب المستودع الموحّد للـ SDK، استخدم الملف
`logbrew-cpp-0.2.3.tar.gz` المخصص لـ C++ من
[إصدار C++ 0.2.3](https://github.com/LogBrewCo/sdk/releases/tag/cpp/logbrew-cpp/v0.2.3).
تدعم الحزمة بعد فك ضغطها `cmake --install`
و`find_package(LogBrew 0.2.3 CONFIG REQUIRED)`. وتغطي إرشادات الحزمة السياق المحدد
الأنواع، وأدلة المشكلات، وأحداث الـ Span، والمقاييس، والإجراءات، والتسليم عبر HTTP.

### <span id="javascript-source-maps">خرائط المصدر في JavaScript</span>

لعمليات بناء Vite، اتبع [خرائط المصدر لـ JavaScript](/ar/guides/source-maps).
تغطي الإرشادات المكوّن الإضافي، ومفتاح ملفات البناء (artifact)، وفحوص الرفع، ومشكلة
جديدة بمواضع المصدر الأصلية.

### <span id="apple-flask-and-react-native">Apple وFlask وReact Native</span>

استخدم منتج Swift المسمى `LogBrew` لبيانات القياس. أضف `LogBrewCrash` فقط لالتقاط
أعطال Apple وحالات التجمّد. اتبع
[أعطال Apple والتجمّد](/ar/guides/apple-crashes-and-hangs) لرفع ملفات dSYM
وتحليل الرموز المستضاف.

مع Flask، اتبع [إعداد Flask](/ar/guides/flask).

مع React Native وExpo، اتبع [React Native](/ar/guides/react-native). تغطي الإرشادات
مفتاح المشروع، وسجلًا تجريبيًا آمنًا، وأخطاء التسليم، وإعدادات Expo Metro لخرائط
المصدر في الإنتاج.

## <span id="javascript-queue-tracing">تتبّع الطوابير في JavaScript</span>

عمليات دمج الطوابير في Node حزم npm مستقلة. ثبّت حزم LogBrew الأساسية
لـ JavaScript، وحزمة الدمج، وعميل الطابور أو الوسيط (broker) الذي يستخدمه تطبيقك
بالفعل.

| الطابور أو الوسيط | التثبيت |
| - | - |
| BullMQ | `npm install @logbrew/sdk @logbrew/node @logbrew/bullmq bullmq` |
| KafkaJS | `npm install @logbrew/sdk @logbrew/node @logbrew/kafkajs kafkajs` |
| RabbitMQ / amqplib | `npm install @logbrew/sdk @logbrew/node @logbrew/amqplib amqplib` |
| Amazon SQS | `npm install @logbrew/sdk @logbrew/node @logbrew/aws-sqs @aws-sdk/client-sqs` |

استخدم هذه الحزم لربط التتبّع بشكل صريح يملكه التطبيق حول استدعاءات الطابور التي
تختارها. لا يملك LogBrew اتصالك بالوسيط، ولا ينشئ طوابير، ولا يعدّل كل العملاء
تلقائيًا على مستوى التطبيق كله.

<Warning>
  أبقِ محتوى رسائل الطابور، والترويسات العشوائية للرسائل، وعناوين URL الخاصة
  بالوسيط، وقيم Bearer الخاصة بالجلسة أو الحساب خارج إعدادات الـ SDK. استخدم إعدادات
  الاستيعاب الخاصة بالمشروع على جهة الخادم من LogBrew.
</Warning>

## <span id="required-envelope-fields">الغلاف الأصلي المباشر</span>

استخدم `POST /api/telemetry/ingest` فقط لعميل مخصص لا تدعمه أي حزمة LogBrew SDK
عامة. تستخدم حزم SDK العامة تنسيق الدفعات الخاص بها، ونقطة النهاية هذه لا تقبل ذلك
التنسيق.

أرسل من 1 إلى 512 عنصرًا في الغلاف الأصلي الواحد. تشترك كل عناصر الغلاف الواحد
في المشروع والخدمة والإصدار والبيئة وسياق التتبّع الاختياري.

| الحقل | مطلوب | ملاحظات |
| - | - | - |
| `project_id` | نعم | UUID لمشروع LogBrew. يجب أن يطابق مشروع مفتاح الاستيعاب. |
| `environment` | نعم | بيئة النشر. 64 حرفًا أو أقل، بلا مسافات بيضاء أو `/` أو `\`. القيمة `None` مرفوضة. |
| `release` | نعم | نسخة الشيفرة. 200 حرف أو أقل، بلا `/` أو `\` أو علامات جدولة أو أسطر جديدة. لا يمكن أن تكون `.` أو `..`. |
| `service_name` | نعم | اسم منطقي للخدمة، مثل `checkout-api`. يجب ألا يكون فارغًا. |
| `sdk_name` | نعم | معرّف الـ SDK أو العميل المخصص. |
| `sdk_version` | نعم | نسخة الـ SDK أو العميل المخصص. |
| `items` | نعم | من 1 إلى 512 عنصرًا من نوع `log` أو `trace_span` أو `issue` أو `action`. |
| `trace_id` | لا | معرّف تتبّع تشترك فيه عناصر الغلاف المرتبطة. مطلوب عندما يحتوي عنصر على `span_id`. |

### <span id="item-fields">حقول العناصر</span>

لكل عنصر `type` وكائن `data`. يستخدم عنصر السجل `level`، ويستخدم عنصر المشكلة
`severity`. ويقبل كلاهما القيم الواردة في [قيم الخطورة](/ar/concepts/telemetry#severity-values).

| حقل العنصر | ينطبق على | ملاحظات |
| - | - | - |
| `id` | كل العناصر | معرّف حدث اختياري من العميل. من 1 إلى 200 حرف، وفريد داخل الغلاف. |
| `span_id` | `log`، `issue`، `action` | اختياري. 16 حرفًا ست عشريًا، ليست كلها أصفارًا. يجب أن يحتوي الغلاف على `trace_id`. |
| `name` | `action` | مطلوب. 64 بايت UTF-8 أو أقل. يجب ألا يبدأ بـ `$`، وألا يبدأ أو ينتهي بمسافة بيضاء، وألا يحتوي على أحرف تحكم أو أحرف تنسيق غير مرئية. |

أرسل `id` مع كل عنصر عندما يستطيع عميلك إعادة المحاولة. عندما تعيد محاولةٌ إرسال
عنصر مقبول مرة أخرى بالقيمة `id` نفسها والمحتوى نفسه، لا يخزّنه LogBrew مرة ثانية.
وتعدّ الاستجابة هذا العنصر ضمن `already_accepted`.

### <span id="example-request">مثال على الطلب</span>

احفظ JSON التالي باسم `telemetry-envelope.json`. استبدل معرّف المشروع في المثال
بمعرّف المشروع الدقيق لمفتاح الاستيعاب. اضبط الطوابع الزمنية على الوقت الحالي
بتوقيت UTC للحدث التجريبي. واستخدم قيم الخدمة والإصدار الخاصة بك.

```json telemetry-envelope.json theme={null}
{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "environment": "production",
  "release": "api@1.2.3",
  "service_name": "checkout-api",
  "sdk_name": "custom-native-client",
  "sdk_version": "1.0.0",
  "items": [
    {
      "type": "log",
      "data": {
        "id": "evt_example_log_0001",
        "level": "warning",
        "message": "checkout retry scheduled",
        "source": "runtime",
        "attributes": { "route": "/checkout" },
        "occurred_at": "2026-06-01T12:00:00Z"
      }
    },
    {
      "type": "action",
      "data": {
        "id": "evt_example_action_0001",
        "name": "checkout_failed",
        "distinct_id": "user_123",
        "session_id": "session_456",
        "occurred_at": "2026-06-01T12:00:00Z",
        "properties": { "cart_total": 4200 }
      }
    }
  ]
}
```

حمّل قيمة الاستيعاب الخاصة بالمشروع في `LOGBREW_INGEST_BEARER` من خلال إعداداتك
المحمية. لا تطبعها، ولا تستخدم بيانات اعتماد الحساب. يرسل الأمر التالي الملف مرة
واحدة، ويتطلب curl 7.76.0 أو أحدث:

```bash theme={null}
: "${LOGBREW_INGEST_BEARER:?load the project-scoped ingest key}" &&
curl --fail-with-body --silent --show-error \
  "https://api.logbrew.co/api/telemetry/ingest" \
  -H "Authorization: Bearer $LOGBREW_INGEST_BEARER" \
  -H "Content-Type: application/json" \
  --data-binary @telemetry-envelope.json \
  --write-out '\nHTTP %{http_code}\n'
```

اقرأ حالة HTTP ونص الاستجابة. يحافظ `--fail-with-body` على نص الخطأ، ويُرجع حالة خروج
غير صفرية عند أخطاء HTTP. فشل الشبكة أو انتهاء المهلة لا يخبرك هل قبل LogBrew الطلب
أم لا. لا ترسل الملف نفسه مرة أخرى إلا إذا كانت لعناصره قيم `id`. ومن دون قيم
`id`، قد يؤدي الإرسال الثاني إلى تخزين العناصر مرتين.

### <span id="response">الاستجابة</span>

يُرجع الطلب الناجح `200` مع أعداد العناصر الجديدة حسب كل تدفق. ويعدّ
`already_accepted` العناصر التي سلّمها طلب سابق بالفعل.

```json theme={null}
{
  "issues": 0,
  "logs": 1,
  "trace_spans": 0,
  "actions": 1,
  "already_accepted": 0,
  "next": "review accepted telemetry in logs, issues, traces, actions, or live feed",
  "next_action": {
    "code": "review_ingested_telemetry",
    "target": "telemetry_reads"
  }
}
```

### <span id="errors">الأخطاء</span>

مفتاح الاستيعاب غير الصالح أو المُبطل يُرجع `401`. والمفتاح الخاص بمشروع آخر يُرجع
`401` أيضًا:

```json theme={null}
{
  "error": "Invalid ingest key",
  "code": "ingest_key_invalid",
  "next": "create a project-scoped ingest key, then retry ingestion with that key",
  "next_action": {
    "code": "configure_ingest_key",
    "target": "project_ingest_key"
  }
}
```

استخدم مفتاح استيعاب خاصًا بالمشروع. لا تستبدله ببيانات اعتماد الحساب. لا يستطيع
مفتاح ملفات البناء (artifact) إرسال بيانات القياس.

الغلاف الذي يخالف قاعدة حقل يُرجع `422` مع الرمز
`validation_failed`. يذكر الحقل `error` القاعدة. ويخبرك الحقل `next` بكيفية إصلاح
الطلب. مثلًا، `"items": []` يُرجع:

```json theme={null}
{
  "error": "native telemetry envelope cannot be empty",
  "code": "validation_failed",
  "next": "send at least one native telemetry item",
  "next_action": {
    "code": "fix_request",
    "target": "request"
  }
}
```

لا ترسل غلافًا عندما لا توجد أحداث. الغلاف الذي يحتوي على أكثر من
512 عنصرًا يُرجع `422` مع الخطأ
`native telemetry envelope exceeds the item limit`. قسّمه إلى دفعات من
512 عنصرًا أو أقل. واحتفظ بالمشروع والسياق المشترك في كل دفعة.

لحدود الاستخدام وحدود المعدّل وأعطال الخدمة، اتبع `code` المُرجَع في
[أخطاء API](/ar/reference/api-errors).

<Tip>
  اضبط الإصدار والبيئة في إعداد الـ SDK. أنشئ سياق التتبّع أو أكمله لكل عملية. لا
  تُعِد استخدام معرّف تتبّع واحد لأعمال لا علاقة بينها.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.