傳送資料

Instatus 透過 OpenTelemetry(經由 HTTPS 的 OTLP)接收日誌、追蹤和指標。連接應用程式有兩種方式,擇一即可。

方式 1:複製提示詞

如果你使用 Claude Code、Cursor 或 Copilot 等程式設計助理,這是最快的方式。

  1. 在你的狀態頁開啟 Observability。
  2. 在 包含 下勾選要傳送的內容:日誌、追蹤、指標。如果之後想要現成的服務儀表板,也勾選 入門儀表板。
  3. 點選 複製提示詞。
  4. 在應用程式的專案中,把它貼到程式設計助理裡。
  5. 把你的 API 金鑰 放到環境變數 INSTATUS_API_KEY,然後執行助理建議的測試。
設定卡片,可選擇包含日誌、追蹤和指標,並有複製提示詞的按鈕

提示詞會要求助理使用你所用語言的官方 OpenTelemetry SDK、保留現有的日誌函式庫、從環境變數讀取金鑰,並且絕不提交它。你的頁面 ID 已經包含在內。

方式 2:手動設定

  1. 在你的狀態頁開啟 Observability。
  2. 點選 手動設定。
  3. 選擇你的語言:Node.js、Python、Go、Java、.NET、Ruby、PHP 或 OpenTelemetry Collector。
  4. 複製 安裝 下的指令並執行,再把 設定 下的程式碼複製到你的應用程式。
  5. 把環境變數 INSTATUS_API_KEY 設為你的 API 金鑰,然後啟動應用程式。
選擇 Node.js 的手動設定畫面,顯示安裝指令和設定程式碼

儀表板中的程式碼已經填好你的頁面 ID。如果你想從這裡複製,下方有相同的範例。

每個請求需要什麼

項目值
端點https://otel.instatus.com。日誌送往 /v1/logs,追蹤送往 /v1/traces,指標送往 /v1/metrics。
AuthorizationBearer <API_KEY>,使用該頁面擁有者、管理員或編輯者的金鑰。
X-Instatus-Site-Id資料所屬狀態頁的 ID。
通訊協定經由 HTTP 的 OTLP,格式為 protobuf 或 JSON。如果你的 SDK 預設使用 gRPC,請改用 HTTP。

你的 API 金鑰可以存取整個帳號。請把它存放在伺服器上的環境變數中。絕對不要放進瀏覽器、行動應用程式或公開的程式碼儲存庫。

找到你的 API 金鑰

開啟頭像選單,依序選擇 使用者設定 和 開發者,或直接前往開發者設定。點選金鑰旁的 複製。

開發者設定中的 API 金鑰和複製按鈕

找到你的頁面 ID

通常不需要:提示詞和儀表板中的程式碼已經包含它。如果要自己複製,在儀表板頂端的專案名稱上按右鍵,選擇 Copy Project 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.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 會接上 Python 的 logging 模組,因此現有的 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 金鑰後,舊金鑰會立即失效,因此請先更新所有使用它的應用程式。