Kirim data

Instatus menerima log, trace, dan metrik melalui OpenTelemetry (OTLP lewat HTTPS). Ada dua cara menghubungkan aplikasi. Pilih salah satu.

Opsi 1: Salin prompt

Cara tercepat jika Anda memakai agen coding seperti Claude Code, Cursor, atau Copilot.

  1. Buka Observability di halaman status Anda.
  2. Di bawah Sertakan, centang yang ingin dikirim: Log, Trace, Metrik. Centang juga Dasbor awal jika nanti Anda ingin dasbor siap pakai untuk layanan Anda.
  3. Klik Salin prompt.
  4. Tempelkan ke agen coding Anda, di proyek aplikasi Anda.
  5. Simpan kunci API Anda di variabel lingkungan INSTATUS_API_KEY, lalu jalankan uji yang disarankan agen.
Kartu penyiapan dengan log, trace, dan metrik yang bisa disertakan serta tombol untuk menyalin prompt

Prompt meminta agen memakai SDK OpenTelemetry resmi untuk bahasa Anda, mempertahankan pustaka logging yang ada, membaca kunci dari variabel lingkungan, dan tidak pernah meng-commit-nya. ID halaman Anda sudah ada di dalamnya.

Opsi 2: Siapkan secara manual

  1. Buka Observability di halaman status Anda.
  2. Klik Siapkan secara manual.
  3. Pilih bahasa Anda: Node.js, Python, Go, Java, .NET, Ruby, PHP, atau OpenTelemetry Collector.
  4. Salin perintah Instal dan jalankan, lalu salin kode Konfigurasi ke aplikasi Anda.
  5. Atur variabel lingkungan INSTATUS_API_KEY ke kunci API Anda dan jalankan aplikasi.
Penyiapan manual dengan Node.js dipilih, menampilkan perintah pemasangan dan kode konfigurasi

Kode di dasbor sudah berisi ID halaman Anda. Contoh yang sama ada di bawah jika Anda lebih suka menyalin dari sini.

Yang dibutuhkan setiap permintaan

ApaNilai
Endpointhttps://otel.instatus.com. Log dikirim ke /v1/logs, trace ke /v1/traces, metrik ke /v1/metrics.
AuthorizationBearer <API_KEY>, dengan kunci milik pemilik, admin, atau editor halaman.
X-Instatus-Site-IdID halaman status tempat data berada.
ProtokolOTLP lewat HTTP, sebagai protobuf atau JSON. Jika SDK Anda memakai gRPC secara default, ganti ke HTTP.

Kunci API Anda memberi akses ke seluruh akun. Simpan di server Anda, dalam variabel lingkungan. Jangan pernah menaruhnya di browser, aplikasi seluler, atau repositori publik.

Temukan kunci API Anda

Buka menu avatar, pilih Pengaturan pengguna, lalu Pengembang, atau langsung ke pengaturan pengembang. Klik Salin di samping kunci.

Kunci API di pengaturan pengembang, dengan tombol untuk menyalinnya

Temukan ID halaman Anda

Jarang diperlukan: prompt dan kode di dasbor sudah memuatnya. Untuk menyalinnya sendiri, klik kanan nama proyek di bagian atas dasbor dan pilih Copy Project ID.

Copy Project ID di menu nama proyek

Kirim log uji

Satu permintaan dari terminal sudah cukup untuk memeriksa kunci dan ID halaman Anda:

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

Respons 200 berarti log diterima. Buka Observability → Log, dan log itu muncul dalam beberapa detik.

Bahasa apa pun, tanpa mengubah kode

Setiap SDK OpenTelemetry membaca variabel lingkungan yang sama. Dengan variabel ini, instrumentasi otomatis mengirim trace, metrik, dan log tanpa menyentuh kode Anda:

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"

Spasi setelah Bearer ditulis %20, karena variabel header dienkode seperti URL. Lalu jalankan aplikasi dengan instrumentasi otomatis untuk bahasanya:

# 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, dan PHP punya instrumentasi otomatis sendiri dan membaca variabel yang sama. Lihat panduan zero-code OpenTelemetry.

Node.js

Untuk mengirim log dari kode Anda, pasang SDK log:

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

Siapkan sekali saat aplikasi dimulai:

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

Sudah mencatat log dengan pino atau winston? Pertahankan saja. pino-opentelemetry-transport dan @opentelemetry/winston-transport mengirim setiap baris log apa adanya.

Python

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

SDK terhubung ke modul logging Python, jadi panggilan logging yang sudah ada dikirim apa adanya:

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

Sudah menjalankan OpenTelemetry Collector? Tambahkan Instatus sebagai exporter dan biarkan aplikasi Anda apa adanya:

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]

Exporter menambahkan /v1/logs, /v1/traces, dan /v1/metrics sendiri, jadi endpoint cukup berisi host. Untuk mengirim file log, tambahkan receiver filelog ke pipeline log.

Yang perlu dikirim

Instatus membaca kolom-kolom ini. Selebihnya disimpan sebagai atribut yang bisa Anda cari dan filter.

KolomDigunakan untuk
service.name (resource)Kolom dan filter Layanan. Atur di setiap aplikasi, worker, dan job.
bodyPesan log, tempat pencarian teks bebas mencari.
severityText atau severityNumberLevel: fatal, error, warn, info, debug, atau trace.
traceId dan spanIdMenautkan log ke trace-nya, agar Anda bisa berpindah di antara keduanya.
AtributApa pun yang Anda tambahkan, seperti customer.id atau http.route. Masing-masing menjadi filter.

Atribut yang diawali instatus. dicadangkan dan diganti saat data tiba.

Pemecahan masalah

Anda melihatSolusi
401Periksa kunci dan header X-Instatus-Site-Id. Pemilik kunci harus pemilik, admin, atau editor halaman.
400Body bukan OTLP yang valid. Periksa Content-Type dan struktur JSON pada log uji.
429Kuota data bulan ini sudah habis. Lihat paket dan batas.
200, tapi tidak ada yang munculTunggu beberapa detik, lalu periksa rentang waktu. Log dengan stempel waktu di masa lalu hanya muncul jika rentang mencakupnya.
Tidak ada sama sekaliSDK mengirim secara batch. Pastikan aplikasi Anda mengosongkan atau mematikan provider sebelum keluar.

Membuat ulang kunci API di pengaturan pengembang langsung menghentikan kunci lama, jadi perbarui dulu setiap aplikasi yang memakainya.