---
title: "أعدّ سجلات FastAPI وعالج الأخطاء دون فقدان تتبّع المكدّس"
description: "لم يطبع FastAPI أي سجل info حتى ضبطنا التسجيل، ولم يطبع تتبّع المكدّس لخطأ 500 إلا uvicorn. إليك الإعداد ومعالجات الأخطاء وLogBrew، من اختبار على FastAPI 0.165."
canonical: "https://logbrew.co/ar/guides/fastapi-logging"
last_updated: "2026-11-21"
---

# أعدّ سجلات FastAPI وعالج الأخطاء دون فقدان تتبّع المكدّس

لم يطبع FastAPI أي سجل `info` حتى ضبطنا التسجيل، ولم يطبع تتبّع المكدّس لخطأ 500 إلا uvicorn. إليك الإعداد ومعالجات الأخطاء وLogBrew، من اختبار على FastAPI 0.165.

اختُبر في 21 نوفمبر 2026 باستخدام Python 3.13.5 وFastAPI 0.165.0 وuvicorn 0.54.0 وlogbrew-sdk 0.1.29 وlogbrew-fastapi 0.1.14 وlogbrew CLI 0.1.96

بقلم [Furkan Erday](https://github.com/furkanerday). Furkan Erday مؤسس LogBrew، ويبني LogBrew كل يوم باستخدام Claude Code وCodex.

Canonical: https://logbrew.co/ar/guides/fastapi-logging

## ما يطبعه FastAPI دون إعداد، وما يصل إلى LogBrew

| الحدث | المطبوع دون إعداد | مشكلة أو سجل في LogBrew |
| --- | --- | --- |
| `logger.debug()` | أُسقط | أُسقط عند `INFO` |
| `logger.info()` | أُسقط | سجل `info` |
| `logger.warning()` | الرسالة فقط | سجل `warning` |
| `ValueError` في مسار | تتبّع المكدّس من uvicorn | مشكلة |
| قيمة مسار ليست رقمًا، 422 | سطر الوصول فقط | Span، دون مشكلة |
| `HTTPException`، 404 | سطر الوصول فقط | Span، دون مشكلة |

6 أحداث في FastAPI 0.165.0 مع uvicorn 0.54.0، ثم الأحداث نفسها مع `basicConfig()` وlogbrew-fastapi 0.1.14.

## سجّل من تطبيق FastAPI

### شاهد ما يطبعه FastAPI دون إعداد

في تطبيقنا مسجّل واحد اسمه `taproom` و3 مسارات. شغّلناه عبر `uvicorn main:app`. يضبط uvicorn مسجّلاته فقط، لذلك طبع Python المستوى `warning` وما فوقه نصًا عاديًا، وأسقط `debug` و`info`.

```bash
import logging

from fastapi import FastAPI, HTTPException

app = FastAPI()
logger = logging.getLogger("taproom")


@app.get("/taps/{tap}")
def pour(tap: str):
    logger.debug("keg pressure read")
    logger.info("tap %s opened", tap)
    logger.warning("keg below 10%")
    logger.error("keg empty")
    logger.critical("cooler offline")
    return {"tap": tap}


@app.get("/kegs/{keg_id}")
def keg(keg_id: int):
    raise ValueError(f"keg {keg_id} is empty")


@app.get("/missing")
def missing():
    raise HTTPException(status_code=404, detail="no such tap")
```

المخرجات

```text
keg below 10%
keg empty
cooler offline
INFO:     127.0.0.1:51421 - "GET /taps/ipa HTTP/1.1" 200 OK
```

### استدعِ basicConfig() قبل إنشاء التطبيق

تمنح `logging.basicConfig()` المسجّل الجذري مستوى وتنسيقًا. صارت أسطر `taproom` تعرض مستواها، وظهر `info`. ويحتفظ uvicorn بتنسيقه الخاص.

```bash
import logging
import os

from fastapi import FastAPI, HTTPException

logging.basicConfig(
    level=os.environ.get("LOG_LEVEL", "INFO"),
    format="%(levelname)s %(name)s %(message)s",
)

app = FastAPI()
logger = logging.getLogger("taproom")
```

المخرجات

```text
INFO taproom tap ipa opened
WARNING taproom keg below 10%
ERROR taproom keg empty
CRITICAL taproom cooler offline
INFO:     127.0.0.1:51428 - "GET /taps/ipa HTTP/1.1" 200 OK
```

### اقرأ المستوى من متغيّر البيئة

يقرأ استدعاء `basicConfig()` أعلاه القيمة `LOG_LEVEL`. شغّل uvicorn مع `LOG_LEVEL=DEBUG` فيظهر سطر `debug` دون تغيير الشيفرة.

```bash
LOG_LEVEL=DEBUG uvicorn main:app
```

المخرجات

```text
DEBUG taproom keg pressure read
INFO taproom tap ipa opened
WARNING taproom keg below 10%
ERROR taproom keg empty
CRITICAL taproom cooler offline
INFO:     127.0.0.1:51442 - "GET /taps/ipa HTTP/1.1" 200 OK
```

## عالج الأخطاء في FastAPI

### شاهد ما يطبعه استثناء غير معالَج

تلقّى العميل `Internal Server Error` بالحالة 500. وطبع uvicorn العبارة `Exception in ASGI application` وتتبّع المكدّس. أعاد المسار `/kegs/abc` الحالة 422 مع قائمة `detail`، وأعاد `HTTPException` قيمة `detail` الخاصة به مع 404. لم يطبع أيّ منهما تتبّعًا للمكدّس. حذفنا 27 إطارًا من uvicorn وStarlette وFastAPI.

```bash
curl localhost:8000/kegs/7
curl localhost:8000/kegs/abc
curl localhost:8000/missing
```

المخرجات

```text
INFO:     127.0.0.1:51422 - "GET /kegs/7 HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  …
  File "main.py", line 21, in keg
    raise ValueError(f"keg {keg_id} is empty")
ValueError: keg 7 is empty
INFO:     127.0.0.1:51423 - "GET /kegs/abc HTTP/1.1" 422 Unprocessable Content
INFO:     127.0.0.1:51424 - "GET /missing HTTP/1.1" 404 Not Found
```

### أضف معالج استثناءات للنوع Exception

يسجّل المعالج الخطأ ويعيد JSON خاصًا بك، وتلقّى العميل `{"error":"internal"}`. ومع ذلك طبع uvicorn تتبّع المكدّس، لأن Starlette يرفع الاستثناء مرة أخرى بعد إرسال استجابتك. لذلك ظهر تتبّع المكدّس مرتين.

```bash
from fastapi import Request
from fastapi.responses import JSONResponse


@app.exception_handler(Exception)
async def on_error(request: Request, exc: Exception):
    logger.exception("request failed")
    return JSONResponse({"error": "internal"}, status_code=500)
```

المخرجات

```text
ERROR taproom request failed
Traceback (most recent call last):
  …
  File "main.py", line 34, in keg
    raise ValueError(f"keg {keg_id} is empty")
ValueError: keg 7 is empty
INFO:     127.0.0.1:51436 - "GET /kegs/7 HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  …
  File "main.py", line 34, in keg
    raise ValueError(f"keg {keg_id} is empty")
ValueError: keg 7 is empty
```

## أرسل سجلات FastAPI وأخطاءه إلى LogBrew

### ثبّت الحزمة

تثبّت `logbrew-fastapi` الحزمة `logbrew-sdk` أيضًا. استخدم مفتاح خادم من مشروعك في LogBrew.

```bash
python3 -m pip install logbrew-sdk logbrew-fastapi
```

### استدعِ init_logbrew() بعد إنشاء التطبيق

تسجّل `init_logbrew()` عنصر Span لكل طلب، وتسجّل كل خطأ غير معالَج على أنه مشكلة. ويرسل `logbrew.logging_handler` سجلات مسجّلك. أرسلنا إلى خادم LogBrew محلي، لذلك مرّرت نسختنا `transport` أيضًا.

```bash
import logging
import os

from fastapi import FastAPI, HTTPException
from logbrew_fastapi import init_logbrew

logging.basicConfig(
    level=os.environ.get("LOG_LEVEL", "INFO"),
    format="%(levelname)s %(name)s %(message)s",
)

app = FastAPI()
logbrew = init_logbrew(
    app, api_key=os.environ["LOGBREW_API_KEY"], service_name="taproom"
)
logger = logging.getLogger("taproom")
logger.addHandler(logbrew.logging_handler)
```

### اقرأ المشكلة والسجلات من جديد

أرسلنا الطلبات الأربعة نفسها مجددًا وقرأنا المشروع بمفتاح قراءة. أصبح خطأ 500 مشكلة واحدة تحمل اسم قالب المسار. تشترك سجلات `/taps/ipa` الأربعة في معرّف تتبّع واحد. لم يُنشئ 422 ولا 404 أي مشكلة.

```bash
logbrew issues --since 1h
logbrew read logs --since 1h
```

المخرجات

```text
Issues (1)
- b100cd3d-f932-57c7-8f23-38067f1c87d7 unresolved error priority=medium GET /kegs/{keg_id} failed occurrences=1 users=unknown last_seen=2026-11-21T06:44:18.663Z service=taproom trace=6b642297fc5d4259b1f17f2bf83b1abb assignee=unassigned [unversioned / production]
Logs (4)
- error keg empty service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
- warning keg below 10% service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
- critical cooler offline service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
- info tap ipa opened service=taproom trace=fcc0eaf7997f4e0796c0b76e0678b455 [unversioned / production]
```

### تحقّق مما تحفظه المشكلة

تحفظ المشكلة نوع الاستثناء والمسار و21 إطارًا من المكدّس، لكنها لا تحفظ الرسالة. يكتب LogBrew العبارة `Unhandled exception` مكانها.

```bash
logbrew issues --since 1h --json | jq '.[0].attributes | {
  message, exception,
  route: .metadata.routeTemplate,
  frames: (.stackFrames | length)
}'
```

المخرجات

```text
{
  "message": "Unhandled exception",
  "exception": {
    "mechanism": {
      "handled": false,
      "type": "fastapi.middleware"
    },
    "type": "ValueError"
  },
  "route": "/kegs/{keg_id}",
  "frames": 21
}
```

### احفظ الرسالة عبر معالج الاستثناءات

مع معالج الاستثناءات أعلاه، بقي LogBrew يسجّل المشكلة، وحفظ السجل `request failed` الرسالة التي تُسقطها المشكلة.

```bash
logbrew read logs --since 1h --severity error \
  --search "request failed" --json | jq '.[0] | {
  message,
  exceptionName: .attributes.metadata.exceptionName,
  exceptionMessage: .attributes.metadata.exceptionMessage
}'
```

المخرجات

```text
{
  "message": "request failed",
  "exceptionName": "ValueError",
  "exceptionMessage": "keg 7 is empty"
}
```

## ما رأيناه في الاختبار

شغّلنا تطبيق FastAPI 0.165.0 واحدًا مع uvicorn 0.54.0 على Python 3.13.5، واستدعينا كل مسار عبر curl، وقرأنا مخرجات الخادم. ثم أضفنا logbrew-fastapi 0.1.14 وقرأنا ما حفظه خادم LogBrew محلي.

طبع uvicorn تتبّع المكدّس لكل استثناء غير معالَج، بمعالج أو دونه. أما الأخطاء التي يحوّلها FastAPI إلى استجابة، مثل 422 أو `HTTPException`، فطبعت سطر الوصول فقط.

| الطلب | `status_code` | تتبّع المكدّس المطبوع | المشكلة في LogBrew |
| --- | --- | --- | --- |
| `/kegs/7` | `500` | نعم | نعم |
| `/kegs/abc` | `422` | لا | لا |
| `/missing` | `404` | لا | لا |

## مستويات السجل في FastAPI ومخرجات uvicorn

في Python خمسة مستويات، `DEBUG` و`INFO` و`WARNING` و`ERROR` و`CRITICAL`. دون إعداد، يُسقط المسجّل الجذري كل سجل أدنى من `WARNING`.

يطبع uvicorn أسطر الوصول والأخطاء بتنسيقه الخاص، ولم يغيّرها `basicConfig()`. يُبقي LogBrew المستويات `warning` و`error` و`critical` كما هي، ويحفظ `DEBUG` و`INFO` بالمستوى `info`.

|  | دون إعداد | `basicConfig()` | LogBrew |
| --- | --- | --- | --- |
| `logger.debug()` | لا | مع `LOG_LEVEL=DEBUG` | لا |
| `logger.info()` | لا | نعم | `info` |
| `logger.warning()` | نعم | نعم | `warning` |
| `logger.error()` | نعم | نعم | `error` |
| `logger.critical()` | نعم | نعم | `critical` |

## ما يسجّله LogBrew

تسجّل `init_logbrew()` عنصر Span واحدًا لكل طلب، وتسمّيه باسم قالب المسار، مثل `GET /kegs/{keg_id}`. ويضيف الاستثناء غير المعالَج مشكلة تحمل نوع الاستثناء والآلية `fastapi.middleware` و`handled: false` وإطارات المكدّس.

يحمل السجل المكتوب أثناء طلب معرّف التتبّع لذلك الطلب. أنشأ طلبا 422 و404 عناصر Span دون خطأ.

- `init_logbrew()`
  - المشكلة: `GET /kegs/{keg_id} failed`
  - `exception.type`: `ValueError`
  - `mechanism`: `fastapi.middleware`
  - `handled`: `false`
  - إطارات المكدّس: 21
- `logbrew.logging_handler`
  - الرسالة: `request failed`
  - `exceptionName`: `ValueError`
  - `exceptionMessage`: `keg 7 is empty`

## أسئلة شائعة

### كيف أضبط التسجيل في FastAPI؟

استدعِ `logging.basicConfig()` مرة واحدة في أعلى `main.py`، ثم استخدم `logging.getLogger()` في كل وحدة. دون إعداد، يُسقط Python المستويين `info` و`debug`.

### كيف أعالج كل الاستثناءات في FastAPI؟

أضف `@app.exception_handler(Exception)` وأعد استجابتك الخاصة. يتلقّى العميل استجابتك، ويبقى uvicorn يطبع تتبّع المكدّس.

### لماذا يعيد FastAPI الحالة 422؟

لم تطابق قيمة في المسار أو الاستعلام أو جسم الطلب نوعها. فشل `/kegs/abc` في فحص `keg_id: int`، لذلك أعاد FastAPI قائمة `detail` بالحالة 422.

### ما معنى Exception in ASGI application؟

خرج استثناء من مسارك ولم يوقفه أي معالج. يسجّله uvicorn مع تتبّع المكدّس، ويتلقّى العميل `Internal Server Error` بالحالة 500.

## شاهد كل خطأ في FastAPI مع مساره

تسجّل logbrew-fastapi كل خطأ غير معالَج على أنه مشكلة تحمل اسم قالب مساره، وترسل سجلاتك مع تتبّع طلبها. ابدأ بخطة مجانية سخية دون بطاقة.

[ابدأ مجانًا](https://logbrew.co/ar)

## المصادر

- [FastAPI docs, Install custom exception handlers](https://fastapi.tiangolo.com/tutorial/handling-errors/#install-custom-exception-handlers)
- [FastAPI docs, Use HTTPException](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)
- [fastapi/fastapi#14071](https://github.com/fastapi/fastapi/discussions/14071)

## إرشادات أخرى للوكلاء وPython وNode.js وReact

- [أضف خادم MCP إلى Claude Code وCodex](https://logbrew.co/ar/guides/mcp-server-claude-code-codex)
- [استخدم AGENTS.md في Claude Code وCodex](https://logbrew.co/ar/guides/agents-md)
- [أصلح خطأ Claude overloaded 529 وخطأ rate limit 429](https://logbrew.co/ar/guides/claude-overloaded-rate-limit-error)
- [إعداد Python logging بمستويات السجل الصحيحة والتقاط الاستثناءات](https://logbrew.co/ar/guides/python-logging)
- [التسجيل المنظّم بتنسيق سجل ومستويات سجل يمكنك البحث فيها حسب الحقل](https://logbrew.co/ar/guides/structured-logging)
- [إعداد السجلات في Node.js باستخدام Pino أو Winston دون أن تفقد أي خطأ](https://logbrew.co/ar/guides/node-logging)
- [أعدّ سجلات Django واحفظ تتبّع المكدّس لكل خطأ 500](https://logbrew.co/ar/guides/django-logging)
- [أضف حدًّا للأخطاء في React وسجّل الأخطاء التي تفوته](https://logbrew.co/ar/guides/react-error-boundary)
- [الفرق بين Trace ID وSpan ID من ترويسة traceparent حقيقية](https://logbrew.co/ar/guides/trace-id)
- [أدلة للأخطاء والسجلات والتتبّعات والمقاييس والإصدارات](https://logbrew.co/ar/guides)
