본문으로 건너뛰기

설정 가이드

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대체 파일명
팁

프로젝트 루트에 .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 (기본값)웹 + 데이터베이스 + 외부 서비스 + 로그모든 패키지 활성화
minimaltrace.Init/Shutdown최소 설정 (프레임워크 미들웨어 제외)
webGin, Echo, Fiber, Chi, Gorilla Mux, net/http, FastHTTP웹 프레임워크만
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"] → 웹 프레임워크 + 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"      # 테스트 데이터
팁

사용자 정의 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"

모든 지원 패키지가 활성화됩니다.

웹과 데이터베이스만​

# .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"

지원 패키지 전체 목록​

웹 프레임워크

패키지명라이브러리삽입 코드
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()
최종 수정: 에