> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 可観測性とトラブルシューティング

> サポート、使用の調整、および非同期メディアデバッグに必要な公開TokenLab識別子をログに記録します。

良好なTokenLabの可観測性は、公開識別子から始まります。あなたのログは「ユーザーが何をリクエストしたのか、TokenLabがどの公開タスクを作成したのか、そしてどのように請求されたのか？」という質問に答えるのに役立つべきですが、プロバイダーのルーティング内部や機密ユーザーデータを露出させてはいけません。

## キャプチャすべき公開識別子

| 識別子                      | 表示される場所                                                      | 使用目的                           |
| ------------------------ | ------------------------------------------------------------ | ------------------------------ |
| `request_id`             | エラーボディ、ダッシュボードログ、使用記録                                        | リクエストレベルのサポートと調整               |
| `id` / `task_id`         | 非同期作成およびステータス応答                                              | 画像、動画、音楽、3Dジョブのポーリング           |
| `poll_url`               | 非同期作成応答                                                      | 優先ステータスURL                     |
| `billing_transaction_id` | 決済時の非ストリーミング応答、非同期タスクステータス応答、使用記録、`X-Billing-Transaction-ID` | コスト調整                          |
| `X-Task-ID`              | 非同期タスク応答ヘッダー                                                 | ヘッダー単位のタスク相関                   |
| 自分のジョブ/ユーザーID            | あなたのアプリケーション                                                 | TokenLabのアクティビティをユーザーフローに結びつける |

プロバイダーのタスクID、上流URL、ルーティングチャネルID、Redisキー、または顧客向けの真実としてプライベート実行メタデータを保存しないでください。

## ログに記録する内容

秘密を漏らさずにリクエストを診断するために十分な情報をログに記録してください：

* エンドポイント、HTTPメソッド、モデル、ステータスコード、タイムスタンプ、レイテンシ。
* 公開識別子：`request_id`、`task_id`、`poll_url`、および`billing_transaction_id`が存在する場合。
* サニタイズされたリクエスト形状：どのフィールドが存在したか、完全なプロンプトやプライベートメディアコンテンツではなく。
* ターミナル非同期ステータス応答、公開エラーフィールドを含む。
* クライアントの再試行回数と、再試行が新しいタスクを作成したか、既存のタスクを再開したか。

明示的な許可がない限り、`Authorization`、APIキー、管理トークン、署名付きURL、プライベートメディアURL、完全なプロンプト、およびユーザーの個人データを常に削除してください。

## トラブルシューティングマトリックス

| 症状                          | 最初に確認すること                                           | 有用なページ                                        |
| --------------------------- | --------------------------------------------------- | --------------------------------------------- |
| `401` または `403`             | APIキー、管理トークン、組織アクセス、キーのスコープ                         | [認証](/ja/authentication)                      |
| `402`                       | 残高、APIキーの支出制限、モデル価格の可用性                             | [請求と価格設定](/ja/guides/billing)                 |
| `429`                       | アカウントティア、エンドポイントのレート制限、再試行の動作                       | [レート制限](/ja/guides/rate-limits)               |
| `400 invalid_request_error` | サポートされていないフィールド、間違ったエンドポイント、必須フィールドの欠如、またはモデル契約の不一致 | [エラーハンドリング](/ja/guides/error-handling)        |
| 非同期タスクが見つからない               | 間違ったAPIキー、古いタスクID、期限切れのタスク、または非公開タスクID              | [非同期ジョブとポーリング](/ja/guides/async-jobs-polling) |
| コストがUIと一致しない                | 決済のタイミングまたは間違った識別子の比較                               | [請求と価格設定](/ja/guides/billing)                 |

## 使用の調整

サーバーサイドの調整にはManagement APIを使用してください：

```bash theme={null}
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
  -H "Authorization: Bearer mt-your-management-token"
```

`GET /v1/management/api-keys/{keyId}/usage`は`scene`、`accessChannel`、`logicalModel`、`modelVendor`、`startDate`、および`endDate`でフィルタリングできます。ダッシュボードページをスクレイピングしたり、上流プロバイダーのタスクIDに依存する代わりに、これらの記録を使用してください。

ストリーミング応答はストリームが送信された後に決済される場合があるため、使用が後で記録される場合でも請求ヘッダーが存在しないことがあります。非同期メディアタスクはターミナルポーリングの後に決済される場合があります。

## サポートパケットテンプレート

サポートに連絡する際は、以下を含めてください：

* `request_id`。
* 非同期作業のための`task_id`と`poll_url`。
* 存在する場合は`billing_transaction_id`。
* エンドポイント、メソッド、モデル、タイムスタンプ、ステータスコード。
* サニタイズされたリクエスト形状と公開エラーボディ。
* あなたの期待する結果とユーザーが実際に見たもの。

TokenLabサポートが明示的に削除されたサンプルを要求しない限り、APIキー、管理トークン、プライベートメディア、完全なプロンプト、プロバイダーURL、チャネルID、または内部ルーティング識別子を含めないでください。

## 操作チェック

* 繰り返しの`401`、`402`、`429`、および`5xx`応答にアラートを出す；通常、異なるオーナーがいます。
* 製品SLAよりも長く非ターミナルのままの非同期ジョブを追跡します。
* 同じユーザージョブIDの重複作成試行を追跡します。
* 完了したジョブをサンプリングし、ユーザーが見えるアセット、使用記録、および保存されたタスク記録が一致することを確認します。

## APIリファレンス

| トピック          | リファレンス                                                          |
| ------------- | --------------------------------------------------------------- |
| エラーハンドリング     | [エラーハンドリング](/ja/guides/error-handling)                          |
| レート制限         | [レート制限](/ja/guides/rate-limits)                                 |
| 請求と価格設定       | [請求と価格設定](/ja/guides/billing)                                   |
| APIキーの使用状況を取得 | [APIキーの使用状況を取得](/ja/api-reference/management/get-api-key-usage) |
| タスクステータスを取得   | [タスクステータスを取得](/ja/api-reference/tasks/get-task-status)          |