שליחת נתונים
Instatus מקבל יומנים, עקבות ומדדים דרך OpenTelemetry (OTLP על גבי HTTPS). יש שתי דרכים לחבר אפליקציה. בחרו אחת.
אפשרות 1: העתיקו הנחיה
הדרך המהירה ביותר, אם אתם משתמשים בסוכן תכנות כמו Claude Code, Cursor או Copilot.
- פתחו את Observability בדף הסטטוס שלכם.
- תחת לכלול, סמנו מה תרצו לשלוח: יומנים, עקבות, מדדים. סמנו גם את לוח בקרה ראשוני אם בהמשך תרצו לוחות בקרה מוכנים לשירותים שלכם.
- לחצו על העתקת הפרומפט.
- הדביקו אותה בסוכן התכנות, בפרויקט של האפליקציה.
- שמרו את מפתח ה-API במשתנה הסביבה
INSTATUS_API_KEY, והריצו את הבדיקה שהסוכן מציע.

ההנחיה מבקשת מהסוכן להשתמש ב-SDK הרשמי של OpenTelemetry לשפה שלכם, לשמור על ספריית הרישום הקיימת, לקרוא את המפתח ממשתנה סביבה ולעולם לא לעשות לו commit. מזהה הדף שלכם כבר כלול בה.
אפשרות 2: הגדרה ידנית
- פתחו את 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 של Python, כך שקריאות 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 ומשימה. |
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 בהגדרות המפתחים משביתה מיד את הישן, לכן עדכנו קודם כל אפליקציה שמשתמשת בו.