maple-onboard

Maple のオンボーディング

リポジトリ内のすべてのアプリとサービスに OpenTelemetry のトレース、ログ、メトリクスを接続し、テレメトリを Maple に送信します。ネイティブの OpenTelemetry API と、各フレームワークで文書化されているブートストラップを使用してください。スタックの扱いに迷ったら、その言語の OTel ドキュメントを参照し、推測で進めないでください。

補助スキル

まず maple-onboarding-style（スパンのパターン、リソース属性、フレームワークに関する注意事項、シグナルの品質、検証）を読み、次にリポジトリ内の各スタックに対応するスキルを読んでください：maple-nextjs-style、maple-nodejs-style、maple-python-style、maple-effect-style、maple-go-style、maple-rust-style、maple-java-style、maple-csharp-style、maple-kotlin-style。これらがこのスキルの隣にインストールされていない場合は、このリポジトリで必要なものだけを https://raw.githubusercontent.com/MapleTechLabs/maple/main/skills/<skill-name>/SKILL.md から取得してください。対応するスキルがないスタック（Ruby、Elixir、PHP、Deno など）では、maple-onboarding-style と上流の OTel ドキュメントを使用してください。LLM を呼び出すサービスには、maple-agent-tracing も適用してください。

ステップ 0：リージョン、エンドポイント、キー

キーは発行されたリージョンでのみ機能します。別のリージョンでは 401 が返されます。

リージョン	取り込みエンドポイント	ダッシュボード	MCP サーバー
US（デフォルト）	https://ingest.maple.dev	https://app.maple.dev	https://api.maple.dev/mcp
EU	https://ingest.eu.maple.dev	https://app.eu.maple.dev	https://api.eu.maple.dev/mcp

リージョンは次の順で選択してください：プロンプト内の取り込みエンドポイント（記載どおりに使用）、EU への言及または eu.maple.dev URL、それ以外は US。以下の <dashboard> と <mcp> は、そのリージョンのホストを指します。

エンドポイントと取り込みキーはブートストラップのソースに直接記述してください。 キーはプロジェクト単位で、書き込み専用です（Sentry DSN のようなものです）。.env ファイル、process.env.OTEL_EXPORTER_OTLP_*、デプロイ設定への組み込みは使用しないでください。公開キー（maple_pk_…）は、ブラウザーやモバイルを含め、どこでも安全に使用できます。秘密キー（maple_sk_…）はサーバー専用です。

• プロンプトに公開キーがある場合： すべてのブートストラップファイルに直接記述してください。
• プロンプトに秘密キーがある場合： サーバーのブートストラップファイルにのみ使用してください。ブラウザーとモバイルのコードでは MAPLE_TEST を使用し、そこを公開キーに置き換えるようユーザーに伝えてください（公開キーはサーバーでも使用できるため、1 つのキーでリポジトリ全体をカバーできます）。
• キーがない場合： センチネル MAPLE_TEST を直接記述してください。どちらのリージョンでもこれに対して 200 が返され、データは保存されないため、ブートストラップを最後まで実行できます。作業を始める前に、ユーザーへ簡潔に次のように伝えてください：「ブートストラップを実行できるよう、プレースホルダーとして MAPLE_TEST を使用します。Settings → Ingestion（/settings?tab=ingestion）から公開取り込みキーをコピーするか、まず /sign-up でアカウントを作成し、作成するファイル内の MAPLE_TEST を検索して置換してください。」その後は作業を続けてください。サインアップを待たないでください。

ステップ 1：すべてのサービスを洗い出す

