---
title: "إعداد السجلات في Node.js باستخدام Pino أو Winston دون أن تفقد أي خطأ"
description: "يفقد Pino وWinston الخطأ في بعض الاستدعاءات. إليك إعداد كل مسجّل في Node.js، ومستويات السجل، والاستدعاءات التي تحفظ المكدّس، من اختبار على Node.js 22."
canonical: "https://logbrew.co/ar/guides/node-logging"
last_updated: "2026-11-20"
---

# إعداد السجلات في Node.js باستخدام Pino أو Winston دون أن تفقد أي خطأ

يفقد Pino وWinston الخطأ في بعض الاستدعاءات. إليك إعداد كل مسجّل في Node.js، ومستويات السجل، والاستدعاءات التي تحفظ المكدّس، من اختبار على Node.js 22.

اختُبر في 20 نوفمبر 2026 باستخدام Node.js 22.18.0 وPino 10.4.0 وWinston 3.19.0 وExpress 5.3.0 و@logbrew/node 0.1.30 و@logbrew/sdk 0.1.47 و@logbrew/express 0.1.14

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

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

## أي استدعاء يحفظ الخطأ، على الشاشة وفي LogBrew

| استدعاء السجل | المطبوع | في LogBrew |
| --- | --- | --- |
| Pino `error(err, msg)` | الرسالة والمكدّس | الاسم والرسالة |
| Pino `error(msg, err)` | ضائع | ضائع |
| Winston `error(err)` | `{"level":"error"}` | الاسم والرسالة |
| Winston `error(err, msg)` | `"message":{}` | ضائع |
| Winston `error(msg, { err })` | `"err":{}` | الاسم والرسالة |
| Winston `error(msg, err)` | الرسالة والمكدّس | الاسم والرسالة |

6 استدعاءات مع `new Error("keg empty")` في Pino 10.4 وفي Winston 3.19 دون تنسيق.

## إعداد مسجّل Pino

### أنشئ مسجّلًا واحدًا ودعه يطبع JSON

يسجّل `pino()` من `info` فما فوق، ويطبع سطر JSON واحدًا لكل استدعاء، فيه `level` رقمي و`time` و`pid` و`hostname`. لم يطبع استدعاء `debug` شيئًا. استبدلنا اسم المضيف في المخرجات.

```bash
import pino from "pino";

const logger = pino();

logger.debug("keg pressure read");
logger.info("tap opened");
logger.warn("keg below 10%");
logger.error("keg empty");
logger.fatal("cooler offline");
```

المخرجات

```text
{"level":30,"time":1795160014210,"pid":27152,"hostname":"taproom","msg":"tap opened"}
{"level":40,"time":1795160014211,"pid":27152,"hostname":"taproom","msg":"keg below 10%"}
{"level":50,"time":1795160014211,"pid":27152,"hostname":"taproom","msg":"keg empty"}
{"level":60,"time":1795160014211,"pid":27152,"hostname":"taproom","msg":"cooler offline"}
```

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

شغّله مع `LOG_LEVEL=debug` فيظهر سطر `debug` دون تغيير الشيفرة. أما `LOG_LEVEL` الفارغ فيوقف العملية. يُبقي `??` النص الفارغ، فيرمي Pino الخطأ `default level: must be included in custom levels`. استخدم `||` إذا كان المتغير قد يأتي فارغًا.

```bash
import pino from "pino";

const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });

logger.debug("keg pressure read");
logger.info("tap opened");
```

المخرجات

```text
{"level":20,"time":1795160014268,"pid":27166,"hostname":"taproom","msg":"keg pressure read"}
{"level":30,"time":1795160014268,"pid":27166,"hostname":"taproom","msg":"tap opened"}
```

### مرّر الخطأ أولًا ثم الرسالة

يحوّل Pino كائن `Error` في الوسيط الأول، أو في الحقل `err`، إلى `err` فيه `type` و`message` و`stack`. أما الخطأ الممرَّر بعد الرسالة فيضيع دون تحذير. السطر الثالث بلا `err`. قصصنا كل مكدّس بعد سطره الأول.

