שליחת נתונים

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

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

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

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

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

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

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