Daten senden

Instatus empfängt Logs, Traces und Metriken über OpenTelemetry (OTLP über HTTPS). Es gibt zwei Wege, eine App zu verbinden. Wählen Sie einen.

Weg 1: Einen Prompt kopieren

Der schnellste Weg, wenn Sie einen Coding-Agenten wie Claude Code, Cursor oder Copilot nutzen.

  1. Öffnen Sie Observability auf Ihrer Statusseite.
  2. Wählen Sie unter Einbeziehen, was Sie senden möchten: Logs, Traces, Metriken. Wählen Sie auch Start-Dashboard, wenn Sie später fertige Dashboards für Ihre Dienste möchten.
  3. Klicken Sie auf Prompt kopieren.
  4. Fügen Sie ihn in Ihren Coding-Agenten ein, im Projekt Ihrer App.
  5. Legen Sie Ihren API-Schlüssel in der Umgebungsvariable INSTATUS_API_KEY ab und führen Sie den Test aus, den der Agent vorschlägt.
Die Einrichtungskarte mit Logs, Traces und Metriken zur Auswahl und einer Schaltfläche zum Kopieren des Prompts

Der Prompt sagt dem Agenten, das offizielle OpenTelemetry-SDK Ihrer Sprache zu nutzen, Ihre bestehende Logging-Bibliothek zu behalten, den Schlüssel aus einer Umgebungsvariable zu lesen und ihn nie zu committen. Ihre Seiten-ID steht schon darin.

Weg 2: Von Hand einrichten

  1. Öffnen Sie Observability auf Ihrer Statusseite.
  2. Klicken Sie auf Manuell einrichten.
  3. Wählen Sie Ihre Sprache: Node.js, Python, Go, Java, .NET, Ruby, PHP oder den OpenTelemetry Collector.
  4. Kopieren Sie den Befehl unter Installieren und führen Sie ihn aus, dann kopieren Sie den Code unter Konfigurieren in Ihre App.
  5. Setzen Sie die Umgebungsvariable INSTATUS_API_KEY auf Ihren API-Schlüssel und starten Sie Ihre App.
Von Hand einrichten mit ausgewähltem Node.js, mit dem Installationsbefehl und dem Konfigurationscode

Im Code im Dashboard ist Ihre Seiten-ID bereits eingetragen. Dieselben Beispiele finden Sie unten, falls Sie lieber hier kopieren.

Was jede Anfrage braucht

WasWert
Endpunkthttps://otel.instatus.com. Logs gehen an /v1/logs, Traces an /v1/traces, Metriken an /v1/metrics.
AuthorizationBearer <API_KEY>, mit dem Schlüssel eines Eigentümers, Admins oder Editors der Seite.
X-Instatus-Site-IdDie ID der Statusseite, zu der die Daten gehören.
ProtokollOTLP über HTTP, als Protobuf oder JSON. Nutzt Ihr SDK standardmäßig gRPC, stellen Sie es auf HTTP um.

Ihr API-Schlüssel gibt Zugriff auf Ihr gesamtes Konto. Bewahren Sie ihn auf Ihren Servern auf, in einer Umgebungsvariable. Legen Sie ihn nie in einen Browser, eine mobile App oder ein öffentliches Repository.

Ihren API-Schlüssel finden

Öffnen Sie Ihr Avatar-Menü, wählen Sie Benutzereinstellungen und dann Entwickler, oder gehen Sie direkt zu den Entwicklereinstellungen. Klicken Sie neben dem Schlüssel auf Kopieren.

Der API-Schlüssel in den Entwicklereinstellungen mit einer Schaltfläche zum Kopieren

Ihre Seiten-ID finden

Das ist selten nötig: Der Prompt und der Code im Dashboard enthalten sie schon. Um sie selbst zu kopieren, klicken Sie mit der rechten Maustaste auf den Projektnamen oben im Dashboard und wählen Copy Project ID.

Copy Project ID im Menü des Projektnamens

