SDKリファレンス

インストール

Python

pip install aitracer

要件: Python 3.8以上

PHP

composer require haro/aitracer

要件: PHP 8.0以上

TypeScript / JavaScript

npm install @haro/aitracer
# or
yarn add @haro/aitracer

要件: Node.js 18以上

初期化

AITracer クラス

from aitracer import AITracer

tracer = AITracer(
    api_key="at-xxxx",          # 必須（または環境変数 AITRACER_API_KEY）
    project="my-project",       # プロジェクト名
    enabled=True,               # ログ記録の有効/無効
    sync=False,                 # 同期送信モード
    batch_size=10,              # バッチサイズ
    flush_interval=5.0,         # フラッシュ間隔（秒）
    pii_detection=False,        # PII検出
    pii_action="mask",          # PII検出時のアクション
    base_url="https://api.aitracer.co"  # APIエンドポイント
)

コンストラクタオプション

パラメータ	型	デフォルト	説明
`api_key`	str	-	AITracer APIキー（必須）
`project`	str	None	プロジェクト識別子
`enabled`	bool	True	ログ記録の有効化
`sync`	bool	False	同期送信モード（サーバーレス推奨）
`batch_size`	int	10	バッチ送信のサイズ
`flush_interval`	float	5.0	自動フラッシュ間隔（秒）
`flush_on_exit`	bool	True	終了時の自動フラッシュ
`pii_detection`	bool	False	PII自動検出
`pii_action`	str	"mask"	mask / redact / hash / none
`pii_types`	list	["email", "phone", ...]	検出対象のPIIタイプ

ラッパーメソッド

既存のLLMクライアントをラップして、自動的にログを記録します。

wrap_openai(client)

OpenAIクライアントをラップします。

from openai import OpenAI

client = tracer.wrap_openai(OpenAI())

# 通常通り使用 - 自動でログ記録
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

wrap_anthropic(client)

Anthropicクライアントをラップします。

from anthropic import Anthropic

client = tracer.wrap_anthropic(Anthropic())

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

wrap_gemini(model)

Google Geminiモデルをラップします。

import google.generativeai as genai

model = tracer.wrap_gemini(genai.GenerativeModel("gemini-pro"))

response = model.generate_content("Hello")

手動ログ

自動ラップを使わず、手動でログを記録します。

log(data)

tracer.log({
    "model": "gpt-4",
    "provider": "openai",
    "input_data": {
        "messages": [{"role": "user", "content": "Hello"}]
    },
    "output_data": {
        "content": "Hi there!"
    },
    "input_tokens": 10,
    "output_tokens": 5,
    "latency_ms": 450,
    "status": "success",
    "metadata": {
        "user_id": "user-123",
        "feature": "chat"
    }
})

ログデータフィールド

フィールド	型	必須	説明
`model`	str	Yes	使用モデル名
`provider`	str	Yes	openai / anthropic / gemini / other
`input_data`	dict	No	入力データ
`output_data`	dict	No	出力データ
`input_tokens`	int	No	入力トークン数
`output_tokens`	int	No	出力トークン数
`latency_ms`	int	No	レイテンシ（ミリ秒）
`status`	str	No	success / error
`error_message`	str	No	エラーメッセージ
`metadata`	dict	No	カスタムメタデータ（最大10キー）

セッション管理

ユーザーセッション単位でログをグループ化します。

session(session_id, **kwargs)

with tracer.session(
    session_id="session-abc123",
    user_id="user-456",
    metadata={"channel": "web"}
) as session:

    # セッション内のすべてのリクエストが自動でグループ化
    response1 = client.chat.completions.create(...)
    response2 = client.chat.completions.create(...)

    # フィードバックを記録
    session.thumbs_up()      # 最後のレスポンスに高評価
    session.thumbs_down()    # 最後のレスポンスに低評価
    session.feedback("Great response!")  # テキストフィードバック

セッションオプション

パラメータ	型	説明
`session_id`	str	セッション識別子（必須）
`user_id`	str	ユーザー識別子
`metadata`	dict	カスタムメタデータ

アプリユーザー追跡

アプリユーザー機能を使うと、あなたのAIアプリケーションのエンドユーザー単位で利用状況を追跡できます。ユーザーごとのコスト・使用量を把握し、課金設計や利用制限に活用できます。

Starterプラン以上で利用可能
アプリユーザー分析機能はStarterプラン以上でご利用いただけます。

user_id の指定方法

セッション開始時に user_id を指定する方法が推奨です。

# 推奨: セッションでuser_idを指定
with tracer.session(
    session_id="session-abc123",
    user_id="user-456",       # あなたのアプリのユーザーID
) as session:
    # このセッション内の全リクエストが user-456 に紐づく
    response = client.chat.completions.create(...)

メタデータでの指定

セッションを使わない場合は、リクエストごとにメタデータで指定できます。

# メタデータでuser_idを指定
response = client.chat.completions.create(
    model="gpt-4",
    messages=[...],
    extra_body={
        "aitracer_metadata": {
            "user_id": "user-456"
        }
    }
)

# または set_metadata でグローバルに設定
tracer.set_metadata({"user_id": "user-456"})
response = client.chat.completions.create(...)

ダッシュボードでの確認

指定した user_id は、ダッシュボードの「アプリユーザー」メニューで集計・分析できます。

ユーザー一覧：全ユーザーのリクエスト数・コスト・トークン数・エラー数
ユーザー詳細：モデル別使用量・最近のログ・統計情報
ユーザー検索：user_idでログを検索・フィルタリング

詳細はダッシュボードの使い方 - アプリユーザー分析をご覧ください。

トレース

複数のAPI呼び出しを1つのトレースにグループ化します。

trace(trace_id)

with tracer.trace("request-123") as trace:
    # 複数のAPI呼び出しが同じトレースに属する
    response1 = client.chat.completions.create(...)
    response2 = client.chat.completions.create(...)

    # メタデータを追加
    trace.set_metadata({
        "user_id": "user-456",
        "feature": "summarization"
    })

    # タグを追加
    trace.add_tag("production")
    trace.add_tag("high-priority")

フラッシュ

バッファされたログを即座に送信します。

flush()

# 手動でフラッシュ
tracer.flush()

# Lambda / Cloud Functions の終了前に呼び出し推奨
def handler(event, context):
    try:
        response = client.chat.completions.create(...)
        return response
    finally:
        tracer.flush()  # 必ずフラッシュ

サーバーレス環境での注意
Lambda / Cloud Functions では sync=True を設定するか、終了前に必ず flush() を呼び出してください。

エラーハンドリング

SDKはアプリケーションに影響を与えないよう設計されています。

from aitracer.exceptions import AITracerError, APIError, RateLimitError

try:
    tracer.log({...})
except RateLimitError:
    # レート制限に達した
    pass
except APIError as e:
    # API通信エラー
    print(f"API Error: {e}")
except AITracerError:
    # その他のエラー
    pass

デフォルトでは、SDKのエラーはログ記録の失敗を意味するだけで、アプリケーションの動作には影響しません。