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

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

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

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

الإشارات والسياق المشترك

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

log

رسالة منظّمة لها خطورة ومصدر ووقت وسياق آمن.

trace_span

عملية واحدة محددة التوقيت، مرتبطة بتتبّعها عبر معرّفَي التتبّع والـ Span.

issue

عطل ملتقَط، وخطورته، وتفاصيل الخطأ التي أرسلها التطبيق.

action

إجراء في تطبيقك، مع كيان وجلسة وخصائص آمنة اختيارية.

metric

قياس رقمي واحد له اسم ونوع وقيمة ووحدة ونمط زمني (temporality).

الإصدار والبيئة

نسخة الشيفرة والبيئة المرفقتان بالأحداث اللاحقة في نطاق الـ SDK نفسه.

قيم الخطورة

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

التثبيت عبر مدير الحزم

ثبّت حزمة 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	`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.9` من 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.

تتبّع الطلبات في Node.js

لربط التتبّع بجذر الطلب، استخدم @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 الخام.

ASP.NET Core

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

logbrew setup --json

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

dotnet add package LogBrew.AspNetCore --version 0.1.2

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

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 دمج المضيف المنشور. وتغطي إرشادات الحزمة العامة دورة حياة المضيف، والتقاط الطلبات، والتقاط المشكلات، وحدود الخصوصية، والتعافي.

Java مع Maven أو Gradle

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

logbrew setup --json

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

<dependency>
  <groupId>co.logbrew</groupId>
  <artifactId>logbrew-sdk</artifactId>
  <version>0.1.9</version>
</dependency>

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

implementation("co.logbrew:logbrew-sdk:0.1.9")

استخدم Java 11 أو أحدث. يمكن لتطبيقات Spring Boot 3 و4 أن توفّر bean من نوع LogBrewClient يملكه التطبيق. ويفعّل هذا الـ bean عمليات دمج اختيارية للطلبات والاستثناءات وعميل HTTP وJDBC والذاكرة المؤقتة. التقاط Spring Kafka لا يعمل إلا إذا فعّلته صراحةً باستخدام logbrew.kafka.enabled=true. ويستخدم اعتمادية Spring Kafka وbean العميل الموجودين في التطبيق. يحدد ملف بناء Java SDK على Maven Central الحزمة المنشورة. وتغطي إرشاداتها العامة التسليم المحدود عبر HTTP، والإيقاف، والتسجيل، وإعدادات Spring، والربط مع Kafka، وحدود الخصوصية.

C++ مع CMake

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

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 الأخير وربط الهدف السابق بما يلي:

set(LOGBREW_BUILD_HTTP_TRANSPORT ON CACHE BOOL "" FORCE)
FetchContent_MakeAvailable(logbrew)
target_link_libraries(your_app PRIVATE LogBrew::HttpTransport)

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

cmake -S . -B build &&
cmake --build build

في عمليات البناء التي لا تستطيع جلب المستودع الموحّد للـ SDK، استخدم الملف logbrew-cpp-0.2.3.tar.gz المخصص لـ C++ من إصدار C++ 0.2.3. تدعم الحزمة بعد فك ضغطها cmake --install وfind_package(LogBrew 0.2.3 CONFIG REQUIRED). وتغطي إرشادات الحزمة السياق المحدد الأنواع، وأدلة المشكلات، وأحداث الـ Span، والمقاييس، والإجراءات، والتسليم عبر HTTP.

خرائط المصدر في JavaScript

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

Apple وFlask وReact Native

استخدم منتج Swift المسمى LogBrew لبيانات القياس. أضف LogBrewCrash فقط لالتقاط أعطال Apple وحالات التجمّد. اتبع أعطال Apple والتجمّد لرفع ملفات dSYM وتحليل الرموز المستضاف. مع Flask، اتبع إعداد Flask. مع React Native وExpo، اتبع React Native. تغطي الإرشادات مفتاح المشروع، وسجلًا تجريبيًا آمنًا، وأخطاء التسليم، وإعدادات Expo Metro لخرائط المصدر في الإنتاج.

تتبّع الطوابير في JavaScript

عمليات دمج الطوابير في 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 اتصالك بالوسيط، ولا ينشئ طوابير، ولا يعدّل كل العملاء تلقائيًا على مستوى التطبيق كله.

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

الغلاف الأصلي المباشر

استخدم 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`.

حقول العناصر

لكل عنصر type وكائن data. يستخدم عنصر السجل level، ويستخدم عنصر المشكلة severity. ويقبل كلاهما القيم الواردة في قيم الخطورة.

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

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

مثال على الطلب

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

telemetry-envelope.json

{
  "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 أو أحدث:

: "${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، قد يؤدي الإرسال الثاني إلى تخزين العناصر مرتين.

الاستجابة

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

{
  "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"
  }
}

الأخطاء

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

{
  "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": [] يُرجع:

{
  "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.

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

البدء

المفاهيم

التثبيت والإرسال

التحقيق

CLI والوكلاء

الدعم

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

الإشارات والسياق المشترك

log

trace_span

issue

action

metric

الإصدار والبيئة

قيم الخطورة

التثبيت عبر مدير الحزم

تتبّع الطلبات في Node.js

ASP.NET Core

Java مع Maven أو Gradle

C++ مع CMake

خرائط المصدر في JavaScript

Apple وFlask وReact Native

تتبّع الطوابير في JavaScript

الغلاف الأصلي المباشر

حقول العناصر

مثال على الطلب

الاستجابة

الأخطاء

​الإشارات والسياق المشترك

log

trace_span

issue

action

metric

الإصدار والبيئة

​قيم الخطورة

​التثبيت عبر مدير الحزم

​تتبّع الطلبات في Node.js

​ASP.NET Core

​Java مع Maven أو Gradle

​C++ مع CMake

​خرائط المصدر في JavaScript

​Apple وFlask وReact Native

​تتبّع الطوابير في JavaScript

​الغلاف الأصلي المباشر

​حقول العناصر

​مثال على الطلب

​الاستجابة

​الأخطاء

الإشارات والسياق المشترك

قيم الخطورة

التثبيت عبر مدير الحزم

تتبّع الطلبات في Node.js

ASP.NET Core

Java مع Maven أو Gradle

C++ مع CMake

خرائط المصدر في JavaScript

Apple وFlask وReact Native

تتبّع الطوابير في JavaScript

الغلاف الأصلي المباشر

حقول العناصر

مثال على الطلب

الاستجابة

الأخطاء