ワークスペースのマニフェスト（pnpm/bun/npm ワークスペース、go.work、Cargo、Python ワークスペース）と apps/* / services/* から、Web フロントエンド、API、ワーカー、バックグラウンドジョブ、CLI、デモアプリ、モバイルアプリ、サーバーレス関数、エッジ関数をすべて列挙してください。ランタイムのエントリーポイントがないパッケージのみを除外します。この作業中にすべてを計装してください。後続の作業がない場合もあります。リストを表示してユーザーが修正できるようにしてから、返答を待たずに続行してください。

ステップ 2：ネイティブの OTel をインストールし、各サービスをブートストラップする

言語に対応したネイティブ SDK を使用します。

• Node サーバー：@opentelemetry/sdk-node。Next.js のサーバー側：instrumentation.ts で @vercel/otel。
• ブラウザーのフロントエンド（Vite、SPA、Next.js クライアント）：@maple-dev/browser（トレース、エラー、セッションリプレイで同じ session.id を共有します）。
• Expo / React Native：OTLP HTTP エクスポーターと @opentelemetry/sdk-trace-web。
• Python：opentelemetry-sdk + opentelemetry-instrumentation-*。Go：go.opentelemetry.io/otel。Effect：@maple-dev/effect-sdk。

ルール：

• ブートストラップは、ドキュメントに記載されたフック（--import、instrumentation.ts、main.py の先頭）を通じて、フレームワークをインポートする前に実行します。
• OTLP エクスポーターは HTTP を使用し、gRPC は使用しません。
• サーバーではトレース、ログ、メトリクスを取得します。ログは、既存のロガーの下で言語のログブリッジを介して OTLP に送信し、trace_id / span_id を含めます。
• service.name、service.version、deployment.environment.name、vcs.repository.url.full（サーバーでは必須）、vcs.ref.head.revision（可能な範囲で設定）を設定します。
• ラッパー API（sendMapleSpan、recordCounter、withTelemetry）は使用しません。モジュールスコープのトレーサーとメーター、および SDK 自体の呼び出しを使用します。
• リポジトリのパッケージマネージャーを使用します。既存の設定を編集し、上書きしないでください。
• 既存のベンダー（Sentry、Datadog、New Relic、Pino transports など）は維持します。OTel はそれらと併用します。

ブラウザーの初期化と CORS、Expo、Workers、FastAPI など、フレームワークごとの詳細は、maple-onboarding-style の「Framework notes」と各スタックのスキルに記載されています。

ステップ 3：ビジネススパン、ログ、メトリクス

自動計装は最低限です。コードを読み、maple-onboarding-style の「Business signals」に従って、次を追加します。

• スパン：すべての重要なビジネス操作（order.process、payment.charge、job.<type>）を囲みます。エンティティ ID と結果を属性として設定し、例外を記録し、失敗時は Error ステータスを設定し、必ず終了します。単純なヘルパーは対象外です。PII は含めません。
• ログ：構造化し、トレースと関連付けます。手動での対応が必要な場合に限り、エラーレベルを使用します。
• メトリクス：状態遷移にはカウンター、レイテンシーとサイズにはヒストグラムを使用し、カーディナリティの低いディメンションのみを使用します。

ステップ 4：検証

サービスごとに、次を確認します。

1. プロジェクト独自の開発またはビルドコマンドで引き続き正常に起動し、スモークテスト（アプリを起動またはインポートしてから、計装済みのルートへのリクエストを 1 回送るか、実際の CLI コマンドを 1 回実行する）でブートストラップが初期化されること。起動の失敗はリグレッションです。修正してください。
2. テレメトリーがプロセス外に送信されること：エクスポーター診断を有効にして実行し、シャットダウン時のフラッシュ後にエクスポートエラーがないことを確認します。言語ごとの設定と 401 が発生した場合の対処方法は、maple-onboarding-style の「Verify export」を参照してください。
3. 実際のキーと Maple MCP ツールを使用し、約 1 分待ってから list_services を呼び出し、各 service.name を確認します。次に audit_setup を実行し、報告された問題を修正します。何も保存しない MAPLE_TEST では、この手順を省略します。MCP を利用できない場合は、データの到着状況は「Settings → Ingestion」で確認できることをユーザーに伝えてください。

ブートストラップが読み込まれても、エクスポートされなければ完了ではありません。

ステップ 5：引き継ぎ

• 変更内容： パッケージ、ファイル、計測対象の業務範囲と指標、既存のまま残したベンダーを、3～7個の短い箇条書きで説明します。@maple-dev/browser を追加した場合は、入力値がマスキングされた状態でセッションリプレイが有効になっていること（replay: { enabled: false } で無効化できます）、訪問者 ID が localStorage と Cookie に保存されること（privacy: { persistVisitorId: false } で無効化できます）を伝えます。
• プレースホルダー： MAPLE_TEST がインラインのままの場合は、ユーザーに次のように伝えます。「インストールを最初から最後まで完了できるよう、ブートストラップでは MAPLE_TEST をプレースホルダーとして使用しています。Settings → Ingestion（/settings?tab=ingestion）から公開取り込みキーをコピーしてください。Maple アカウントをまだお持ちでない場合は、まず /sign-up で作成してください。その後、私が編集したファイル内の MAPLE_TEST を検索して置換し、再デプロイしてください。組織が EU リージョン（app.eu.maple.dev）にある場合は、ingest.maple.dev を ingest.eu.maple.dev に置き換えるか、Maple SDK で region: "eu" を設定してください。」EU エンドポイントを使用した場合は、EU に関する文は省きます。
• デプロイ： 通常どおりデプロイします。設定は不要です。キーはソースに含まれています。

ステップ 6：Maple MCP

Maple MCP ツールがすでに <mcp> に接続されている場合はスキップします（別のリージョンのサーバーは 401 を返すか、別の組織のデータを読み取ります）。それ以外の場合は、実行を提案し、事前に確認します：claude mcp add --transport http maple <mcp>。実行せずに、Codex の場合は codex mcp add maple --url <mcp> を案内し、Cursor などでは /mcp のスニペットをコピーするよう伝えます。

厳守事項

• プロジェクトルート外のファイルは変更しないでください。コミット、プッシュ、PR の作成は行わないでください。
• 秘密鍵（maple_sk_…）をブラウザーやモバイルのコードに含めないでください。
• ユーザーから依頼がない限り、既存のオブザーバビリティベンダーを削除しないでください。
• インストルメンテーションが原因で開発コマンドまたはビルドコマンドが失敗した場合は、修正するか、その旨を報告してください。