monocle2ai/monocle

Monocle is a framework for tracing GenAI app code. This repo contains implementation of Monocle for GenAI apps written in Python.

Monocle – GenAIアプリの観測性とテスト

何であるか – Monocleは、生成型AIアプリケーションおよびエージェントにOpenTelemetry互換のトレーシングを追加するオープンソースのPython SDKです。LangChain、LlamaIndex、Haystack、Google ADK、Claude CLIなど、人気のフレームワークを自動的にインストルメントし、プロンプト、LLM呼び出し、ツールの実行、ベクトルストアクエリ、エージェント実行メタデータの構造化されたスパンを発行します。コンパニオンパッケージである monocle-test-tools を使うと、出力値だけでなくトレース内容に対してアサーションを行うpytestスタイルのテストを書くことができます。

なぜ重要か – 生成型AIエージェントはしばしばブラックボックスとして扱われ、デバッグ、コスト監視、コンプライアンス、CIテストが困難になります。Monocleはエージェント実行のすべてのステップを可視化可能なタイムラインに変換し、任意のOTLPコレクタに送信したり、JSONとして保存したり、Okahu VS Code拡張機能で可視化したりできます。

主な機能（READMEに記載された内容）

機能	得られるもの
メタモデル	エージェント、プロンプト、応答、ツール、ベクトル操作の標準的なスパン属性を定義するJSONスキーマ。
自動インストルメンテーションアダプタ	LangChain、LlamaIndex、Haystack、Google ADK、Claude CLI、Codex CLI、Copilot、AWS Bedrock、Azure OpenAIなど、多数のGenAIスタックに対応するプラグアンドプレイサポート – 手動でのスパン作成は不要。
OTLP互換エクスポート	任意のOpenTelemetryコレクタにトレースを送信したり、ローカルファイルに書き込んだり、クラウドバックエンド（AWS S3、Azure Blob、Okahuクラウド、PostgreSQL、ClickHouseなど）にプッシュしたりできます。
スコープAPI	コンテキストマネージャー／デコレータヘルパー（`monocle_trace_scope`、`monocle_trace_scope_method`）により、ブロック内のすべてのスパンにビジネス属性（user-id、tenant-id、session-id）を付与できます。
組み込みのオブスカレーション	スパンからのシークレットの自動削除；環境変数（`MONOCLE_OBFUSCATE_ENV_VALUES`、`MONOCLE_OBFUSCATE_EXTRA_PATTERNS`）で設定可能。
ゼロコードラッパーモード	CLIスタイルのエントリポイント（`monocle_apptrace …`）により、ソースコードを変更せずにスクリプトをトレース可能 – Lambdaレイヤーやプラットフォームレベルのインジェクションに有用。
`monocle-test-tools`	pytest拡張機能で、トレース内容に対するアサーションが可能：どのエージェントが実行されたか、どのツールが呼び出されたか、トークン／コスト制限、実行時間、および上位レベルの評価事実（役割遵守、知識保持など）を検証できます。
IDE統合	Okahu VS Code拡張機能はMonocle JSONファイルを読み取り、トークン数とエラーバッジを含むガントチャートスタイルのタイムラインを表示します。
Linux Foundationのガバナンス	プロジェクトはLF AI & Dataの下にホストされ、Apache-2.0ライセンスに従います。

一般的な利用事例

複雑なエージェントのデバッグ – すべてのLLM呼び出しとツール使用を可視化し、回答が誤った原因を特定します。
コストとコンプライアンス監視 – トークン使用量をトレースし、シークレットを自動的に削除；CIでトークン予算制限を強制します。
AIフローのCI/CDテスト – monocle-test-toolsを使って、最終出力だけでなく、エージェントおよびツールの実行順序が正しいことを検証するテストを書きます。
プラットフォームレベルの観測性 – インフラチームはラッパーモードでトレーシングをインジェクションし、SREがすべてのGenAIサービスを一貫した視点で監視できるようにします。
マルチテナントトレーシング – スコープAPIを使ってtenant_idやsession_idでスパンをタグ付けし、ダッシュボードでのフィルタリングを容易にします。

セットアップ方法（READMEからのクイックスタート）

# SDKのインストール
pip install monocle_apptrace

# 一度限りのテレメトリ設定（通常、アプリ起動時に実行）
python - <<'PY'
from monocle_apptrace import setup_monocle_telemetry
setup_monocle_telemetry(workflow_name="my_genai_app")
PY

アプリを実行すると、./monocle/配下にJSONトレースファイルが生成されます（例：monocle_trace_my_genai_app_<trace_id>_<ts>.json）。

テスト用に：

pip install monocle_test_tools

その後、READMEの例に従ってexpectedまたはMonocleValidatorを使用するpytest関数を書きます。

エコシステムと統合

フレームワークアダプタ – LangChain、LlamaIndex、Haystack、Google ADK、Claude CLI、OpenAI Codex CLI、GitHub Copilot、AWS Bedrock Agentcore、Azure AI Foundryなど。
エクスポート先 – stdout、ローカルファイル、メモリ内、Azure Blob、AWS S3、Okahuクラウド、一般的なOTELコレクタ、Google Cloud Storage、PostgreSQL、ClickHouse、Paygentic。
IDE – インタラクティブなタイムラインビュー用のOkahu Trace Visualizer VS Code拡張機能。
言語サポート – 主にPython SDK；TypeScript用の補完リポジトリ（monocle-typescript）がリンクされています。

ライセンス

Apache-2.0（READMEのバッジに記載されています）。

結論 – Monocleは、生成型AIアプリケーションにOpenTelemetryベースの観測性レイヤーを提供し、不透明なエージェント実行を構造化され検索可能なトレースに変換し、AIの振る舞いに対するテスト駆動検証を可能にします。