本文へスキップ

設定ガイド

whatap-go-instの設定ファイルと環境変数を使用して計測動作を制御する方法を案内します。Presetで簡単に設定したり、個別パッケージを選択して細かく制御できます。

基本的な使用方法は基本使用法を先に参照してください。

設定ファイル​

ファイル位置​

設定ファイルは次の順序で検索されます。

優先順位位置説明
1--configフラグwhatap-go-inst --config=/path/to/config.yaml
2WHATAP_INST_CONFIG環境変数WHATAP_INST_CONFIG=/path/to/config.yaml
3.whatap/config.yamlプロジェクトルートの.whatapディレクトリ (推奨)
4.whatap/whatap.yaml代替ファイル名
Tips

プロジェクトルートに.whatap/config.yamlファイルを作成して使用することを推奨します。

基本構造​

# .whatap/config.yaml
instrumentation:
  preset: "full"           # Preset選択 (full/minimal/web/database/external/log/custom)
  error_tracking: false    # エラー追跡有効化の有無
  enabled_packages: []     # 追加で有効化するパッケージ
  disabled_packages: []    # 無効化するパッケージ

exclude:                   # 計測除外パターン (オプション)
  - "**/*_test.go"

設定項目​

Presetオプション​

Presetを使用して計測するパッケージグループを簡単に選択できます。

Preset含まれる項目説明
full (デフォルト)Web + データベース + 外部サービス + ログすべてのパッケージを有効化
minimaltrace.Init/Shutdown最小設定 (フレームワークミドルウェアを除く)
webGin, Echo, Fiber, Chi, Gorilla Mux, net/http, FastHTTPWebフレームワークのみ
databasedatabase/sql, sqlx, GORM v1/v2データベースのみ
externalRedis, MongoDB, Kafka, gRPC, Kubernetes外部サービスのみ
loglog, logrus, zapログライブラリのみ
customenabled_packagesで直接指定ユーザー定義

Preset組み合わせ​

Presetとパッケージオプションを組み合わせると、より細かく制御できます。

最終有効化パッケージ = Presetパッケージ + enabled_packages - disabled_packages

組み合わせ例:

  • preset: full + disabled_packages: ["grpc"] → gRPCを除く全体
  • preset: web + enabled_packages: ["sql"] → Webフレームワーク + SQL
  • preset: custom + enabled_packages: ["gin", "sql"] → GinとSQLのみ

環境変数​

設定ファイルの代わりに環境変数でも設定できます。

環境変数説明値デフォルト
GO_API_AST_DEBUGデバッグ出力を有効化1 (有効化), 0 (無効化)0
GO_API_AST_OUTPUT_DIR計測されたソース出力ディレクトリディレクトリパス-
WHATAP_INST_CONFIG設定ファイルパスファイルパス.whatap/config.yaml

設定優先順位​

設定値は次の順序で適用されます。

CLIオプション > 環境変数 > 設定ファイル > 既定値
ソース例優先順位
CLIオプション--error-tracking1 (最高)
環境変数GO_API_AST_DEBUG=12
設定ファイルerror_tracking: true3
既定値false4 (最低)

ファイル除外パターン​

計測から除外するファイルパターンを指定します。

デフォルト除外パターン​

設定ファイルにexcludeパターンを指定しない場合、次のパターンが自動的に適用されます:

パターン説明
**/*.pb.goprotobuf生成ファイル
**/*.pb.gw.gogrpc-gateway生成ファイル
**/*_grpc.pb.gogrpc生成ファイル
**/*.connect.goconnect-go生成ファイル
**/*_generated.go自動生成ファイル
**/*_gen.goコード生成器出力
**/*_test.goテストファイル
vendor/**vendorディレクトリ
.git/**gitディレクトリ
node_modules/**node_modulesディレクトリ
whatap-instrumented/**計測された出力ディレクトリ
ノート

除外理由

  • 生成されたコード (protobuf、grpcなど): コンパイルエラーが発生する可能性
  • テストファイル: プロダクションモニタリングに不要
  • 依存関係ディレクトリ: サードパーティコード

ユーザー定義除外パターン​

excludeパターンを指定すると、既定値を置き換えます。

# .whatap/config.yaml
exclude:
  - "**/*_test.go"
  - "vendor/**"
  - "internal/legacy/**"    # レガシーコードを除外
  - "migrations/**"          # マイグレーションファイルを除外

Globパターン構文​

パターン説明マッチ例
*ファイル名のすべての文字*.go → main.go
**再帰的にすべてのディレクトリ**/test/** → a/b/test/c/d.go
?単一文字test?.go → test1.go
[abc]文字クラスtest[12].go → test1.go

コピー除外ディレクトリ (copy_exclude)​

wrapモード (whatap-go-inst go build) で一時ディレクトリにソースファイルをコピーする際に除外するディレクトリを指定します。

デフォルト除外ディレクトリ​

次のディレクトリは自動的に除外されます:

ディレクトリ説明
.gitGitリポジトリ
.svnSVNリポジトリ
.hgMercurialリポジトリ
node_modulesNode.js依存関係
vendorGo vendorディレクトリ
.ideaJetBrains IDE設定
.vscodeVS Code設定
whatap-instrumented計測されたソース出力
ノート

build、distディレクトリはGoプロジェクトでgo:embedの対象として頻繁に使用されるため、デフォルトで除外されません。

ユーザー定義除外ディレクトリ​

# .whatap/config.yaml
copy_exclude:
  - "tmp"           # 一時ディレクトリ
  - "cache"         # キャッシュディレクトリ
  - "data"          # 大容量データディレクトリ
  - "testdata"      # テストデータ
Tips

ユーザー定義copy_exclude項目はデフォルトリストに追加されます（置き換えではありません）。

exclude vs copy_exclude の違い​

オプション用途適用時点
exclude計測から除外するファイルパターンAST分析時
copy_excludeコピーから除外するディレクトリwrapモードファイルコピー時
  • exclude: _test.go、**/*.pb.goなどのglobパターンで特定ファイルを除外
  • copy_exclude: tmp、cacheなどのディレクトリ名でディレクトリ全体を除外

