エージェントでコードを計装する

エージェントにプロンプトを 1 つ渡すだけです。エージェントがサービスに OpenTelemetry の自動計装を追加し、その向き先を sigiro に設定します。これは Claude Code、OpenCode、Codex で動作します。

このガイドでは、計装がまったく入っていないサービスに OpenTelemetry を追加する方法を、エージェントに編集させながら説明します。以下のプロンプトをエージェントに貼り付けてください。エージェントがフレームワークを検出し、公式の自動計装をインストールし、エクスポーターの向き先を sigiro に設定します。

これは Claude Code、OpenCode、Codex、あるいはファイルを編集してパッケージマネージャーを実行できる任意のエージェントで動作します。

はじめる前に

送信先として sigiro サーバーが必要です。sigiro serve で起動するか、クイックスタートにある Docker コマンドで起動してください。セルフホストのサーバーにはキーは不要です。キーが必要なのはホステッドサービスのみで、そのキーは sk_<tenant>_<random> という形式です。

自動計装は Python、Node.js、Java、.NET、Ruby 向けに提供されています。対象のサービスが Go の場合、このプロンプトは使用しないでください。代わりに Go のセクションへ進んでください。

1. エージェントに次のプロンプトを渡す

エンドポイントを置き換えてください。ホステッドサービスを使用しない場合は、キーの行を削除してください。

Instrument this codebase for sigiro observability.

SIGIRO ENDPOINT: http://localhost:4318  (replace with your OTLP ingest address)
HOSTED API KEY: sk_<tenant>_<random>  (omit entirely for a self-hosted server)

Goal: add OpenTelemetry auto-instrumentation so this service emits traces,
metrics, and logs to sigiro. Make the minimum change that works — prefer
auto-instrumentation over hand-written spans.

Rules:
- Detect the language and framework automatically
- Use official OTel auto-instrumentation where it exists (Python opentelemetry-instrument,
  Java javaagent, Node.js auto-instrumentations-node, etc.)
- If auto-instrumentation is not available for this language/framework, add
  manual OTel SDK spans for HTTP handlers and database calls
- Set OTEL_EXPORTER_OTLP_ENDPOINT to the sigiro OTLP HTTP endpoint (:4318)
- For hosted sigiro only, set OTEL_EXPORTER_OTLP_HEADERS with the tenant bearer token
- Set OTEL_SERVICE_NAME to identify this service (use the existing service name or repo name)
- Use the existing package manager (pip, npm, Maven, Gradle, gem, go get)
- For hosted sigiro, do NOT hardcode the tenant key — read it from SIGIRO_API_KEY
- If a file already initializes the OTel SDK, update it rather than re-initializing
- Add SIGIRO_API_KEY to .env.example only for a hosted deployment

エージェントが誤った言語を検出した場合は、直接指示してください。

Language: <python|nodejs|java|dotnet|ruby>
Framework: <fastapi|express|spring-boot|rails|...>

2. やってはいけないことをエージェントに伝える

ここでエージェントは、必要以上のことをやりがちです。作業を始める前に、次の制限を明示してください。

OTel Collector をインストールしないでください。sigiro がコレクターです。
エンドポイントごとに手書きのスパンを追加しないでください。自動計装がカバーします。
データベース接続文字列やビジネスロジックを変更しないでください。
ダッシュボードやアラート設定をセットアップしないでください。sigiro にはどちらもありません。

タスクの全体はこれだけです。フレームワークを検出し、自動計装をインストールし、その向き先を sigiro に設定することです。

3. 得られるカバレッジを確認する

言語	アプローチ	カバー範囲
Python	`opentelemetry-instrument` CLI + ディストリビューション	HTTP（FastAPI、Flask、Starlette）、DB（psycopg2、asyncpg）、Redis
Node.js	`@opentelemetry/auto-instrumentations-node`	HTTP（Express、Fastify）、DB（pg、mysql2、mongoose）
Java	`opentelemetry-javaagent.jar`	HTTP（サーブレット、Spring）、DB（JDBC）、JVM メトリクス
.NET	`OpenTelemetry.AutoInstrumentation` スタートアップフック	HTTP（ASP.NET Core）、DB（EF Core）
Ruby	`opentelemetry-instrumentation-all` gem	HTTP（Rails）、DB（ActiveRecord）、Sidekiq
Go	`otelc` コンパイル時計装	HTTP サーバースパン、Go ランタイムメトリクス、サードパーティライブラリ

あるライブラリでスパンがまったく取得できない場合は、そのライブラリに限って手動でスパンを追加してください。

Go の場合、この作業をエージェントに任せないでください。Go ではビルドコマンドに接頭辞を付けるだけで、計装済みのバイナリが生成されます。ソースファイルは 1 つも変更しません。ツールは otelc で、OpenTelemetry プロジェクトがビルドしています。このツールは、自分で管理していないサードパーティライブラリも計装します。エージェントは自分のコードしか編集できないため、これはエージェントには不可能です。

お使いのプラットフォーム向けのバイナリを v1.0.1 リリースからダウンロードしてください。このリリースでは、macOS と Linux 向けの arm64 および x86-64 版、Windows 向けの x86-64 版の otelc が公開されています。

curl -fsSL -o otelc https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation/releases/download/v1.0.1/otelc-darwin-arm64
chmod +x otelc
./otelc version

このツールでは go install は使えません。モジュールがコマンドパスを公開していないためです。アセットが提供されていないプラットフォームでは、リポジトリをクローンして make build を実行してください。

続いて、通常のビルドコマンドの前に otelc を付けます。

./otelc go build -o checkout .

初回のビルドでは OpenTelemetry のパッケージをダウンロードするため、通常のビルドより時間がかかります。go.mod ファイルは変更されません。

クイックスタートで使用しているのと同じ 2 つの変数を指定して、バイナリを起動します。

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=checkout \
  ./checkout

バイナリは起動時にトレースプロバイダー、メータープロバイダー、ロガープロバイダーを作成します。ユーザー側の SDK コードは不要です。サービスは HTTP サーバースパンと Go ランタイムメトリクスをレポートします。

制限が 2 つあります。このツールには Go 1.25 以降が必要であり、現在のバージョンは 1.0.1 で、プロジェクトが 2026 年 7 月 14 日にタグ付けしたものです。カバーされるライブラリについては、アップストリームのドキュメントを参照してください。

4. 動作していることを確認する

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=my-service \
  <your-app-start-command>

次に、どのサービスを受信したかを sigiro に問い合わせます。

curl http://localhost:9999/v1/services

実際のトラフィックが発生してから数秒以内にサービスが表示されます。表示された後は、sigiro diagnose my-service が読み取れるデータが揃っています。

サービスが表示されない場合は、次の点を確認してください。ポートを確認します。HTTP は :4318、gRPC は :4317 です。sigiro status を実行して、サーバーが正常であることを確認します。自分のサービスのログを読み、OTel の起動時エラーを確認してください。エクスポーターの設定が誤っている場合、起動時に障害がレポートされるためです。

ホステッドサービスでは、ヘッダーが正確に Authorization: Bearer sk_<tenant>_<random> であることを確認してください。セルフホストのサーバーはすべての認証ヘッダーを無視します。そのため、誤ったキーを指定しても、メッセージも 401 レスポンスもなく失敗します。

次のステップ

クイックスタート — 何がどう変わったのかを尋ねる
エージェント自身のテレメトリを sigiro に送る — Claude Code や Codex の向き先も sigiro にする
ホステッド sigiro にテレメトリを送る — サーバーを自分で運用したくない場合はこちら