ارسال داده
Instatus لاگها، ردیابیها و متریکها را با OpenTelemetry (OTLP روی HTTPS) دریافت میکند. دو راه برای اتصال یک اپلیکیشن وجود دارد. یکی را انتخاب کنید.
روش ۱: یک پرامپت کپی کنید
سریعترین راه، اگر از عامل برنامهنویسی مثل Claude Code، Cursor یا Copilot استفاده میکنید.
- در صفحهٔ وضعیت خود Observability را باز کنید.
- زیر شامل آنچه را میخواهید بفرستید علامت بزنید: لاگها، ردیابیها، متریکها. اگر بعدها داشبوردهای آماده برای سرویسهایتان میخواهید، داشبورد آغازین را هم علامت بزنید.
- روی کپی پرامپت کلیک کنید.
- آن را در عامل برنامهنویسی، داخل پروژهٔ اپلیکیشن، بچسبانید.
- کلید API را در متغیر محیطی
INSTATUS_API_KEYقرار دهید و آزمایشی را که عامل پیشنهاد میکند اجرا کنید.

پرامپت از عامل میخواهد از SDK رسمی OpenTelemetry برای زبان شما استفاده کند، کتابخانهٔ لاگ فعلی را نگه دارد، کلید را از یک متغیر محیطی بخواند و هرگز آن را commit نکند. شناسهٔ صفحهٔ شما از قبل در آن است.
روش ۲: راهاندازی دستی
- در صفحهٔ وضعیت خود Observability را باز کنید.
- روی راهاندازی دستی کلیک کنید.
- زبان خود را انتخاب کنید: Node.js، Python، Go، Java، .NET، Ruby، PHP یا OpenTelemetry Collector.
- دستور بخش نصب را کپی و اجرا کنید، سپس کد بخش پیکربندی را در اپلیکیشن خود کپی کنید.
- متغیر محیطی
INSTATUS_API_KEYرا روی کلید API خود تنظیم کنید و اپلیکیشن را اجرا کنید.

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

شناسهٔ صفحهٔ خود را پیدا کنید
بهندرت لازم است: پرامپت و کد داخل داشبورد از قبل آن را دارند. برای کپی کردنش، روی نام پروژه در بالای داشبورد راستکلیک کنید و Copy Project ID را انتخاب کنید.

یک لاگ آزمایشی بفرستید
یک درخواست از ترمینال کافی است تا کلید و شناسهٔ صفحه را بررسی کنید:
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 متغیرهای محیطی یکسانی را میخوانند. با آنها، ابزارگذاری خودکار بدون دست زدن به کد، ردیابیها، متریکها و لاگها را میفرستد:
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 است. سپس اپلیکیشن را با ابزارگذاری خودکار زبانش اجرا کنید:
# Node.jsnpm install @opentelemetry/api @opentelemetry/auto-instrumentations-nodenode --require @opentelemetry/auto-instrumentations-node/register app.js# Pythonpip install opentelemetry-distro opentelemetry-exporter-otlpopentelemetry-bootstrap -a installOTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true opentelemetry-instrument python app.py
Java، .NET، Go، Ruby و PHP ابزارگذاری خودکار خودشان را دارند و همین متغیرها را میخوانند. راهنماهای بدون کد OpenTelemetry را ببینید.
Node.js
برای ارسال لاگ از کد، SDK لاگ را نصب کنید:
npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \@opentelemetry/exporter-logs-otlp-http @opentelemetry/resources
یک بار هنگام شروع اپلیکیشن آن را راهاندازی کنید:
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 و @opentelemetry/winston-transport هر خط لاگ موجود را همانطور که هست میفرستند.
Python
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
SDK به ماژول logging پایتون وصل میشود، پس فراخوانیهای فعلی logging همانطور که هستند فرستاده میشوند:
import loggingimport osfrom opentelemetry._logs import set_logger_providerfrom opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporterfrom opentelemetry.sdk._logs import LoggerProvider, LoggingHandlerfrom opentelemetry.sdk._logs.export import BatchLogRecordProcessorfrom opentelemetry.sdk.resources import Resourceprovider = 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 را بهعنوان صادرکننده اضافه کنید و اپلیکیشنها را دست نزنید:
exporters:otlphttp/instatus:endpoint: https://otel.instatus.comheaders: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 | سهمیهٔ دادهٔ این ماه تمام شده است. پلنها و محدودیتها را ببینید. |
200، اما چیزی نمایش داده نمیشود | چند ثانیه صبر کنید و بعد بازهٔ زمانی را بررسی کنید. لاگی که مُهر زمانیاش در گذشته است فقط وقتی دیده میشود که بازه آن را پوشش دهد. |
| هیچچیز | SDKها داده را دستهای میفرستند. مطمئن شوید اپلیکیشن پیش از خروج، provider را خالی یا خاموش میکند. |
ساختن دوبارهٔ کلید API در تنظیمات توسعهدهنده، کلید قبلی را فوراً از کار میاندازد؛ پس اول هر اپلیکیشنی را که از آن استفاده میکند بهروز کنید.