コアガイド
可観測性とトラブルシューティング
サポート、使用の調整、および非同期メディアデバッグに必要な公開TokenLab識別子をログに記録します。
良好な TokenLab の可観測性は、公開識別子から始まります。ログは「ユーザーが何をリクエストしたのか、TokenLab がどの公開タスクを作成したのか、そしてどのように請求されたのか？」という質問に答えられるようにしつつ、機密性の高いプロバイダー情報やユーザーデータを露出させないでください。
リクエストから調査、サポートへ
-
リクエストの所属ワークスペースでリクエストを開き、Request ID を探して行を選択します。
-
詳細全体を専用ページで開けます。一覧に戻るとフィルターが復元されます。リンクで他のワークスペースへの権限が付与されることはありません。権限のあるアカウントを使用してください。
-
保留中や不明な状態では、まず進行状況を更新します。失敗や応答の中断では、表示される調査操作からアプリ内 Agent を起動できます。元のモデルリクエストは再送されません。正常に成功したリクエストは、通常は調査不要です。
-
解決しない場合は、リクエストや調査から人によるサポートを選択します。プレビューと、利用可能なリクエスト・会話へのリンクを確認し、私的な内容を削除して明示的に送信してください。調査やプレビューだけではサポートに送信されません。
-
送信確認を保存し、サポートの同じ会話で返信や追加情報をやり取りしてください。重複した依頼は不要です。
キャプチャすべき公開識別子
| 識別子 | 表示される場所 | 使用目的 |
|---|---|---|
request_id | エラーボディ、ダッシュボードログ、使用記録 | リクエストレベルのサポートと調整 |
id / task_id | 非同期作成およびステータス応答 | 画像、動画、音楽、3Dジョブのポーリング |
poll_url | 非同期作成応答 | 優先ステータスURL |
billing_transaction_id | 決済時の非ストリーミング応答、非同期タスクステータス応答、使用記録、X-Billing-Transaction-ID | コスト調整 |
X-Task-ID | 非同期タスク応答ヘッダー | ヘッダー単位のタスク相関 |
| 自分のジョブ/ユーザーID | あなたのアプリケーション | TokenLabのアクティビティをユーザーフローに結びつける |
プロバイダーのタスク ID、プロバイダー URL、プロバイダー識別子、Redis キー、または機密性の高い実行メタデータを顧客向け記録として保存しないでください。
ログに記録する内容
秘密を漏らさずにリクエストを診断するために十分な情報をログに記録してください：
- エンドポイント、HTTPメソッド、モデル、ステータスコード、タイムスタンプ、レイテンシ。
- 公開識別子：
request_id、task_id、poll_url、およびbilling_transaction_idが存在する場合。 - サニタイズされたリクエスト形状：どのフィールドが存在したか、完全なプロンプトやプライベートメディアコンテンツではなく。
- ターミナル非同期ステータス応答、公開エラーフィールドを含む。
- クライアントの再試行回数と、再試行が新しいタスクを作成したか、既存のタスクを再開したか。
明示的な許可がない限り、Authorization、APIキー、管理トークン、署名付きURL、プライベートメディアURL、完全なプロンプト、およびユーザーの個人データを常に削除してください。
トラブルシューティングマトリックス
| 症状 | 最初に確認すること | 有用なページ |
|---|---|---|
401 または 403 | APIキー、管理トークン、組織アクセス、キーのスコープ | 認証 |
402 | 残高、APIキーの支出制限、モデル価格の可用性 | 請求と価格設定 |
429 | アカウントティア、エンドポイントのレート制限、再試行の動作 | レート制限 |
400 invalid_request_error | サポートされていないフィールド、間違ったエンドポイント、必須フィールドの欠如、またはモデル詳細の不一致 | エラーハンドリング |
| 非同期タスクが見つからない | 間違ったAPIキー、古いタスクID、期限切れのタスク、または非公開タスクID | 非同期ジョブとポーリング |
| コストがUIと一致しない | 決済のタイミングまたは間違った識別子の比較 | 請求と価格設定 |
使用の調整
サーバーサイドの調整にはManagement APIを使用してください：
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、model、modelVendor、startDate、およびendDateでフィルタリングできます。ダッシュボードページをスクレイピングしたり、上流プロバイダーのタスクIDに依存する代わりに、これらの記録を使用してください。
ストリーミング応答はストリームが送信された後に決済される場合があるため、使用が後で記録される場合でも請求ヘッダーが存在しないことがあります。非同期メディアタスクはターミナルポーリングの後に決済される場合があります。
サポートパケットテンプレート
サポートに連絡する際は、以下を含めてください：
request_id。- 非同期作業のための
task_idとpoll_url。 - 存在する場合は
billing_transaction_id。 - エンドポイント、メソッド、モデル、タイムスタンプ、ステータスコード。
- サニタイズされたリクエスト形状と公開エラーボディ。
- あなたの期待する結果とユーザーが実際に見たもの。
TokenLab サポートが明示的にマスク済みサンプルを要求しない限り、API キー、管理トークン、プライベートメディア、完全なプロンプト、プロバイダー URL、チャネル ID、または非公開の診断識別子を含めないでください。
操作チェック
- 繰り返しの
401、402、429、および5xx応答にアラートを出す；通常、異なるオーナーがいます。 - 製品SLAよりも長く非ターミナルのままの非同期ジョブを追跡します。
- 同じユーザージョブIDの重複作成試行を追跡します。
- 完了したジョブをサンプリングし、ユーザーが見えるアセット、使用記録、および保存されたタスク記録が一致することを確認します。
APIリファレンス
| トピック | リファレンス |
|---|---|
| エラーハンドリング | エラーハンドリング |
| レート制限 | レート制限 |
| 請求と価格設定 | 請求と価格設定 |
| APIキーの使用状況を取得 | APIキーの使用状況を取得 |
| タスクステータスを取得 | タスクステータスを取得 |