# שליחת נתונים

Source: https://instatus.com/help/he/observability/send-logs

Instatus מקבל יומנים, עקבות ומדדים דרך OpenTelemetry (‏OTLP על גבי HTTPS). יש שתי דרכים לחבר אפליקציה. בחרו אחת.

| At a glance | Details |
| :-- | :-- |
| [הכי מהיר](https://instatus.com/help/he/observability/send-logs#אפשרות-1-העתיקו-הנחיה) | העתיקו הנחיה לסוכן התכנות שלכם |
| [ידנית](https://instatus.com/help/he/observability/send-logs#אפשרות-2-הגדרה-ידנית) | בחרו שפה והדביקו את הקוד |
| [נקודת קצה](https://instatus.com/help/he/observability/send-logs#מה-כל-בקשה-צריכה) | https://otel.instatus.com ועוד שתי כותרות |
| [בדיקה](https://instatus.com/help/he/observability/send-logs#שלחו-יומן-בדיקה) | בקשת curl אחת |
| [לא מופיע כלום?](https://instatus.com/help/he/observability/send-logs#פתרון-בעיות) | פתרון הבעיות הנפוצות |

## אפשרות 1: העתיקו הנחיה

הדרך המהירה ביותר, אם אתם משתמשים בסוכן תכנות כמו Claude Code,‏ Cursor או Copilot.

1. פתחו את **Observability** בדף הסטטוס שלכם.
2. תחת **לכלול**, סמנו מה תרצו לשלוח: **יומנים**, **עקבות**, **מדדים**. סמנו גם את **לוח בקרה ראשוני** אם בהמשך תרצו לוחות בקרה מוכנים לשירותים שלכם.
3. לחצו על **העתקת הפרומפט**.
4. הדביקו אותה בסוכן התכנות, בפרויקט של האפליקציה.
5. שמרו את [מפתח ה-API](#איפה-מוצאים-את-מפתח-ה-api) במשתנה הסביבה `INSTATUS_API_KEY`, והריצו את הבדיקה שהסוכן מציע.

![כרטיס ההגדרה עם יומנים, עקבות ומדדים לבחירה וכפתור להעתקת ההנחיה](https://instatus.com/help/observability/setup.png)

ההנחיה מבקשת מהסוכן להשתמש ב-SDK הרשמי של OpenTelemetry לשפה שלכם, לשמור על ספריית הרישום הקיימת, לקרוא את המפתח ממשתנה סביבה ולעולם לא לעשות לו commit. מזהה הדף שלכם כבר כלול בה.

## אפשרות 2: הגדרה ידנית

1. פתחו את **Observability** בדף הסטטוס שלכם.
2. לחצו על **הגדרה ידנית**.
3. בחרו את השפה: Node.js,‏ Python,‏ Go,‏ Java,‏ .NET,‏ Ruby,‏ PHP או OpenTelemetry Collector.
4. העתיקו את הפקודה שתחת **התקנה** והריצו אותה, ואז העתיקו את הקוד שתחת **הגדרה** לאפליקציה.
5. הגדירו את משתנה הסביבה `INSTATUS_API_KEY` ל[מפתח ה-API](#איפה-מוצאים-את-מפתח-ה-api) שלכם והפעילו את האפליקציה.

![הגדרה ידנית עם Node.js נבחר, עם פקודת ההתקנה וקוד ההגדרה](https://instatus.com/help/observability/setup-by-hand.png)

בקוד שבלוח הבקרה כבר מולא מזהה הדף שלכם. אותן דוגמאות מופיעות למטה, אם נוח לכם יותר להעתיק מכאן.

## מה כל בקשה צריכה

| מה          | ערך                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------------- |
| נקודת קצה      | `https://otel.instatus.com`. יומנים נשלחים ל-`/v1/logs`, עקבות ל-`/v1/traces` ומדדים ל-`/v1/metrics`. |
| `Authorization`      | `Bearer <API_KEY>`, עם המפתח של בעלים, מנהל או עורך של הדף.                    |
| `X-Instatus-Site-Id` | מזהה דף הסטטוס שאליו שייכים הנתונים.                                                |
| פרוטוקול      | OTLP על גבי HTTP, בפורמט protobuf או JSON. אם ה-SDK שלכם משתמש ב-gRPC כברירת מחדל, העבירו אותו ל-HTTP.          |

> מפתח ה-API נותן גישה לכל החשבון שלכם. שמרו אותו בשרתים שלכם, במשתנה סביבה. לעולם אל תשימו אותו בדפדפן, באפליקציה לנייד או במאגר ציבורי.

### איפה מוצאים את מפתח ה-API

פתחו את תפריט האווטאר, בחרו **הגדרות משתמש** ואז **מפתחים**, או עברו ישירות ל[הגדרות המפתחים](https://dashboard.instatus.com/developer). לחצו על **העתקה** ליד המפתח.

![מפתח ה-API בהגדרות המפתחים, עם כפתור העתקה](https://instatus.com/help/observability/api-key.png)

### איפה מוצאים את מזהה הדף

לרוב אין בו צורך: ההנחיה והקוד שבלוח הבקרה כבר כוללים אותו. כדי להעתיק אותו בעצמכם, לחצו לחיצה ימנית על שם הפרויקט בראש לוח הבקרה ובחרו **Copy Project ID**.

![Copy Project ID בתפריט של שם הפרויקט](https://instatus.com/help/observability/copy-page-id.png)

## שלחו יומן בדיקה

בקשה אחת מהטרמינל מספיקה כדי לבדוק את המפתח ואת מזהה הדף:

```bash
curl -X POST https://otel.instatus.com/v1/logs \
  -H "Authorization: Bearer $INSTATUS_API_KEY" \
  -H "X-Instatus-Site-Id: $INSTATUS_PAGE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceLogs": [{
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "api" } }
        ]
      },
      "scopeLogs": [{
        "logRecords": [{
          "timeUnixNano": "'$(date +%s)'000000000",
          "severityText": "INFO",
          "body": { "stringValue": "Hello from Instatus" }
        }]
      }]
    }]
  }'
```

תגובת `200` אומרת שהיומן התקבל. פתחו את **Observability** ← **יומנים**, והוא יופיע תוך שניות.

## כל שפה, בלי שינויי קוד

כל ה-SDK של OpenTelemetry קוראים את אותם משתני סביבה. בעזרתם, מכשור אוטומטי שולח עקבות, מדדים ויומנים בלי לגעת בקוד:

```bash
export OTEL_SERVICE_NAME="api"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.instatus.com"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${INSTATUS_API_KEY},X-Instatus-Site-Id=${INSTATUS_PAGE_ID}"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
```

הרווח שאחרי `Bearer` נכתב כ-`%20`, כי משתנה הכותרות מקודד כ-URL. לאחר מכן הפעילו את האפליקציה עם המכשור האוטומטי של השפה שלה:

```bash
# Node.js
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register app.js

# Python
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py
```

ל-Java,‏ .NET,‏ Go,‏ Ruby ו-PHP יש מכשור אוטומטי משלהם, והוא קורא את אותם משתנים. ראו את [המדריכים ללא קוד של OpenTelemetry](https://opentelemetry.io/docs/zero-code/).

## Node.js

כדי לשלוח יומנים מהקוד, התקינו את ה-SDK ליומנים:

```bash
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \
  @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
```

הגדירו אותו פעם אחת כשהאפליקציה עולה:

```js
import { SeverityNumber } from '@opentelemetry/api-logs'
import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { BatchLogRecordProcessor, LoggerProvider } from '@opentelemetry/sdk-logs'

const provider = new LoggerProvider({
  resource: resourceFromAttributes({ 'service.name': 'api' }),
  processors: [
    new BatchLogRecordProcessor(
      new OTLPLogExporter({
        url: 'https://otel.instatus.com/v1/logs',
        headers: {
          Authorization: `Bearer ${process.env.INSTATUS_API_KEY}`,
          'X-Instatus-Site-Id': process.env.INSTATUS_PAGE_ID
        }
      })
    )
  ]
})

const logger = provider.getLogger('api')

logger.emit({
  severityNumber: SeverityNumber.ERROR,
  severityText: 'ERROR',
  body: 'Payment failed: card declined',
  attributes: { 'customer.id': 'cus_123', route: '/v2/charges' }
})

process.on('beforeExit', () => provider.shutdown())
```

כבר רושמים יומנים עם **pino** או **winston**? השאירו אותם. [`pino-opentelemetry-transport`](https://www.npmjs.com/package/pino-opentelemetry-transport) ו-[`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) שולחים כל שורת יומן קיימת כמו שהיא.

## Python

```bash
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

ה-SDK מתחבר למודול `logging` של Python, כך שקריאות `logging` הקיימות נשלחות כמו שהן:

```python
import logging
import os

from opentelemetry._logs import set_logger_provider
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.resources import Resource

provider = LoggerProvider(resource=Resource.create({"service.name": "worker"}))
provider.add_log_record_processor(
    BatchLogRecordProcessor(
        OTLPLogExporter(
            endpoint="https://otel.instatus.com/v1/logs",
            headers={
                "Authorization": f"Bearer {os.environ['INSTATUS_API_KEY']}",
                "X-Instatus-Site-Id": os.environ["INSTATUS_PAGE_ID"],
            },
        )
    )
)
set_logger_provider(provider)

logging.getLogger().addHandler(LoggingHandler(level=logging.INFO, logger_provider=provider))
logging.getLogger().setLevel(logging.INFO)

logging.warning("Card declined for customer %s", "cus_123")
```

## OpenTelemetry Collector

כבר מריצים את OpenTelemetry Collector? הוסיפו את Instatus כמייצא והשאירו את האפליקציות כמו שהן:

```yaml
exporters:
  otlphttp/instatus:
    endpoint: https://otel.instatus.com
    headers:
      Authorization: Bearer ${env:INSTATUS_API_KEY}
      X-Instatus-Site-Id: ${env:INSTATUS_PAGE_ID}

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/instatus]
```

המייצא מוסיף בעצמו את `/v1/logs`,‏ `/v1/traces` ו-`/v1/metrics`, כך שנקודת הקצה היא המארח בלבד. כדי לשלוח קובצי יומן, הוסיפו מקלט `filelog` לצינור היומנים.

## מה לשלוח

Instatus קורא את השדות האלה. כל השאר נשמר כמאפיין שאפשר לחפש ולסנן לפיו.

| שדה                       | משמש ל                                                                                    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `service.name` (משאב)      | העמודה והמסנן **שירות**. הגדירו אותו בכל אפליקציה, worker ומשימה. |
| `body`                             | הודעת היומן, שבה מחפש החיפוש החופשי.                                                     |
| `severityText` או `severityNumber` | הרמה: `fatal`,‏ `error`,‏ `warn`,‏ `info`,‏ `debug` או `trace`.                                  |
| `traceId` ו `spanId`             | מקשר יומן לעקבה שלו, כדי לעבור ביניהם.                                          |
| מאפיינים                     | כל מה שתוסיפו, כמו `customer.id` או `http.route`. כל אחד מהם הופך למסנן.               |

מאפיינים שמתחילים ב-`instatus.` שמורים, ומוחלפים כשהנתונים מגיעים.

## פתרון בעיות

| מה רואים               | פתרון                                                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `401`                       | בדקו את המפתח ואת הכותרת `X-Instatus-Site-Id`. בעל המפתח חייב להיות בעלים, מנהל או עורך של הדף.       |
| `400`                       | גוף הבקשה אינו OTLP תקין. בדקו את `Content-Type` ואת מבנה ה-JSON ב[יומן הבדיקה](#שלחו-יומן-בדיקה).             |
| `429`                       | מכסת הנתונים של החודש נוצלה. ראו [תוכניות ומגבלות](https://instatus.com/help/he/observability#תוכניות-ומגבלות).                    |
| `200`, אבל לא מופיע כלום | חכו כמה שניות ובדקו את טווח הזמן. יומן עם חותמת זמן בעבר מופיע רק כשהטווח מכסה אותה. |
| שום דבר              | ה-SDK שולחים בקבוצות. ודאו שהאפליקציה מרוקנת או סוגרת את ה-provider לפני שהיא נסגרת.                           |

יצירה מחדש של מפתח ה-API בהגדרות המפתחים משביתה מיד את הישן, לכן עדכנו קודם כל אפליקציה שמשתמשת בו.

- [יומנים](https://instatus.com/help/he/observability/logs): חפשו, סננו ועקבו אחרי היומנים בשידור חי
- [עקבות](https://instatus.com/help/he/observability/traces): ראו איפה כל בקשה מבזבזת את הזמן שלה
