データを送信

Instatus は OpenTelemetry(HTTPS 経由の OTLP)でログ、トレース、メトリクスを受け取ります。アプリの接続方法は 2 つあります。どちらかを選んでください。

方法 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 の確認には、ターミナルからのリクエスト 1 回で十分です:

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 (リソース)サービス 列とフィルター。すべてのアプリ、ワーカー、ジョブで設定してください。
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 はまとめて送信します。アプリが終了する前にプロバイダーをフラッシュまたはシャットダウンしていることを確認してください。

開発者設定で API キーを再生成すると、古いキーはすぐに使えなくなります。先にそのキーを使うすべてのアプリを更新してください。