Skip to main content

概要

カスタムログ連携を使用すると、標準化された JSON 形式でアプリケーションのログを Profound のアナリティクスプラットフォームに直接送信できます。この連携はログのバッチ処理をサポートしており、堅牢なバリデーションによってデータ品質を確保するとともに、バリデーションの問題について詳細なフィードバックを提供します。

前提条件

  • Profound Log Ingestion Token
  • アプリケーションまたはインフラストラクチャから HTTP POST リクエストを送信できること

API 仕様

エンドポイント

認証

リクエストヘッダーに Profound Log Ingestion Token を含めます。

リクエスト形式

ログは JSON オブジェクトの配列として送信する必要があります。各ログエントリには、特定のフィールドが必要です。

必須フィールド

  • timestamp - イベントのタイムスタンプ(Unix タイムスタンプまたは ISO 8601 文字列)
  • method - HTTP メソッド(最大 10 文字)
  • host - リクエストのホスト名(最大 255 文字)
  • path - リクエストのパス(最大 2048 文字)
  • status_code - HTTP ステータスコード(範囲: 100-599)
  • ip - クライアントの IP アドレス(最大 45 文字)
  • user_agent - ユーザーエージェント文字列(最大 1024 文字)

任意フィールド

query_params と referer はどちらも任意です。ただし、どちらも指定しない場合、ダッシュボードで人間のリファラルデータは利用できません。
  • query_params - クエリパラメータ(キーは最大 100 文字、値は最大 1000 文字)
  • referer - リクエストのリファラー(最大 2048 文字)
  • bytes_sent - レスポンスサイズ(バイト単位、0 以上である必要があります)
  • duration_ms - リクエストの所要時間(ミリ秒単位、0 以上である必要があります)
各リクエストには最大 1,000 件のログエントリを含めることができます。それより大きなデータセットの場合は、ログを複数のリクエストに分割してください。

実装ガイド

Custom Detected
1

ログをフォーマットする

ログデータを必要な JSON 形式で準備します。
2

リクエストを送信する

主要なプログラミング言語を使用してログを送信する方法は次のとおりです。Python:
Node.js:
3

レスポンスを処理する

API のレスポンスを処理して、取り込みが成功したことを確認するか、エラーに対処します。成功時のレスポンス:
バリデーションエラーを含むレスポンス:

エラー処理

API は 2 つの方法でエラーを処理します。

バリデーションエラー

想定されるバリデーションの問題(無効なタイムスタンプ、不正な形式のデータなど)の場合、API は次のように動作します。
  • バッチ内の有効なエントリの処理を継続します
  • レスポンスの errors 配列にバリデーションエラーを追加します
  • 処理されたエントリとエラーとともに 200 ステータスコードを返します

予期しないエラー

予期しないエラー(サーバーの問題、データベースの問題など)の場合、API は次のように動作します。
  • 500 ステータスコードを返します
  • レスポンスの detail フィールドにエラーメッセージを返します
  • バッチ内のエントリは一切処理されません

ベストプラクティス

  • ログを最大 1,000 件のエントリごとにバッチにまとめてください
  • 失敗したリクエストに対するリトライロジックを実装してください
  • ログの送信にはバックグラウンド処理を使用してください
  • アプリケーションのパフォーマンスへの影響を避けるため、ログは非同期で送信してください
  • ローカルバッファリングの実装を検討してください
  • サイズの大きいペイロードには圧縮を使用してください

サポート

セキュリティに関する考慮事項

  • Log Ingestion Token は安全に保管してください
  • Log Ingestion Token は定期的にローテーションしてください
  • リクエストログに異常なパターンがないか監視してください
  • すべての API リクエストに HTTPS を使用してください