```bash
import pino from "pino";

const logger = pino();
const err = new Error("keg empty");

logger.error(err, "pour failed");
logger.error({ err, orderId: "ord_42" }, "pour failed");
logger.error("pour failed", err);
```

المخرجات

```text
{"level":50,"time":1795160014336,"pid":27169,"hostname":"taproom","err":{"type":"Error","message":"keg empty","stack":"Error: keg empty\n    at …"},"msg":"pour failed"}
{"level":50,"time":1795160014337,"pid":27169,"hostname":"taproom","err":{"type":"Error","message":"keg empty","stack":"Error: keg empty\n    at …"},"orderId":"ord_42","msg":"pour failed"}
{"level":50,"time":1795160014337,"pid":27169,"hostname":"taproom","msg":"pour failed"}
```

## إعداد مسجّل Winston

### أنشئ المسجّل مع ناقل Console

دون خيارات، يسجّل `winston.createLogger()` من `info` فما فوق ويطبع JSON. لم يطبع استدعاء `debug` شيئًا، ولا تحمل الأسطر وقتًا حتى تضيف `winston.format.timestamp()`.

```bash
import winston from "winston";

const logger = winston.createLogger({
  transports: [new winston.transports.Console()]
});

logger.debug("keg pressure read");
logger.info("tap opened");
logger.warn("keg below 10%");
logger.error("keg empty");
```

المخرجات

```text
{"level":"info","message":"tap opened"}
{"level":"warn","message":"keg below 10%"}
{"level":"error","message":"keg empty"}
```

### أضف format.errors() قبل format.json()

دون تنسيق، يطبع `logger.error(err)` القيمة `{"level":"error"}` فقط. يتخطى تنسيق JSON رسالة كائن `Error` ومكدّسه. ضع `winston.format.errors({ stack: true })` في البداية، فيطبع الاستدعاء نفسه الاثنين معًا.

```bash
import winston from "winston";

const err = new Error("keg empty");
const plain = winston.createLogger({
  transports: [new winston.transports.Console()]
});
plain.error(err);

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [new winston.transports.Console()]
});
logger.error(err);
```

المخرجات

```text
{"level":"error"}
{"level":"error","message":"keg empty","stack":"Error: keg empty\n    at …"}
```

### مرّر الرسالة أولًا ثم الخطأ

يُضيّع `logger.error(err, "pour failed")` رسالتك. ويطبع `logger.error("pour failed", { err })` القيمة `"err":{}`. أما `logger.error("pour failed", err)` فيحفظ الاثنين ويُلحق رسالة الخطأ برسالتك لتصبح `pour failed keg empty`.

```bash
import winston from "winston";

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [new winston.transports.Console()]
});
const err = new Error("keg empty");

logger.error(err, "pour failed");
logger.error("pour failed", { err });
logger.error("pour failed", err);
```

المخرجات

```text
{"level":"error","message":"keg empty","stack":"Error: keg empty\n    at …"}
{"err":{},"level":"error","message":"pour failed"}
{"level":"error","message":"pour failed keg empty","stack":"Error: keg empty\n    at …"}
```

## أرسل سجلات Pino وWinston إلى LogBrew

### ثبّت الحزم واضبط المفتاح

تلتقط `@logbrew/node` سجلات Pino، وتضم `@logbrew/sdk` ناقل Winston، وتضيف `@logbrew/express` تتبّع كل طلب. تقرأ `createLogBrewNodeClient()` المفتاح من `LOGBREW_SERVER_API_KEY`.

```bash
npm install pino winston express @logbrew/node @logbrew/sdk @logbrew/express
```

### استدعِ installLogBrewPinoInstrumentation() مرة واحدة

استدعها قبل أول سجل. يواصل Pino طباعة أسطره، ويستقبل LogBrew كل سجل مع `pinoLevel` و`pinoLevelNumber` وحقولك. يحتفظ LogBrew بالحقول المسطّحة فقط، لذلك لم يُرسَل الكائن `card`. يحفظ `RecordingTransport` ما أرسلته حزمة SDK لنطبعه. احذف `transport` في تطبيقك.

