Superlog オンボーディング

ユーザーのプロジェクトに OpenTelemetry トレース、ログ、メトリクスを接続し、テレメトリが Superlog にストリーミングされるようにします。リポジトリ内のすべてのアプリとサービスをカバーします。ユーザーが現在いるアプリだけではありません。

ネイティブ OpenTelemetry API とフレームワークの公式ドキュメントに記載されているブートストラップを優先します。カスタムヘルパーレイヤーより native API を使います。特定のスタックに困ったら OTel ドキュメントをその言語で検索してください。推測で進めないでください。

編集する前に、以下の関連スキルを読んでください：

• otel-onboarding-style — 一般的な OTel の方針。
• otel-python-style — Python サービス向け。
• otel-fastapi-style — FastAPI サービス向け。
• otel-livekit-style — LiveKit エージェント向け。
• otel-nextjs-style — Next.js/Vercel アプリ向け。
• otel-expo-style — Expo / React Native アプリ向け。
• otel-supabase-edge-style — Supabase Edge Functions 向け。
• otel-generic-style — その他すべての言語（Go、Java/Kotlin、Ruby、Rust、.NET/C#、PHP、Elixir、plain Node など）向け。上記に当てはまらない場合のフォールバックです。

ステップ 0 — エンドポイントと公開トークンの処理

OTLP エンドポイントは常に https://intake.superlog.sh であり、ブートストラップソースに直接含めます。

Superlog 公開インジェストトークンは sl_public_ で始まります。プロジェクトごとのスコープを持つ書き込み専用で、アプリケーションソース（ブラウザバンドルとモバイルバンドルを含む）に含めても安全です。PostHog プロジェクトトークン、Sentry DSN、Datadog RUM クライアントトークンと同じように扱ってください。1 つのプロジェクトにテレメトリを送信できますが、データの読み取り、設定の変更、Superlog アカウントへのアクセスはできません。

公開トークンをエンドポイントと一緒に定数としてインラインに配置してください。.env ファイル、デプロイ設定、生成されたシェルコマンドには入れないでください。ソースレベルの設定がオンボーディング方法であり、環境変数の欠落によるデプロイの破損を避けられます。

OTLP エクスポーターにヘッダーが必要な場合は、エクスポーターのコンストラクタを通じて公開トークンを渡してください。superlogHeaders(token) のようなニュートラルなヘルパーを優先して、トークンが 1 つのセットアップブロックにのみ表示されるようにしてください。

2 つのパス、異なる処理：

プロンプトに公開トークンが含まれている場合

呼び出しプロンプトに sl_public_... トークンが含まれている場合は、プレフィックスを検証し、作成するすべてのテレメトリブートストラップファイルにインラインで含めてください。完全なトークンをチャットに出力しないでください。他の公開クライアントトークンと同じようにコード diff に表示されます。

公開トークンがない場合

ローカルで公開トークンを生成し、すぐにサインアップインテントを登録し、並行して作業を続けます。インストールをサインアップでブロックしないでください。

1. sl_public_<base64url相当のランダムバイト列> という形式のランダムプレーンテキスト公開インジェストトークンを生成してください。プレフィックスの後に最低 32 バイトのエントロピーを使用してください。プレーンテキストをメモリに保持して、ブートストラップファイルにインラインで含められるようにしてください。ただし、完全なトークンをチャットに出力することは決してありないでください。

2. keyHash = sha256(plaintextToken) を小文字の 16 進数として計算し、keyPrefix = トークンプレフィックスに続く最初の 6 文字 として計算してください。

3. POST https://api.superlog.sh/api/signup-intents を Content-Type: application/json で実行し、本文は以下の通りです：

   {
     "keyHash": "<sha256 hex>",
     "keyPrefix": "<short public token prefix>",
     "returnTo": null
   }
   

   エージェントランタイムが現在の会話に戻るセーフリターンやディープリンクを公開している場合は、returnTo として渡してください。そうでない場合は null を使用してください。このリクエストにプレーンテキストトークンを含めないでください。

