ارسال داده

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

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

سریع‌ترین راه، اگر از عامل برنامه‌نویسی مثل Claude Code،‏ Cursor یا Copilot استفاده می‌کنید.

  1. در صفحهٔ وضعیت خود Observability را باز کنید.
  2. زیر شامل آنچه را می‌خواهید بفرستید علامت بزنید: لاگ‌ها،‏ ردیابی‌ها،‏ متریک‌ها. اگر بعدها داشبوردهای آماده برای سرویس‌هایتان می‌خواهید، داشبورد آغازین را هم علامت بزنید.
  3. روی کپی پرامپت کلیک کنید.
  4. آن را در عامل برنامه‌نویسی، داخل پروژهٔ اپلیکیشن، بچسبانید.
  5. کلید API را در متغیر محیطی INSTATUS_API_KEY قرار دهید و آزمایشی را که عامل پیشنهاد می‌کند اجرا کنید.
کارت راه‌اندازی با لاگ‌ها، ردیابی‌ها و متریک‌ها برای انتخاب و دکمهٔ کپی پرامپت

پرامپت از عامل می‌خواهد از SDK رسمی OpenTelemetry برای زبان شما استفاده کند، کتابخانهٔ لاگ فعلی را نگه دارد، کلید را از یک متغیر محیطی بخواند و هرگز آن را commit نکند. شناسهٔ صفحهٔ شما از قبل در آن است.

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

  1. در صفحهٔ وضعیت خود Observability را باز کنید.
  2. روی راه‌اندازی دستی کلیک کنید.
  3. زبان خود را انتخاب کنید: Node.js،‏ Python،‏ Go،‏ Java،‏ .NET،‏ Ruby،‏ PHP یا OpenTelemetry Collector.
  4. دستور بخش نصب را کپی و اجرا کنید، سپس کد بخش پیکربندی را در اپلیکیشن خود کپی کنید.
  5. متغیر محیطی INSTATUS_API_KEY را روی کلید API خود تنظیم کنید و اپلیکیشن را اجرا کنید.
راه‌اندازی دستی با Node.js انتخاب‌شده، همراه با دستور نصب و کد پیکربندی

در کد داخل داشبورد، شناسهٔ صفحهٔ شما از قبل وارد شده است. اگر ترجیح می‌دهید از این‌جا کپی کنید، همان نمونه‌ها در ادامه آمده‌اند.

هر درخواست به چه نیاز دارد

موردمقدار
نقطهٔ پایانیhttps://otel.instatus.com. لاگ‌ها به /v1/logs، ردیابی‌ها به /v1/traces و متریک‌ها به /v1/metrics می‌روند.
AuthorizationBearer <API_KEY>، با کلید مالک، مدیر یا ویرایشگر صفحه.
X-Instatus-Site-Idشناسهٔ صفحهٔ وضعیتی که داده به آن تعلق دارد.
پروتکلOTLP روی HTTP، به‌صورت protobuf یا JSON. اگر SDK شما به‌طور پیش‌فرض از gRPC استفاده می‌کند، آن را روی HTTP بگذارید.

کلید API به کل حساب شما دسترسی می‌دهد. آن را روی سرورهای خود و در یک متغیر محیطی نگه دارید. هرگز آن را در مرورگر، اپلیکیشن موبایل یا مخزن عمومی قرار ندهید.

کلید API خود را پیدا کنید

منوی آواتار را باز کنید، تنظیمات کاربر و سپس توسعه‌دهنده را انتخاب کنید یا مستقیم به تنظیمات توسعه‌دهنده بروید. کنار کلید روی کپی کلیک کنید.

کلید API در تنظیمات توسعه‌دهنده با دکمهٔ کپی

شناسهٔ صفحهٔ خود را پیدا کنید

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

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.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 را ببینید.

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 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 را به‌عنوان صادرکننده اضافه کنید و اپلیکیشن‌ها را دست نزنید:

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

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