```bash
import pino from "pino";
import { RecordingTransport } from "@logbrew/sdk";
import { createLogBrewNodeClient, installLogBrewPinoInstrumentation } from "@logbrew/node";

const transport = RecordingTransport.alwaysAccept();
const client = createLogBrewNodeClient({ transport });
installLogBrewPinoInstrumentation({ client });

const logger = pino({ redact: ["card.number"] }).child({ service: "taproom" });
logger.info({ orderId: "ord_42", card: { number: "4242424242424242" } }, "order paid");
logger.error(new Error("keg empty"), "pour failed");

await client.shutdown();
for (const { attributes: { level, message, metadata } } of JSON.parse(transport.lastBody()).events) {
  console.log(JSON.stringify({ level, message, metadata }));
}
```

المخرجات

```text
{"level":30,"time":1795160014692,"pid":27178,"hostname":"taproom","service":"taproom","orderId":"ord_42","card":{"number":"[Redacted]"},"msg":"order paid"}
{"level":"info","message":"order paid","metadata":{"pinoLevel":"info","context.service":"taproom","context.orderId":"ord_42","pinoLevelNumber":30}}
{"level":"error","message":"pour failed","metadata":{"pinoLevel":"error","context.service":"taproom","pinoLevelNumber":50,"errorName":"Error","errorMessage":"keg empty"}}
{"level":50,"time":1795160014700,"pid":27178,"hostname":"taproom","service":"taproom","err":{"type":"Error","message":"keg empty","stack":"Error: keg empty\n    at …"},"msg":"pour failed"}
```

### أضف createLogBrewWinstonTransport() إلى Winston

أضف الناقل بجانب Console. يصل كل سجل ومعه `winstonLevel` و`defaultMeta` وحقولك، ومعه `errorName` و`errorMessage` عند وجود خطأ.

```bash
import winston from "winston";
import { RecordingTransport, createLogBrewWinstonTransport } from "@logbrew/sdk";
import { createLogBrewNodeClient } from "@logbrew/node";

const transport = RecordingTransport.alwaysAccept();
const client = createLogBrewNodeClient({ transport });

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  defaultMeta: { service: "taproom" },
  transports: [new winston.transports.Console(), createLogBrewWinstonTransport({ client })]
});
logger.info("order paid", { orderId: "ord_42" });
logger.error(new Error("keg empty"));

await client.shutdown();
for (const { attributes: { level, message, metadata } } of JSON.parse(transport.lastBody()).events) {
  console.log(JSON.stringify({ level, message, metadata }));
}
```

المخرجات

```text
{"level":"info","message":"order paid","orderId":"ord_42","service":"taproom"}
{"level":"error","message":"keg empty","service":"taproom","stack":"Error: keg empty\n    at …"}
{"level":"info","message":"order paid","metadata":{"winstonLevel":"info","context.service":"taproom","context.orderId":"ord_42"}}
{"level":"error","message":"keg empty","metadata":{"winstonLevel":"error","context.service":"taproom","errorName":"Error","errorMessage":"keg empty"}}
```

### اربط كل سجل بطلب Express الخاص به

يفتح `logbrewMiddleware()` نطاق span واحدًا لكل طلب، ويحوّل `logbrewErrorHandler()` الخطأ المرمي إلى مشكلة مع إطارات المكدّس. ويحصل سجل Pino داخل الطلب على معرّف التتبّع نفسه. العمود الأخير هو بداية هذا المعرّف.