Ein Test-Log senden

Eine Anfrage aus dem Terminal genügt, um Schlüssel und Seiten-ID zu prüfen:

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" }
}]
}]
}]
}'

Eine 200-Antwort heißt, das Log wurde angenommen. Öffnen Sie Observability → Logs, und es ist innerhalb weniger Sekunden da.

Jede Sprache, ohne Codeänderungen

Jedes OpenTelemetry-SDK liest dieselben Umgebungsvariablen. Damit sendet die Auto-Instrumentierung Traces, Metriken und Logs, ohne dass Sie Ihren Code anfassen:

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"

Das Leerzeichen nach Bearer wird als %20 geschrieben, weil die Header-Variable URL-kodiert ist. Starten Sie Ihre App dann mit der Auto-Instrumentierung ihrer Sprache:

# 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 und PHP haben eigene Auto-Instrumentierung und lesen dieselben Variablen. Siehe die Zero-Code-Anleitungen von OpenTelemetry.

Node.js

Um Logs aus Ihrem Code zu senden, installieren Sie das Logs-SDK:

npm install @opentelemetry/api-logs @opentelemetry/sdk-logs \
@opentelemetry/exporter-logs-otlp-http @opentelemetry/resources

Richten Sie es einmal beim Start Ihrer App ein:

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())

Sie loggen schon mit pino oder winston? Behalten Sie sie. pino-opentelemetry-transport und @opentelemetry/winston-transport senden jede bestehende Logzeile unverändert.

Python

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Das SDK hängt sich in Pythons logging-Modul ein, Ihre bestehenden logging-Aufrufe werden also unverändert gesendet:

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

Sie betreiben schon den OpenTelemetry Collector? Fügen Sie Instatus als Exporter hinzu und lassen Sie Ihre Apps, wie sie sind:

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]

Der Exporter hängt /v1/logs, /v1/traces und /v1/metrics selbst an, der Endpunkt ist also nur der Host. Um Logdateien zu senden, fügen Sie der Logs-Pipeline einen filelog-Receiver hinzu.

Was Sie senden

Instatus liest diese Felder. Alles andere bleibt als Attribut erhalten, nach dem Sie suchen und filtern können.

FeldWofür
service.name (Ressource)Die Spalte und der Filter Dienst. Setzen Sie es in jeder App, jedem Worker und jedem Job.
bodyDie Lognachricht, die die Freitextsuche durchsucht.
severityText oder severityNumberDie Stufe: fatal, error, warn, info, debug oder trace.
traceId und spanIdVerknüpft ein Log mit seinem Trace, damit Sie zwischen beiden springen können.
AttributeAlles, was Sie ergänzen, etwa customer.id oder http.route. Jedes wird zu einem Filter.

Attribute, die mit instatus. beginnen, sind reserviert und werden beim Eingang ersetzt.

Fehlerbehebung

Sie sehenLösung
401Prüfen Sie den Schlüssel und den Header X-Instatus-Site-Id. Der Besitzer des Schlüssels muss Eigentümer, Admin oder Editor der Seite sein.
400Der Body ist kein gültiges OTLP. Prüfen Sie Content-Type und die JSON-Struktur im Test-Log.
429Das Datenvolumen dieses Monats ist aufgebraucht. Siehe Tarife und Limits.
200, aber nichts erscheintWarten Sie ein paar Sekunden und prüfen Sie dann den Zeitraum. Ein Log mit einem Zeitstempel in der Vergangenheit erscheint nur, wenn der Zeitraum ihn abdeckt.
Gar nichtsSDKs senden in Stapeln. Stellen Sie sicher, dass Ihre App den Provider leert oder herunterfährt, bevor sie sich beendet.

Wenn Sie Ihren API-Schlüssel in den Entwicklereinstellungen neu erzeugen, funktioniert der alte sofort nicht mehr. Aktualisieren Sie also vorher jede App, die ihn nutzt.