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

# カスタムログ連携

> このドキュメントでは、Custom Log Integration API を使用してアプリケーションのログを Profound のアナリティクスプラットフォームに直接送信する方法を説明します。

## 概要

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

## 前提条件

* Profound Log Ingestion Token

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

## API 仕様

### エンドポイント

```http theme={null}
POST https://artemis.api.tryprofound.com/v1/logs/custom
```

### 認証

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

```http theme={null}
'x-api-key': 'bot_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 文字)

#### 任意フィールド

<Warning>
  `query_params` と `referer` はどちらも任意です。ただし、どちらも指定しない場合、ダッシュボードで人間のリファラルデータは**利用できません**。
</Warning>

* `query_params` - クエリパラメータ(キーは最大 100 文字、値は最大 1000 文字)

* `referer` - リクエストのリファラー(最大 2048 文字)

* `bytes_sent` - レスポンスサイズ(バイト単位、0 以上である必要があります)

* `duration_ms` - リクエストの所要時間(ミリ秒単位、0 以上である必要があります)

<Tip>
  各リクエストには最大 1,000 件のログエントリを含めることができます。それより大きなデータセットの場合は、ログを複数のリクエストに分割してください。
</Tip>

## 実装ガイド

<img src="https://mintcdn.com/profound-37face47/cWnNS0qcU3zRxQWi/images/custom_setup.png?fit=max&auto=format&n=cWnNS0qcU3zRxQWi&q=85&s=5dfad431ec225ef0cd700f3ffc201494" alt="Custom Detected" width="3680" height="2390" data-path="images/custom_setup.png" />

<Steps>
  <Step title="ログをフォーマットする">
    ログデータを必要な JSON 形式で準備します。

    ```json theme={null}
    [
      {
        "timestamp": "2024-01-11T12:00:00Z",
        "method": "GET",
        "host": "example.com",
        "path": "/products",
        "status_code": 200,
        "ip": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "query_params": {
          "category": "electronics",
          "page": "1"
        },
        "referer": "https://example.com",
        "bytes_sent": 1024,
        "duration_ms": 150
      }
    ]
    ```
  </Step>

  <Step title="リクエストを送信する">
    主要なプログラミング言語を使用してログを送信する方法は次のとおりです。

    Python:

    ```python theme={null}
    import requests
    import json

    logs = [{
        "timestamp": "2024-01-11T12:00:00Z",
        "method": "GET",
        "host": "example.com",
        "path": "/products",
        "status_code": 200,
        "ip": "192.168.1.1",
        "user_agent": "Mozilla/5.0..."
    }]

    response = requests.post(
        "https://artemis.api.tryprofound.com/v1/logs/custom",
        headers={
            "x-api-key": "bot_PROFOUND_LOG_INGESTION_TOKEN",
            "Content-Type": "application/json"
        },
        json=logs
    )

    print(response.json())
    ```

    Node.js:

    ```javascript theme={null}
    const axios = require('axios');

    const logs = [{
        timestamp: "2024-01-11T12:00:00Z",
        method: "GET",
        host: "example.com",
        path: "/products",
        status_code: 200,
        ip: "192.168.1.1",
        user_agent: "Mozilla/5.0..."
    }];

    axios.post('https://artemis.api.tryprofound.com/v1/logs/custom', logs, {
        headers: {
            'x-api-key': 'bot_PROFOUND_LOG_INGESTION_TOKEN',
            'Content-Type': 'application/json'
        }
    })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));
    ```
  </Step>

  <Step title="レスポンスを処理する">
    API のレスポンスを処理して、取り込みが成功したことを確認するか、エラーに対処します。

    成功時のレスポンス:

    ```json theme={null}
    {
      "status": "accepted",
      "message": "Processing X log entries",
      "first_visit_id": "uuid-string",
      "errors": []
    }
    ```

    バリデーションエラーを含むレスポンス:

    ```json theme={null}
    {
      "status": "accepted",
      "message": "Processing 98 log entries",
      "first_visit_id": "uuid-string",
      "errors": [
        "Invalid log format: timestamp out of reasonable range",
        "Invalid log format: status_code must be between 100 and 599"
      ]
    }
    ```
  </Step>
</Steps>

## エラー処理

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

### バリデーションエラー

想定されるバリデーションの問題(無効なタイムスタンプ、不正な形式のデータなど)の場合、API は次のように動作します。

* バッチ内の有効なエントリの処理を継続します

* レスポンスの `errors` 配列にバリデーションエラーを追加します

* 処理されたエントリとエラーとともに 200 ステータスコードを返します

### 予期しないエラー

予期しないエラー(サーバーの問題、データベースの問題など)の場合、API は次のように動作します。

* 500 ステータスコードを返します

* レスポンスの detail フィールドにエラーメッセージを返します

* バッチ内のエントリは一切処理されません

## ベストプラクティス

* ログを最大 1,000 件のエントリごとにバッチにまとめてください

* 失敗したリクエストに対するリトライロジックを実装してください

* ログの送信にはバックグラウンド処理を使用してください

* アプリケーションのパフォーマンスへの影響を避けるため、ログは非同期で送信してください

* ローカルバッファリングの実装を検討してください

* サイズの大きいペイロードには圧縮を使用してください

## サポート

* サポートが必要な場合は [support@tryprofound.com](mailto:support@tryprofound.com) までお問い合わせください

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

* Log Ingestion Token は安全に保管してください

* Log Ingestion Token は定期的にローテーションしてください

* リクエストログに異常なパターンがないか監視してください

* すべての API リクエストに HTTPS を使用してください

***