4. レスポンスには id、signupUrl、expiresAt が含まれます。signupUrl をユーザーのデフォルトブラウザで開いてください（open "$signupUrl" / xdg-open "$signupUrl" / start "" "%signupUrl%"）。開くコマンドが無声で失敗した場合のため、URL も出力してください。ユーザーに簡潔に伝えてください：サインアップが開いている、GitHub/Slack がそこで行われ、生成したトークンはユーザーがフローを完了したときにプロジェクトに登録されます。

5. ユーザーがサインアップしている間、ブロックしないでください。 ステップ 1～4 に進んで、ブートストラップソースで生成したプレーンテキストトークンを使用します。サインアップが完了する前に、インジェストがそのトークンを拒否する可能性があります。これは予期された動作です。Web フロー完了まではトークンが要求されていないため、トークンはまだ登録されていません。

ステップ 1 — リポジトリ内のすべてのアプリ/サービスをマッピング

何かをインストルメント化する前に、ここに何があるかを列挙してください。ワークスペースマニフェストをチェックしてください（pnpm-workspace.yaml、ルート package.json の workspaces、go.work、Cargo ワークスペース、Python pyproject.toml ワークスペースセットアップ、apps/* および services/* 規約）。各サービスを識別してください：Web フロントエンド、API、ワーカー、バックグラウンドジョブ、CLI、サンプル/デモアプリ、モバイルアプリ、Supabase、またはサーバー関数。モバイルアプリとサーバーレス/エッジ関数はスコープ内です。これらがクライアント側または短命だからといってスキップしないでください。純粋な型/設定パッケージでランタイムエントリポイントがないものはスキップしてください。実行可能なサービスをスキップしたり、「スコープ外」のままにしたりしないでください。このスコープ内のすべてを完全にインストルメント化してください。フォローアップがない可能性があります。

始める前にリストをユーザーに表示して、修正できるようにしてください。

ステップ 2 — 各サービスに対して native OTel をインストール、ブートストラップ

言語の native OpenTelemetry SDK を使用してください。 公式パッケージが存在する場合、ベンダーラッパーや手作りヘルパーに手を出さないでください。ここで「native」の意味の例：Node サーバー用の @opentelemetry/sdk-node、通常の Next.js/Vercel アプリ用の @vercel/otel（sdk-node は Next の webpack を破壊し、フレームワークブートストラップを見落とします）、Vite/SPA/Expo 用の @opentelemetry/sdk-trace-web + ブラウザ/モバイル互換エクスポーター、Python 用の opentelemetry-instrumentation-* + opentelemetry-sdk、Go 用の go.opentelemetry.io/otel。

幅広いラッパー API を使わないでください。sendSuperlogSpan、recordCounter、recordLog、startTelemetrySpan、withTelemetry などの再利用可能なヘルパーを避けてください。モジュールスコープで native トレーサー/メーター/ロガーを取得し、SDK 自身の API を直接使用してください。TypeScript/JavaScript では、公開されている @superlog/otel-helpers の withSpan ヘルパーを境界付きビジネススパンに使用し、@superlog/otel-helpers を package.json に追加してください。OpenInference/プロバイダーインストルメンテーションが直接監視できる関数全体を startActiveSpan プラス try / catch / finally に展開するのを避けるため、パッケージをインストールできる場合はこれが必須です。プロバイダー SDK 呼び出しの周りでヘルパーを使用しないでください。OpenInference/プロバイダーインストルメンテーションが直接監視できます。エッジランタイムが本当にアップストリーム OTel SDK をロードできない場合は、シムを小さく、プロバイダーに中立的、OTel 形式のままにしてください：tracer.startActiveSpan、span.setAttributes、SpanStatusCode、meter.createCounter、histogram.record。

3 つのシグナルすべてをワイヤリングしてください — トレース、ログ、メトリクス。ログは stdout ではなく OTLP を通じて送信されます — 言語用に OTel ログブリッジをセットアップして、アプリログ（既存のログレベルと構造化フィールド付き）がアクティブな trace_id / span_id を自動的に実行するようにしてください。ユーザーの既存のロガーは引き続き機能します。SDK init だけでは、ログブリッジはカバーされていません。ほとんどの言語 SDK とフレームワークラッパーはトレース（時々メトリクス）をデフォルトでワイヤリングしますが、明示的な LoggerProvider + OTLP ログエクスポーター + ログレコードプロセッサー + 既存ロガーへのブリッジが必要です。例：Python stdlib には LoggerProvider + OTLPLogExporter + ルートロガーにアタッチされた LoggingHandler が必要です（そして既存レコードのトレース相関用に LoggingInstrumentor）；Node には @opentelemetry/sdk-logs + プロジェクトのロガー用インストルメンテーション（pino/winston/bunyan）が必要です；@vercel/otel には logRecordProcessor(s) オプションが必要です — これがなければログはプロセスを出て行きません。関連するスタイルスキルがスタックごとに正確なピースを記載しているので、参照してください。

チェックすべき一般的なログブリッジのミス：

• ハンドラーが名前付きロガーにアタッチされていますが、アプリはルートロガーを使用しています（またはその逆）— 何も流れません。
• デフォルトレベルフィルター（例：WARNING）でユーザーが実際に Superlog に必要な INFO/DEBUG 行を飲み込まれる。
• BatchLogRecordProcessor がシャットダウン時にフラッシュされない → 短命の CLI、サーバーレス、エッジ関数は最後のバッチをドロップします。ランタイムの終了フックに shutdown() / forceFlush() をワイヤリングしてください。
• 既存のベンダートランスポート（Pino → Logtail、Winston → Datadog など）がそのまま残っている場合は問題ありません。予期されたことです — ただし、ロガーから橋をかけていることを確認してください。異なるフォーマッタを通じて同じ行を二重送出する 2 番目のトランスポートを追加しないでください。
• スパンの外側で発行されたログは trace_id / span_id なしで到着します。これは正しく、予期された動作です。ログコールの周りに使い捨てスパンを開始して「修正」しないでください。

ブートストラップルール：

• ブートストラップファイルはすべてのフレームワークインポートの前に実行される必要があります。言語/フレームワークの公式ドキュメントのフック（--import フラグ、instrumentation.ts、main.py インポートの先頭など）を使用してください。
• エンドポイント（https://intake.superlog.sh）と公開インジェストトークンをブートストラップソースに直接インラインで含めてください。process.env.OTEL_EXPORTER_OTLP_* から読み取ったり、.env ファイルを書き込んだりしないでください。（スタックごとの正確な形状についてはフレームワーク固有のスタイルスキルを参照してください。）
• HTTP OTLP エクスポーターを使用してください、gRPC ではなく。gRPC はネイティブバインディングを取得し、バンドラーを破壊し、コンテナを複雑にします。
• プロジェクトの既存パッケージマネージャーを使用してください（ロックファイルで検出）。
• べき等な編集を優先してください。設定ファイルが既に存在する場合は、上書きするのではなく編集してください。
• すべてのサービスの OTel リソースにリソース属性を設定してください：service.name、service.version、deployment.environment.name、および vcs.repository.url.full — リポジトリの正規 https URL（例：https://github.com/acme/api）。リポジトリ URL は重要なもので、SDK init で service.name と一緒にハードコードして問題ありません。ビルドプラットフォームがスラッグを公開している場合（Vercel VERCEL_GIT_REPO_OWNER/VERCEL_GIT_REPO_SLUG、Railway RAILWAY_GIT_REPO_OWNER/RAILWAY_GIT_REPO_NAME）、環境から読み取ることを優先してください。また、vcs.ref.head.revision（コミット SHA）をランタイムがすでに注入するもの（VERCEL_GIT_COMMIT_SHA、RAILWAY_GIT_COMMIT_SHA、GITHUB_SHA、SOURCE_COMMIT、GIT_COMMIT、HEROKU_SLUG_COMMIT など）から best-effort で設定してください。実行中のプロセスから git にシェルアウトしないでください。SHA をスキップするのは構いませんが、URL をスキップするのは構いません。OTel セマンティック規約キーを正確に使用してください — git.repo / app.repo_url を作り出さないでください。

フレームワークルール：

• Next.js/Vercel： ブートストラップとして instrumentation.ts と @vercel/otel の registerOTel(...) を使用してください。リポジトリがその構造をすでに使用していてかつ拡張していない限り、raw @opentelemetry/sdk-node / NodeSDK ブートストラップを置き換えないでください。ルートハンドラー内でのみ @opentelemetry/api トレーサー/メーターを使用してください。ここで auto-instrumentation は盲目です。registerOTel はデフォルトではログをエクスポートしません — @opentelemetry/exporter-logs-otlp-http から OTLPLogExporter を持つ logRecordProcessor（v1）/ logRecordProcessors（v2）を渡してください。ログはプロセスを出て行きません。インストールされた @vercel/otel メジャーバージョンに合わせてオプション名を一致させてください。
• Expo/React Native： 既存の Expo Go / サポートされていないランタイムガードを保持してください。サポートされたビルドでは、Sentry の前にアプリ登録/ユーザーコードの前に initObservability() を呼び出してください。観測性モジュールにエンドポイント + sl_public_ トークンをインラインで含めてください。Superlog に EXPO_PUBLIC_* 環境変数を使用しないでください。
• Supabase Edge Functions： native Deno OpenTelemetry は、ホストされている Supabase Edge では現在機能しません。上記の小さい OTel 形式のシムパターンを使用してください。エクスポーターエンドポイント/ヘッダーを 1 つのセットアップ領域に保持し、Superlog 固有の関数/ファイル名を避けてください。
• Python/FastAPI： FastAPIInstrumentor.instrument_app(app) のような native インストルメンテーションを使用してください。手動ミドルウェアでリクエスト処理を置き換えるのではなく。
• Python/LiveKit： シャットダウンコールバックを横切るライフサイクルスパンは start_span + trace.use_span(..., end_on_exit=False) を使用し、シャットダウンコールバックで終了する可能性があります。境界付きの作業は、デコレーターまたはコンテキストマネージャーを使用する必要があります。

既存の観測性ベンダーと共存してください。Sentry、Datadog、New Relic、Honeycomb、Logtail、Pino トランスポートなどを削除しないでください。 OTel はそれらと並行します。ユーザーは移行中に両方のシグナルが流れることを明示的に望んでいます。現職者を削除するのはあなたの決定ではありません。

ステップ 3 — ビジネス操作の周りにカスタムスパン、メトリクス、ログを追加

Auto-instrumentation は HTTP 入出力、DB クエリ、フレームワークライフサイクルを提供します。これはフロアで、天井ではありません。プロジェクトを読んで、人間のオペレーターが何か問題に見えたときに実際に見たい操作を見つけてください。

トレース

すべての重要なビジネス操作をアクティブスパンでラップしてください。Auto-instrumented スパンは存在する場所で問題ありません — ただし、操作がまだスパンを取得していない場合は、1 つを追加してください。

• 命名：domain.verb（order.process、payment.charge、email.send、agent.run、interview.create、job.<type>）。

• 属性：エンティティ ID（order.id、user.id、workspace.id、tenant.id）、カウント、キーブール値分岐の結果、LLM 呼び出し用のモデル名/プロバイダー。

• 例外を記録：span.recordException(err) + 失敗パスで span.setStatus({ code: ERROR })。

• 明確な境界を持つ Python 関数の場合は、@tracer.start_as_current_span("operation.name") を優先してください — 同じ呼び出しがデコレーターとコンテキストマネージャーとして機能し、デコレーター形式は通常、関数全体に対して必要なものです：

  @tracer.start_as_current_span("do_work")
  def do_work():
      print("doing some work...")
  

  デコレーターが適切でない場合はコンテキストマネージャーを使用してください（部分的スコープ、動的スパン名など）。境界付きの作業には、デタッチされた start_span() + 手動 end() を使用しないでください。

• 細かい getter、純粋な変換、内部ヘルパーをスキップしてください — 実際のレイテンシーまたは失敗モードがないすべて。

• 属性に PII を入れないでください（メール、パスワード、トークン、フルリクエストボディ）。

ログ

ログが構造化されていて操作コンテキストを実行していることを確認してください。具体的には、スパン内で発行されるすべてのログ行は trace_id / span_id が入力されている Superlog に到着する必要があり、構造化フィールド（orderId、userId など）は属性として保持されます。トレース/スパンコンテキストはログブリッジまたはインテグレーションによってネイティブに追加されるか、追加の作業が必要な場合があります。

ログをナラティブ（「バッチ整合開始」、「3xx の後に再試行」）と例外イベント用に使用してください。エラーログは、操作が回復できず、手動による介入が必要な場合にのみ発行される必要があります。

メトリクス

ビジネス + パフォーマンス + コストをカバーしてください。3 つのカテゴリを探します：

• ビジネスロジックカウンター。 すべての意味のある状態遷移：created、started、completed、failed、retried。テナントごと、チャネルごと、ステータスごと — 低カーディナリティディメンションのみ（ユーザー/注文 ID は決して）。
• パフォーマンスヒストグラム。 ユーザーが気にする操作のレイテンシー、キューの深さ、バッチサイズ、ペイロードサイズ。プロジェクトがすでに何か（time.perf_counter ブロック、カスタム LatencyTracker、「[TIMING]」ログ行）を持っている場合は、既存のタイミングインストルメンテーションを再利用してください — 2 回測定するのではなく、それらの測定からヒストグラムを発行してください。
• コスト — 特に LLM コスト。 プロジェクトが OpenAI / Anthropic / Google / 任意の LLM プロバイダーを呼び出す場合は、利用可能な OpenInference のようなプロバイダーインストルメンテーションを優先して、native SDK 呼び出しが読みやすいまま。製品ハンドラーに価格設定定数または LLM コスト数学を追加しないでください。Superlog はキャプチャされたプロバイダー/モデル/トークン属性から UI/クエリレイヤーで推定コストを集中的に計算します。プロバイダーインストルメンテーションによってすでにキャプチャされているトークンカウンターの複製を避けてください。

モジュールレベルで 1 度メーターを取得し、モジュールレベルで計器を作成し、ホットパスで増分してください。呼び出しごとに新しいメーターを作成しないでください。

ステップ 4 — アプリが動作することを確認

サービスごと：

1. プロジェクト独自の dev またはビルドコマンドを実行してください（package.json / pyproject / Makefile がすでにワイヤリングしているもの）。OTel インストールまでさかのぼるエラーなしで正常に起動することを確認してください。また、アプリをインポートまたは起動するテレメトリブートストラップスモークを実行してください。プロバイダーセットアップ、エクスポーター構築、ログブリッジ、フレームワークインストルメンテーションがすべて初期化されるため。Python サーバーの場合、これは uv run python -c 'from app.main import app; print(app.title)' のようなインポート/スタートアップコマンドである可能性があります。Node/Next ではリポジトリの build/start パスを使用してください。サーバーの場合、curl でも少なくとも 1 つのルートにヒットして、インストルメンテーションを通じてトラフィックが流れるようにしてください。可能な場合は、静的ヘルスルートだけではなく、インストルメント化された操作を実行するルートを選択してください。CLI の場合は、実コマンドを呼び出してください。アプリ独自のスタートアップが破損している場合は出荷しないでください — これは回帰です。
2. テレメトリがプロセスを出ることを確認します — 3 つのシグナルすべて。 ブラウザサインアップフローが完了した後、dev サーバーからの OTLP POST は /v1/traces、/v1/logs、/v1/metrics のそれぞれに対して 2xx を返す必要があります — これはフルブートストラップがネットワークに到達していることを証明します。トレースパイプラインだけではなく。シグナルは、3 つのパス全体に成功する実行中のアプリ独自の POST です。dev サーバーがシャットダウンする時点です。ログパスを特に強制するには、プロジェクトのロガーをインストルメント化された操作内で呼び出すことを知っているルートをヒット（または CLI コマンドを呼び出し）してから、dev サーバーの送信トラフィック / debug エクスポーター出力で /v1/logs POST を監視してください。サインアップがまだ進行中の場合、生成されたトークンがまだ要求されていないため、ingest からの 401/403 が予期されています。その場合は、ブートストラップがクリーンに初期化されることを確認し、ユーザーに開いているサインアップタブを完了するよう求めてから、アウトバウンド ingest を失敗と見なしてください。サインアップ後に /v1/traces のみが表示