Wysyłanie danych

Instatus odbiera logi, ślady i metryki przez OpenTelemetry (OTLP po HTTPS). Aplikację można podłączyć na dwa sposoby. Wybierz jeden.

Sposób 1: Skopiuj prompt

Najszybszy sposób, jeśli używasz agenta programistycznego, np. Claude Code, Cursor lub Copilot.

  1. Otwórz Observability na swojej stronie statusu.
  2. W sekcji Uwzględnij zaznacz, co chcesz wysyłać: Logi, Ślady, Metryki. Zaznacz też Dashboard startowy, jeśli później chcesz gotowe pulpity dla swoich usług.
  3. Kliknij Kopiuj prompt.
  4. Wklej go do agenta programistycznego, w projekcie swojej aplikacji.
  5. Zapisz swój klucz API w zmiennej środowiskowej INSTATUS_API_KEY i uruchom test zaproponowany przez agenta.
Karta konfiguracji z logami, śladami i metrykami do wyboru oraz przyciskiem kopiowania promptu

Prompt każe agentowi użyć oficjalnego SDK OpenTelemetry dla Twojego języka, zachować obecną bibliotekę logowania, czytać klucz ze zmiennej środowiskowej i nigdy go nie commitować. Identyfikator Twojej strony już w nim jest.

Sposób 2: Skonfiguruj ręcznie

  1. Otwórz Observability na swojej stronie statusu.
  2. Kliknij Skonfiguruj ręcznie.
  3. Wybierz język: Node.js, Python, Go, Java, .NET, Ruby, PHP lub OpenTelemetry Collector.
  4. Skopiuj polecenie z sekcji Instalacja i uruchom je, a potem skopiuj kod z sekcji Konfiguracja do swojej aplikacji.
  5. Ustaw zmienną środowiskową INSTATUS_API_KEY na swój klucz API i uruchom aplikację.
Ręczna konfiguracja z wybranym Node.js, z poleceniem instalacji i kodem konfiguracji

Kod w panelu ma już wpisany identyfikator Twojej strony. Te same przykłady znajdziesz niżej, jeśli wolisz skopiować je stąd.

Czego potrzebuje każde żądanie

CoWartość
Endpointhttps://otel.instatus.com. Logi trafiają do /v1/logs, ślady do /v1/traces, metryki do /v1/metrics.
AuthorizationBearer <API_KEY>, z kluczem właściciela, administratora lub edytora strony.
X-Instatus-Site-IdIdentyfikator strony statusu, do której należą dane.
ProtokółOTLP po HTTP, jako protobuf lub JSON. Jeśli Twoje SDK domyślnie używa gRPC, przełącz je na HTTP.

Twój klucz API daje dostęp do całego konta. Trzymaj go na swoich serwerach, w zmiennej środowiskowej. Nigdy nie umieszczaj go w przeglądarce, aplikacji mobilnej ani publicznym repozytorium.

Znajdź swój klucz API

Otwórz menu pod awatarem, wybierz Ustawienia użytkownika, a potem Deweloper, albo przejdź od razu do ustawień dewelopera. Kliknij Kopiuj obok klucza.

Klucz API w ustawieniach dewelopera, z przyciskiem kopiowania

Znajdź identyfikator strony

Rzadko jest potrzebny: prompt i kod w panelu już go zawierają. Aby skopiować go samodzielnie, kliknij prawym przyciskiem nazwę projektu na górze panelu i wybierz Copy Project ID.

Copy Project ID w menu nazwy projektu

Wyślij testowy log

Jedno żądanie z terminala wystarczy, by sprawdzić klucz i identyfikator strony:

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

Odpowiedź 200 oznacza, że log został przyjęty. Otwórz Observability → Logi, a pojawi się w ciągu kilku sekund.

Dowolny język, bez zmian w kodzie

Każde SDK OpenTelemetry czyta te same zmienne środowiskowe. Dzięki nim automatyczna instrumentacja wysyła ślady, metryki i logi bez dotykania kodu:

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"

Spację po Bearer zapisuje się jako %20, bo zmienna nagłówków jest kodowana jak URL. Następnie uruchom aplikację z automatyczną instrumentacją dla jej języka:

# 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 i PHP mają własną automatyczną instrumentację i czytają te same zmienne. Zobacz przewodniki zero-code OpenTelemetry.

Node.js

Aby wysyłać logi z kodu, zainstaluj SDK logów:

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

Skonfiguruj je raz przy starcie aplikacji:

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

Logujesz już przez pino lub winston? Zostaw je. pino-opentelemetry-transport i @opentelemetry/winston-transport wysyłają każdą istniejącą linię logu bez zmian.

Python

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

SDK podpina się pod moduł logging Pythona, więc Twoje obecne wywołania logging są wysyłane bez zmian:

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

Masz już OpenTelemetry Collector? Dodaj Instatus jako eksporter i zostaw aplikacje bez zmian:

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]

Eksporter sam dopisuje /v1/logs, /v1/traces i /v1/metrics, więc endpoint to tylko host. Aby wysyłać pliki logów, dodaj odbiornik filelog do potoku logów.

Co wysyłać

Instatus czyta te pola. Wszystko inne zostaje zapisane jako atrybut, po którym można wyszukiwać i filtrować.

PoleDo czego służy
service.name (zasób)Kolumna i filtr Usługa. Ustaw go w każdej aplikacji, workerze i zadaniu.
bodyTreść logu, którą przeszukuje wyszukiwanie tekstowe.
severityText lub severityNumberPoziom: fatal, error, warn, info, debug lub trace.
traceId i spanIdŁączy log z jego śladem, by można było przechodzić między nimi.
AtrybutyWszystko, co dodasz, np. customer.id lub http.route. Każdy staje się filtrem.

Atrybuty zaczynające się od instatus. są zarezerwowane i zastępowane po odebraniu danych.

Rozwiązywanie problemów

WidziszRozwiązanie
401Sprawdź klucz i nagłówek X-Instatus-Site-Id. Właściciel klucza musi być właścicielem, administratorem lub edytorem strony.
400Treść żądania nie jest poprawnym OTLP. Sprawdź Content-Type i strukturę JSON w testowym logu.
429Limit danych na ten miesiąc został wykorzystany. Zobacz plany i limity.
200, ale nic się nie pojawiaPoczekaj kilka sekund, a potem sprawdź zakres czasu. Log ze znacznikiem czasu z przeszłości pojawi się tylko, gdy zakres go obejmuje.
Zupełnie nicSDK wysyłają dane partiami. Upewnij się, że aplikacja opróżnia lub zamyka dostawcę przed zakończeniem.

Wygenerowanie nowego klucza API w ustawieniach dewelopera od razu unieważnia stary, więc najpierw zaktualizuj każdą aplikację, która go używa.