ログ収集​

ログ収集を有効化するには、次のように設定します。

# .whatap/config.yaml
instrumentation:
  preset: "full"  # ログパッケージを含む
# whatap.conf
logsink_enabled=true
ノート
  • whatap-go-instで計測すると、自動的にTraceLogWriterが挿入されます
  • ログにトランザクションID(@txid)、マルチトランザクションID(@mtid)などが自動的に含まれます
  • TraceLogWriter方式を推奨します（トランザクション連携可能）

設定例​

全体有効化​

# .whatap/config.yaml
instrumentation:
  preset: "full"

すべてのサポートパッケージが有効化されます。

Webとデータベースのみ​

# .whatap/config.yaml
instrumentation:
  preset: "custom"
  enabled_packages:
    - "gin"
    - "echo"
    - "sql"
    - "gorm"

Gin、Echo、database/sql、GORMのみが計測されます。

特定パッケージを除外​

# .whatap/config.yaml
instrumentation:
  preset: "full"
  disabled_packages:
    - "k8s"
    - "grpc"

KubernetesとgRPCを除くすべてのパッケージが計測されます。

エラー追跡を有効化​

# .whatap/config.yaml
instrumentation:
  preset: "full"
  error_tracking: true

if err != nilパターンにtrace.Error(ctx, err)コードが自動的に挿入されます。

// 変更前
if err != nil {
    return err
}

// 変更後
if err != nil {
    trace.Error(ctx, err)  // 自動追加
    return err
}

環境別設定ファイル​

# 開発環境
WHATAP_INST_CONFIG=.whatap/dev-config.yaml whatap-go-inst go build ./...

# プロダクション環境
WHATAP_INST_CONFIG=.whatap/prod-config.yaml whatap-go-inst go build ./...
# .whatap/dev-config.yaml
instrumentation:
  preset: "full"
  debug: true
  error_tracking: true
# .whatap/prod-config.yaml
instrumentation:
  preset: "full"
  error_tracking: true
  debug: false

デバッグモード​

# .whatap/config.yaml
instrumentation:
  debug: true
  preset: "full"

ビルド時に詳細なデバッグ情報が出力されます。

[whatap-go-inst] Config file: .whatap/config.yaml
[whatap-go-inst] Preset: full
[whatap-go-inst] Processing: main.go
[whatap-go-inst]   Added: trace.Init
...

計測コード出力​

# .whatap/config.yaml
instrumentation:
  output_dir: "./instrumented"
  preset: "full"

計測されたソースコードが./instrumentedディレクトリに保存されます。

使用事例:

  • 計測結果のレビュー
  • CI/CDでの計測コード分析

トラブルシューティング​

計測が適用されない場合​

次を確認してください:

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

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

コンパイルエラー発生時​

protobufなどの自動生成ファイルが計測されてエラーが発生する場合があります。excludeパターンを確認してください:

# .whatap/config.yaml
exclude:
  - "**/*.pb.go"
  - "**/*_generated.go"

wrapモードビルドが遅い場合​

copy_excludeに大容量ディレクトリを追加してください:

# .whatap/config.yaml
copy_exclude:
  - "data"
  - "testdata"
  - "tmp"

サポートパッケージ全リスト​

Webフレームワーク

パッケージ名ライブラリ挿入コード
gingithub.com/gin-gonic/ginwhatapgin.Middleware()
echogithub.com/labstack/echo/v4whatapecho.Middleware()
fibergithub.com/gofiber/fiber/v2whatapfiber.Middleware()
chigithub.com/go-chi/chi/v5whatapchi.Middleware
gorillagithub.com/gorilla/muxwhatapmux.Middleware
nethttpnet/httpwhataphttp.Func(), whataphttp.Handler()
fasthttpgithub.com/valyala/fasthttpwhatapfasthttp.Middleware()

データベース

パッケージ名ライブラリ挿入コード
sqldatabase/sqlwhatapsql.Open()
sqlxgithub.com/jmoiron/sqlxwhatapsqlx.Open()
gormgorm.io/gormwhatapgorm.Open()
jinzhugormgithub.com/jinzhu/gormwhatapgorm.Open()

外部サービス

パッケージ名ライブラリ挿入コード
redigogithub.com/gomodule/redigowhatapredigo.Dial()
goredisgithub.com/redis/go-redis/v9whatapgoredis.NewClient()
mongogo.mongodb.org/mongo-driverwhatapmongo.Connect()
saramagithub.com/IBM/saramaKafka Interceptor
grpcgoogle.golang.org/grpcServer/Client Interceptor
k8sk8s.io/client-goconfig.Wrap()

ログライブラリ

パッケージ名ライブラリ挿入コード
logloglog.SetOutput(logsink.GetTraceLogWriter())
logrusgithub.com/sirupsen/logruslogrus.SetOutput(logsink.GetTraceLogWriter())
zapgo.uber.org/zaplogsink.HookStderr()
最終修正：