```bash
import express from "express";
import pino from "pino";
import { RecordingTransport } from "@logbrew/sdk";
import { logbrewErrorHandler, logbrewMiddleware } from "@logbrew/express";
import { createLogBrewNodeClient, installLogBrewPinoInstrumentation } from "@logbrew/node";

const transport = RecordingTransport.alwaysAccept();
const client = createLogBrewNodeClient({ transport });
installLogBrewPinoInstrumentation({ client });
const logger = pino();

const app = express();
app.use(logbrewMiddleware({ client }));
app.get("/taps/:tap", (req, res) => {
  logger.info({ tap: req.params.tap }, "tap opened");
  res.json({ ok: true });
});
app.get("/kegs/:keg", () => {
  throw new Error("keg empty");
});
app.use(logbrewErrorHandler({ client }));
app.use((err, req, res, next) => {
  logger.error(err, "request failed");
  res.status(500).json({ error: "internal" });
});

const server = app.listen(3001, async () => {
  await fetch("http://127.0.0.1:3001/taps/ipa");
  await fetch("http://127.0.0.1:3001/kegs/stout");
  server.close();
  await client.shutdown();
  for (const body of transport.sentBodies) {
    for (const { type, attributes: a } of JSON.parse(body).events) {
      console.log(type, a.title ?? a.name ?? a.message, a.status ?? a.level, (a.traceId ?? a.context.trace.traceId).slice(0, 8));
    }
  }
});
```

المخرجات

```text
{"level":30,"time":1795160015082,"pid":27185,"hostname":"taproom","tap":"ipa","msg":"tap opened"}
{"level":50,"time":1795160015140,"pid":27185,"hostname":"taproom","err":{"type":"Error","message":"keg empty","stack":"Error: keg empty\n    at …"},"msg":"request failed"}
log tap opened info 3dc57c32
span GET /taps/:tap ok 3dc57c32
issue GET /kegs/:keg failed error 49e1920b
log request failed error 49e1920b
span GET /kegs/:keg error 49e1920b
```

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

شغّلنا كل نص برمجي في هذه الصفحة على Node.js 22.18.0 وPino 10.4.0 وWinston 3.19.0 وExpress 5.3.0. تعرض المخرجات كل حمولة بنتها حزمة SDK من LogBrew. وفي تشغيل ثانٍ أرسلنا السجلات نفسها إلى خادم LogBrew ثم قرأناها مرة أخرى.

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

|  | Pino | Winston |
| --- | --- | --- |
| `level: ""` | يتوقف عند البدء بخطأ | يسجّل كل المستويات، ومنها `debug` |
| تسري قيمة `logger.level` الجديدة فورًا | نعم | نعم |

## Pino أم Winston، أيهما تستخدم

ابقَ على المسجّل الذي يستخدمه تطبيقك. يستقبل LogBrew السجلات من الاثنين.

لا يملك Winston إخفاءً مدمجًا، لذلك تكتب تنسيقك الخاص.

|  | Pino | Winston |
| --- | --- | --- |
| ترتيب الوسائط | `error(err, msg)` | `error(msg, err)` |
| الوقت في كل سطر | نعم | مع `format.timestamp()` |
| المكدّس من `error(err)` | نعم | مع `format.errors()` |
| إخفاء مدمج | `redact` | لا |

## مستويات السجل في Node.js مع Pino وWinston

يرقّم Pino مستوياته من `trace` بالرقم 10 إلى `fatal` بالرقم 60، والرقم الأكبر أخطر. ويرقّم Winston مستوياته من `error` بالرقم 0 إلى `silly` بالرقم 6، والرقم الأصغر أخطر.

يسجّل كلاهما افتراضيًا من `info` فما فوق. اضبط `logger.level = "debug"` لتغيير المستوى أثناء تشغيل العملية.

يبقى المستوى الأصلي في `pinoLevel` أو `winstonLevel`.

```bash
import pino from "pino";
import winston from "winston";

console.log(pino().levels.values);
console.log(winston.createLogger().levels);
```

المخرجات

```text
{ trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 }
{ error: 0, warn: 1, info: 2, http: 3, verbose: 4, debug: 5, silly: 6 }
```

| LogBrew | Pino | Winston |
| --- | --- | --- |
| `info` | `trace` `debug` `info` | `silly` `debug` `verbose` `http` `info` |
| `warning` | `warn` | `warn` |
| `error` | `error` | `error` |
| `critical` | `fatal` | لا |

## ما يسجّله LogBrew

يصبح كل سجل من Pino أو Winston سجلًا واحدًا في LogBrew بمستواه ورسالته ومستواه الأصلي وحقولك. وتصل أيضًا الحقول من مسجّل فرعي أو من `defaultMeta`، مثل `context.service` أعلاه.

