# ارسال داده

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

Instatus لاگ‌ها، ردیابی‌ها و متریک‌ها را با OpenTelemetry (‏OTLP روی HTTPS) دریافت می‌کند. دو راه برای اتصال یک اپلیکیشن وجود دارد. یکی را انتخاب کنید.

| At a glance | Details |
| :-- | :-- |
| [سریع‌ترین](https://instatus.com/help/fa/observability/send-logs#روش-۱-یک-پرامپت-کپی-کنید) | یک پرامپت برای عامل برنامه‌نویسی کپی کنید |
| [دستی](https://instatus.com/help/fa/observability/send-logs#روش-۲-راهاندازی-دستی) | زبان را انتخاب کنید و کد را بچسبانید |
| [نقطهٔ پایانی](https://instatus.com/help/fa/observability/send-logs#هر-درخواست-به-چه-نیاز-دارد) | https://otel.instatus.com به‌همراه دو هدر |
| [آزمایش](https://instatus.com/help/fa/observability/send-logs#یک-لاگ-آزمایشی-بفرستید) | یک درخواست curl |
| [چیزی نمایش داده نمی‌شود؟](https://instatus.com/help/fa/observability/send-logs#رفع-اشکال) | مشکلات رایج را برطرف کنید |

## روش ۱: یک پرامپت کپی کنید

سریع‌ترین راه، اگر از عامل برنامه‌نویسی مثل 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 نکند. شناسهٔ صفحهٔ شما از قبل در آن است.

## روش ۲: راه‌اندازی دستی

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` پایتون وصل می‌شود، پس فراخوانی‌های فعلی `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 و job تنظیم کنید. |
| `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/fa/observability#پلنها-و-محدودیتها) را ببینید.                    |
| `200`، اما چیزی نمایش داده نمی‌شود | چند ثانیه صبر کنید و بعد بازهٔ زمانی را بررسی کنید. لاگی که مُهر زمانی‌اش در گذشته است فقط وقتی دیده می‌شود که بازه آن را پوشش دهد. |
| هیچ‌چیز              | SDKها داده را دسته‌ای می‌فرستند. مطمئن شوید اپلیکیشن پیش از خروج، provider را خالی یا خاموش می‌کند.                           |

ساختن دوبارهٔ کلید API در تنظیمات توسعه‌دهنده، کلید قبلی را فوراً از کار می‌اندازد؛ پس اول هر اپلیکیشنی را که از آن استفاده می‌کند به‌روز کنید.

- [لاگ‌ها](https://instatus.com/help/fa/observability/logs): لاگ‌ها را جست‌وجو، فیلتر و زنده دنبال کنید
- [ردیابی‌ها](https://instatus.com/help/fa/observability/traces): ببینید هر درخواست وقتش را کجا صرف می‌کند
