> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> بايثون لـ ClickStack - حزمة ClickHouse للرصد

# بايثون

export const ClickStackIntegrates = ({signals = []}) => {
  const list = Array.isArray(signals) ? signals : String(signals).split(",");
  const supported = list.map(s => String(s).trim().toLowerCase());
  const pillStyle = {
    display: "inline-flex",
    alignItems: "center",
    padding: "0.125rem 0.625rem",
    borderRadius: "9999px",
    fontSize: "0.8125rem",
    fontWeight: 500,
    lineHeight: 1.6,
    color: "#161517",
    backgroundColor: "#faff69",
    border: "1px solid rgba(0, 0, 0, .1)",
    marginRight: "0.5rem"
  };
  return <div style={{
    margin: "0 0 1.25rem"
  }}>
      <span style={{
    marginRight: "0.5rem"
  }}>يتكامل هذا الدليل مع:</span>
      {supported.includes("logs") && <span style={pillStyle}>السجلات</span>}
      {supported.includes("metrics") && <span style={pillStyle}>المقاييس</span>}
      {supported.includes("traces") && <span style={pillStyle}>التتبعات</span>}
    </div>;
};

تستخدم ClickStack معيار OpenTelemetry لجمع بيانات القياس عن بُعد (السجلات والتتبعات). ويتم إنشاء التتبعات تلقائيًا عبر التتبّع التلقائي، لذلك لا حاجة إلى التضمين اليدوي للاستفادة من التتبّع.

<ClickStackIntegrates signals={['logs', 'metrics', 'traces']} />

<h2 id="getting-started">
  البدء
</h2>

<h3 id="install-clickstack-otel-instrumentation-package">
  تثبيت حزمة التضمين لـ ClickStack OpenTelemetry
</h3>

استخدم الأمر التالي لتثبيت [حزمة التضمين الخاصة بـ ClickStack OpenTelemetry](https://pypi.org/project/hyperdx-opentelemetry/).

```shell theme={null}
pip install hyperdx-opentelemetry
```

ثبّت مكتبات OpenTelemetry الخاصة بالتتبّع التلقائي للحزم التي يستخدمها تطبيق بايثون. نوصي باستخدام أداة
`opentelemetry-bootstrap` المرفقة مع OpenTelemetry Python SDK لفحص حزم تطبيقك وإنشاء قائمة بالمكتبات المتاحة.

```shell theme={null}
opentelemetry-bootstrap -a install
```

<h3 id="configure-environment-variables">
  تكوين متغيرات البيئة
</h3>

بعد ذلك، ستحتاج إلى تكوين متغيرات البيئة التالية في الـ shell لديك لإرسال بيانات القياس عن بُعد إلى ClickStack عبر OpenTelemetry Collector:

<Tabs>
  <Tab title="Managed ClickStack">
    ```shell theme={null}
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> 
    ```
  </Tab>

  <Tab title="ClickStack Open Source">
    ```shell theme={null}
    export HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' \
    OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' \
    OTEL_EXPORTER_OTLP_ENDPOINT=<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT> 
    ```
  </Tab>
</Tabs>

*يُستخدم متغير البيئة `OTEL_SERVICE_NAME` للتعرّف على خدمتك في تطبيق HyperDX، ويمكن أن يكون أي اسم تريده.*

<h3 id="run-the-application-with-otel-python-agent">
  شغّل التطبيق باستخدام وكيل OpenTelemetry لبايثون
</h3>

يمكنك الآن تشغيل التطبيق باستخدام وكيل OpenTelemetry لبايثون (`opentelemetry-instrument`).

```shell theme={null}
opentelemetry-instrument python app.py
```

<h4 id="using-uvicorn-gunicorn-uwsgi">
  إذا كنت تستخدم `Gunicorn` أو `uWSGI` أو `uvicorn`
</h4>

في هذه الحالة، سيتطلب وكيل OpenTelemetry لبايثون بعض التغييرات الإضافية لكي يعمل.

لتهيئة OpenTelemetry لخوادم التطبيقات التي تستخدم وضع خادم الويب `pre-fork`، تأكد من استدعاء الدالة `configure_opentelemetry` داخل hook ما بعد التفرّع.

<Tabs>
  <Tab title="Gunicorn">
    ```python theme={null}
    from hyperdx.opentelemetry import configure_opentelemetry

    def post_fork(server, worker):
        configure_opentelemetry()
    ```
  </Tab>

  <Tab title="uWSGI">
    ```python theme={null}
    from hyperdx.opentelemetry import configure_opentelemetry
    from uwsgidecorators import postfork

    @postfork
    def init_tracing():
        configure_opentelemetry()
    ```
  </Tab>

  <Tab title="uvicorn">
    لا يعمل OpenTelemetry [حاليًا](https://github.com/open-telemetry/opentelemetry-python-contrib/issues/385) مع `uvicorn` عند تشغيله باستخدام
    الخيار `--reload` أو مع عدة workers (`--workers`). نوصي بتعطيل هذين الخيارين أثناء الاختبار، أو باستخدام Gunicorn.
  </Tab>
</Tabs>

<h2 id="advanced-configuration">
  الإعدادات المتقدمة
</h2>

<h4 id="network-capture">
  التقاط الشبكة
</h4>

من خلال تمكين ميزات التقاط الشبكة، يصبح بإمكان المطورين تصحيح أخطاء
رؤوس طلبات HTTP وحمولات المتن بفعالية. ويمكن تحقيق ذلك
ببساطة عبر ضبط العلامة `HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE` على 1.

```shell theme={null}
export HYPERDX_ENABLE_ADVANCED_NETWORK_CAPTURE=1
```

<h2 id="troubleshooting">
  استكشاف الأخطاء وإصلاحها
</h2>

<h3 id="logs-not-appearing-due-to-log-level">
  عدم ظهور السجلات بسبب مستوى التسجيل
</h3>

يستخدم معالج logging في OpenTelemetry، افتراضيًا، المستوى `logging.NOTSET`، والذي
يُعيَّن افتراضيًا إلى مستوى WARNING. يمكنك تحديد مستوى logging عند إنشاء
`logger`:

```python theme={null}
import logging

logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG)
```

<h3 id="exporting-to-the-console">
  التصدير إلى وحدة التحكم
</h3>

تعرض حزمة OpenTelemetry SDK الخاصة بـ بايثون عادةً الأخطاء في وحدة التحكم عند
حدوثها. ومع ذلك، إذا لم تواجه أي أخطاء ولكن لاحظت أن بياناتك لا
تظهر في HyperDX كما هو متوقع، فيمكنك تفعيل وضع Debug.
عند تفعيل وضع Debug، ستُطبع جميع بيانات القياس عن بُعد في وحدة التحكم،
مما يتيح لك التحقق مما إذا كان تطبيقك مهيأً بشكل صحيح لإرسال
البيانات المتوقعة.

```shell theme={null}
export DEBUG=true
```

اطّلع هنا على مزيد من المعلومات حول التضمين في OpenTelemetry لبايثون:
[https://opentelemetry.io/docs/instrumentation/python/manual/](https://opentelemetry.io/docs/instrumentation/python/manual/)