基本使用法

whatap-go-instは、ビルド時にモニタリングコードを自動的に挿入するCLIツールです。ソースコードを直接修正せずにGoアプリケーションにWhaTapモニタリングを追加できます。

このドキュメントでは、whatap-go-instのインストールと基本的な使用方法を案内します。

Tips

APIを直接使用してモニタリングコードを追加するには、手動計測ガイドを参照してください。

サポート環境

whatap-go-instを使用するには、次の環境が必要です。

項目	要求事項	備考
Goバージョン	1.18以上	計測されたコードビルド時に必要
OS	Linux	amd64, arm64

ノート

whatap-go-instバイナリは、Goのインストールなしで実行できます。ただし、計測されたコードをビルドするにはGo 1.18以上が必要です。

クイックスタート

ステップ1: whatap-go-instをインストール

whatap-go-instのインストール方法は次の3つです。環境に合った方法を選択してください。

Go installインストール (推奨)

Go 1.21以上で推奨されるインストール方法です。

go install github.com/whatap/go-api-inst/cmd/whatap-go-inst@latest

バイナリ直接インストール

Goのインストールなしで直接インストールする方法です。Go 1.18-1.20ユーザーはこの方法を使用してください。

# Linux (amd64)
curl -sSL https://github.com/whatap/go-api-inst/releases/latest/download/whatap-go-inst_linux_amd64.tar.gz | tar xz
sudo mv whatap-go-inst /usr/local/bin/

# Linux (arm64)
curl -sSL https://github.com/whatap/go-api-inst/releases/latest/download/whatap-go-inst_linux_arm64.tar.gz | tar xz
sudo mv whatap-go-inst /usr/local/bin/

ソースからビルド

git clone https://github.com/whatap/go-api-inst.git
cd go-api-inst
go build -o whatap-go-inst .

ステップ3: ビルドおよび実行

# モニタリングコードが自動的に挿入されてビルドされます
whatap-go-inst go build ./...

# 実行
./myapp

完了!

これでWhaTapモニタリングサービスでデータを確認できます。

💡 元のコードを全く変更したくない場合は?

wrapモードを使用すると、whatap_inst.tool.goファイルやgo.modの変更なしでビルドできます。

# initなしで直接ビルド
whatap-go-inst go --wrap build ./...

wrapモードの特徴

元のプロジェクトファイルを変更しない
最初のテストや一時適用に便利
毎回--wrapオプションが必要

whatap-go-inst詳細説明

動作原理

whatap-go-instは、ビルド時にソースコードを分析してモニタリングコードを自動的に挿入します。

1. main()関数初期化

// 変更前
func main() {
    // アプリケーションコード
}

// 変更後
func main() {
    trace.Init(nil)         // 自動追加
    defer trace.Shutdown()  // 自動追加
    
    // アプリケーションコード
}

2. Webフレームワークミドルウェア

// 変更前
r := gin.Default()
r.GET("/api", handler)

// 変更後
r := gin.Default()
r.Use(whatapgin.Middleware())  // 自動追加
r.GET("/api", handler)

3. データベース呼び出し

// 変更前
db, _ := sql.Open("mysql", dsn)

// 変更後
db, _ := whatapsql.Open("mysql", dsn)  // 自動変更

サポートする主要ライブラリ

Webフレームワーク: Gin, Echo, Fiber, Chi, Gorilla Mux, net/http, FastHTTP
データベース: database/sql, sqlx, GORM v1/v2
キャッシュ/NoSQL: Redis (go-redis, Redigo), MongoDB
外部サービス: gRPC, Kafka (Sarama), Kubernetes client-go
ログ: log, logrus, zap

サポートライブラリの完全なリストを表示

分類	サポートライブラリ
Webフレームワーク	Gin, Echo v4, Fiber v2, Chi v5, Gorilla Mux, net/http, FastHTTP
データベース	database/sql, sqlx, GORM v1/v2
Redis	go-redis v8/v9, Redigo
NoSQL	MongoDB
メッセージキュー	Kafka (Sarama - IBM/Shopify)
RPC	gRPC
Kubernetes	client-go
ログ	log, logrus, zap

コマンド

区分	コマンド	説明	主な使用
基本	`whatap-go-inst go build`	モニタリングコードを挿入してビルド	通常ビルド
基本	`whatap-go-inst go run`	モニタリングコードを挿入して実行	開発/テスト
基本	`whatap-go-inst go test`	モニタリングコードを挿入してテスト	ユニットテスト
高度	`whatap-go-inst inject`	計測コードを別ディレクトリに出力	コードレビュー
高度	`whatap-go-inst remove`	挿入されたモニタリングコードを削除	計測解除
ユーティリティ	`whatap-go-inst version`	バージョン確認	バージョンチェック

