# データを送信

Source: https://instatus.com/help/ja/observability/send-logs

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

| At a glance | Details |
| :-- | :-- |
| [最速](https://instatus.com/help/ja/observability/send-logs#方法-1-プロンプトをコピーする) | コーディングエージェント用のプロンプトをコピー |
| [手動](https://instatus.com/help/ja/observability/send-logs#方法-2-手動で設定する) | 言語を選んでコードを貼り付け |
| [エンドポイント](https://instatus.com/help/ja/observability/send-logs#各リクエストに必要なもの) | https://otel.instatus.com と 2 つのヘッダー |
| [テスト](https://instatus.com/help/ja/observability/send-logs#テストログを送る) | curl リクエスト 1 回 |
| [表示されない?](https://instatus.com/help/ja/observability/send-logs#トラブルシューティング) | よくある問題を解決 |

## 方法 1: プロンプトをコピーする

Claude Code、Cursor、Copilot などのコーディングエージェントを使っているなら、これが最速です。

1. ステータスページで **Observability** を開きます。
2. **含める** で、送信するものにチェックを入れます: **ログ**、**トレース**、**メトリクス**。後でサービス向けの既成ダッシュボードを使いたい場合は、**スターターダッシュボード** にもチェックを入れます。
3. **プロンプトをコピー** をクリックします。
4. アプリのプロジェクトで、コーディングエージェントに貼り付けます。
5. [API キー](#api-キーを見つける)を環境変数 `INSTATUS_API_KEY` に設定し、エージェントが提案するテストを実行します。

![送信するログ、トレース、メトリクスを選べるセットアップカードと、プロンプトをコピーするボタン](https://instatus.com/help/observability/setup.png)

プロンプトは、使用言語の公式 OpenTelemetry SDK を使うこと、既存のログライブラリを残すこと、キーを環境変数から読み込み、決してコミットしないことをエージェントに指示します。ページ ID はすでに含まれています。

## 方法 2: 手動で設定する

1. ステータスページで **Observability** を開きます。
2. **手動で設定** をクリックします。
3. 言語を選びます: Node.js、Python、Go、Java、.NET、Ruby、PHP、または OpenTelemetry Collector。
4. **インストール** のコマンドをコピーして実行し、**設定** のコードをアプリにコピーします。
5. 環境変数 `INSTATUS_API_KEY` に [API キー](#api-キーを見つける)を設定し、アプリを起動します。

![Node.js を選んだ手動設定。インストールコマンドと設定コードを表示](https://instatus.com/help/observability/setup-by-hand.png)

ダッシュボードのコードにはページ 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 キーを見つける

アバターメニューを開いて **ユーザー設定**、**開発者** の順に選ぶか、[開発者設定](https://dashboard.instatus.com/developer)に直接移動します。キーの横の **コピー** をクリックします。

![開発者設定の API キーとコピーボタン](https://instatus.com/help/observability/api-key.png)

### ページ ID を見つける

通常は不要です。プロンプトとダッシュボードのコードにすでに含まれています。自分でコピーするには、ダッシュボード上部のプロジェクト名を右クリックし、**Copy Project ID** を選びます。

![プロジェクト名のメニューにある Copy Project ID](https://instatus.com/help/observability/copy-page-id.png)

## テストログを送る

キーとページ ID の確認には、ターミナルからのリクエスト 1 回で十分です:

```bash
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 は同じ環境変数を読みます。これを使えば、自動計装がコードに手を加えずにトレース、メトリクス、ログを送ります:

```bash
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` と書きます。次に、その言語の自動計装でアプリを起動します:

```bash
# 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 のゼロコードガイド](https://opentelemetry.io/docs/zero-code/)を参照してください。

## Node.js

コードからログを送るには、ログ SDK をインストールします:

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

アプリの起動時に一度だけ設定します:

```js
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`](https://www.npmjs.com/package/pino-opentelemetry-transport) と [`@opentelemetry/winston-transport`](https://www.npmjs.com/package/@opentelemetry/winston-transport) が既存のログ行をそのまま送ります。

## Python

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

SDK は Python の `logging` モジュールにつながるので、既存の `logging` 呼び出しはそのまま送られます:

```python
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 をエクスポーターとして追加すれば、アプリはそのままで構いません:

```yaml
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`                       | 今月のデータ枠を使い切りました。[プランと上限](https://instatus.com/help/ja/observability#プランと上限)を参照してください。                    |
| `200` なのに何も表示されない | 数秒待ってから期間を確認してください。過去のタイムスタンプを持つログは、期間に含まれる場合にのみ表示されます。 |
| まったく何も来ない              | SDK はまとめて送信します。アプリが終了する前にプロバイダーをフラッシュまたはシャットダウンしていることを確認してください。                           |

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

- [ログ](https://instatus.com/help/ja/observability/logs): ログを検索、絞り込み、ライブで追跡
- [トレース](https://instatus.com/help/ja/observability/traces): 各リクエストがどこで時間を使っているかを確認