يضيف الخطأ داخل السجل `errorName` و`errorMessage`. اضبط `includeErrorStack: true` على أيٍّ من التكاملين لإرسال المكدّس أيضًا في `errorStack`.

يُسقط تكامل Pino حقولًا مثل `token` و`password` و`cookie` قبل أن يرسل السجل. أما ناقل Winston فيرسلها كما هي، لذا احذفها أولًا في format خاص بـ Winston.

مع وسيط Express، يحمل كل سجل معرّف تتبّع طلبه. وتتشارك المشكلة ونطاق span والسجلات لطلب فاشل واحد هذا المعرّف.

- `installLogBrewPinoInstrumentation()`
  - `pinoLevel`: `error`
  - `pinoLevelNumber`: `50`
  - `context.service`: `taproom`
  - `errorName`: `Error`
  - `errorMessage`: `keg empty`
- `createLogBrewWinstonTransport()`
  - `winstonLevel`: `error`
  - `context.service`: `taproom`
  - `errorName`: `Error`
  - `errorMessage`: `keg empty`
- `logbrewErrorHandler()`
  - المشكلة: `GET /kegs/:keg failed`
  - `exception.type`: `Error`
  - `mechanism`: `express.middleware`
  - `handled`: `false`
  - إطارات المكدّس: 10

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

### ما مستوى السجل الافتراضي في Pino؟

`info`. يطبع `pino()` المستويات `info` و`warn` و`error` و`fatal`، ويُسقط `debug` و`trace`. مرّر `level` إلى `pino()` أو اضبط `logger.level` لتغييره.

### لماذا يسجّل Winston رسالة فارغة للخطأ؟

يتخطى تنسيق JSON الخاصيتين `message` و`stack` في كائن `Error`، لأنهما غير قابلتين للتعداد. أضف `winston.format.errors({ stack: true })` قبل `winston.format.json()`.

### كيف أسجّل خطأً باستخدام Pino؟

مرّر الخطأ أولًا، مثل `logger.error(err, "pour failed")`، أو داخل حقل، مثل `logger.error({ err }, "pour failed")`. يُسقط Pino الخطأ الذي يأتي بعد الرسالة.

### هل أستخدم Pino أم Winston؟

ابقَ على المسجّل الذي يستخدمه تطبيقك. يطبع Pino بصيغة JSON دون إعداد وفيه إخفاء مدمج. ويبني Winston السطر من التنسيقات التي تختارها. يستقبل LogBrew السجلات من الاثنين.

### لماذا يرمي Pino الخطأ default level must be included in custom levels؟

المستوى الذي مرّرته ليس من مستويات Pino، وغالبًا ما يكون `LOG_LEVEL` فارغًا. اكتب `process.env.LOG_LEVEL || "info"` لتعود القيمة الفارغة إلى `info`.

## شاهد كل خطأ في Node.js مع طلبه

ترسل حزمة SDK من LogBrew لـNode كل سجل من Pino أو Winston بمستواه وحقوله، وتربطه بتتبّع الطلب وبالمشكلة. ابدأ بخطة مجانية سخية دون بطاقة.

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

## المصادر

- [Pino docs, Logging method parameters](https://github.com/pinojs/pino/blob/main/docs/api.md#logging-method-parameters)
- [Pino docs, Redaction](https://github.com/pinojs/pino/blob/main/docs/redaction.md)
- [Winston docs, Logging levels](https://github.com/winstonjs/winston/blob/master/README.md#logging-levels)
- [Winston docs, Formats](https://github.com/winstonjs/winston/blob/master/README.md#formats)
- [Express docs, Error handling](https://expressjs.com/en/guide/error-handling/)
- [winstonjs/winston#1338](https://github.com/winstonjs/winston/issues/1338)

## إرشادات أخرى للوكلاء و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)
- [أعدّ سجلات Django واحفظ تتبّع المكدّس لكل خطأ 500](https://logbrew.co/ar/guides/django-logging)
- [أعدّ سجلات FastAPI وعالج الأخطاء دون فقدان تتبّع المكدّس](https://logbrew.co/ar/guides/fastapi-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)
