傳送資料
Instatus 透過 OpenTelemetry(經由 HTTPS 的 OTLP)接收日誌、追蹤和指標。連接應用程式有兩種方式,擇一即可。
方式 1:複製提示詞
如果你使用 Claude Code、Cursor 或 Copilot 等程式設計助理,這是最快的方式。
- 在你的狀態頁開啟 Observability。
- 在 包含 下勾選要傳送的內容:日誌、追蹤、指標。如果之後想要現成的服務儀表板,也勾選 入門儀表板。
- 點選 複製提示詞。
- 在應用程式的專案中,把它貼到程式設計助理裡。
- 把你的 API 金鑰 放到環境變數
INSTATUS_API_KEY,然後執行助理建議的測試。

提示詞會要求助理使用你所用語言的官方 OpenTelemetry SDK、保留現有的日誌函式庫、從環境變數讀取金鑰,並且絕不提交它。你的頁面 ID 已經包含在內。
方式 2:手動設定
- 在你的狀態頁開啟 Observability。
- 點選 手動設定。
- 選擇你的語言:Node.js、Python、Go、Java、.NET、Ruby、PHP 或 OpenTelemetry Collector。
- 複製 安裝 下的指令並執行,再把 設定 下的程式碼複製到你的應用程式。
- 把環境變數
INSTATUS_API_KEY設為你的 API 金鑰,然後啟動應用程式。

儀表板中的程式碼已經填好你的頁面 ID。如果你想從這裡複製,下方有相同的範例。
每個請求需要什麼
| 項目 | 值 |
|---|---|
| 端點 | https://otel.instatus.com。日誌送往 /v1/logs,追蹤送往 /v1/traces,指標送往 /v1/metrics。 |
Authorization | Bearer <API_KEY>,使用該頁面擁有者、管理員或編輯者的金鑰。 |
X-Instatus-Site-Id | 資料所屬狀態頁的 ID。 |
| 通訊協定 | 經由 HTTP 的 OTLP,格式為 protobuf 或 JSON。如果你的 SDK 預設使用 gRPC,請改用 HTTP。 |
你的 API 金鑰可以存取整個帳號。請把它存放在伺服器上的環境變數中。絕對不要放進瀏覽器、行動應用程式或公開的程式碼儲存庫。
找到你的 API 金鑰
開啟頭像選單,依序選擇 使用者設定 和 開發者,或直接前往開發者設定。點選金鑰旁的 複製。

找到你的頁面 ID
通常不需要:提示詞和儀表板中的程式碼已經包含它。如果要自己複製,在儀表板頂端的專案名稱上按右鍵,選擇 Copy Project ID。

傳送一筆測試日誌
從終端機發出一個請求,就能檢查金鑰和頁面 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 → 日誌,幾秒內就會看到它。
任何語言,不必改程式碼
每個 OpenTelemetry SDK 都會讀取相同的環境變數。有了它們,自動檢測就能在不改程式碼的情況下傳送追蹤、指標和日誌:
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"
由於標頭變數經過 URL 編碼,Bearer 後面的空格要寫成 %20。接著用該語言的自動檢測啟動應用程式:
# 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 會接上 Python 的 logging 模組,因此現有的 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 金鑰後,舊金鑰會立即失效,因此請先更新所有使用它的應用程式。