Tips

whatap-go-inst goの後は、通常のgoコマンドと同じように使用できます。

# 例: 通常のgoコマンドのように使用
whatap-go-inst go build -o myapp -ldflags="-s -w" .

主要オプション

whatap-go-inst goオプション

オプション	説明
`--error-tracking`	エラー追跡コード挿入 (`if err != nil`パターンに`trace.Error`追加)

使用例:

# wrapモード
whatap-go-inst go --wrap build ./...

# エラー追跡を含む
whatap-go-inst go --error-tracking build ./...

inject/removeオプション

オプション	説明
`-s, --src`	ソースコードパス
`-o, --output`	出力ディレクトリ
`--all`	(removeのみ) 手動挿入パターンも削除試行

使用例:

# 計測コードを別途保存
whatap-go-inst inject -s ./src -o ./instrumented

# 計測コードを削除
whatap-go-inst remove -s ./instrumented -o ./clean

グローバルオプション

すべてのコマンドで使用できる共通オプションです。

オプション	説明
`--verbose, -v`	詳細出力 (ファイル別変換内容表示)
`--quiet, -q`	要約のみ出力
`--config`	設定ファイルパス (デフォルト: `.whatap/config.yaml`)
`--report`	JSONレポートファイルパス

使用例:

# 詳細出力
whatap-go-inst -v go build ./...

# 設定ファイル指定
whatap-go-inst --config ./my-config.yaml go build ./...

よくある質問

元のコードが変更されますか?

元のコードは変更されません。whatap-go-instはtmpディレクトリにソースコードをコピーした後、依存関係をダウンロードしてビルドします。

ビルド成果物はwhatap-instrumentedディレクトリに生成されます。

既存のgoコマンドと何が違いますか?

whatap-go-inst go buildは通常のgo buildと同じように動作しますが、ビルド前にモニタリングコードを自動的に挿入します。すべてのオプションとフラグはそのまま使用できます。

# 通常のビルドコマンドと同じように使用
whatap-go-inst go build -o myapp -ldflags="-s -w" .

ビルド時間が遅くなりますか?

tmpディレクトリコピー、依存関係ダウンロード、コード挿入過程により、通常のビルドより時間がかかります。

計測が適用されていないようですが?

次を確認してください:

# ビルドキャッシュ削除後、再ビルド
go clean -cache
whatap-go-inst go build ./...

# デバッグモードで詳細ログ確認
GO_API_AST_DEBUG=1 whatap-go-inst go build ./...

詳細については、自動計測ガイドを参照してください。

Docker環境でも使用できますか?

はい、Dockerfileで同じように使用できます:

FROM golang:1.21 AS builder

WORKDIR /app

# whatap-go-instインストール
RUN go install github.com/whatap/go-api-inst/cmd/whatap-go-inst@latest

# ソースコピー
COPY . .

# 初期化およびビルド
RUN whatap-go-inst go build -o /app/myapp .

FROM alpine:latest
COPY --from=builder /app/myapp /app/myapp
CMD ["/app/myapp"]

詳細については、Dockerインストールガイドを参照してください。

サポート環境​

クイックスタート​

ステップ1: whatap-go-instをインストール​

Go installインストール (推奨)​

バイナリ直接インストール​

ソースからビルド​

ステップ3: ビルドおよび実行​

whatap-go-inst詳細説明​

動作原理​

1. main()関数初期化​

2. Webフレームワークミドルウェア​

3. データベース呼び出し​

サポートする主要ライブラリ​

コマンド​

主要オプション​

whatap-go-inst goオプション​

inject/removeオプション​

グローバルオプション​

よくある質問​

元のコードが変更されますか?​

既存のgoコマンドと何が違いますか?​

ビルド時間が遅くなりますか?​

計測が適用されていないようですが?​

Docker環境でも使用できますか?​

サポート環境

クイックスタート

ステップ1: whatap-go-instをインストール

Go installインストール (推奨)

バイナリ直接インストール

ソースからビルド

ステップ3: ビルドおよび実行

whatap-go-inst詳細説明

動作原理

1. main()関数初期化

2. Webフレームワークミドルウェア

3. データベース呼び出し

サポートする主要ライブラリ

コマンド

主要オプション

whatap-go-inst goオプション

inject/removeオプション

グローバルオプション

よくある質問

元のコードが変更されますか?

既存のgoコマンドと何が違いますか?

ビルド時間が遅くなりますか?

計測が適用されていないようですが?

Docker環境でも使用できますか?