API 가이드

이 문서에서 기술된 예제 코드는 github.com/whatap/go-api-example 저장소에서 확인할 수 있습니다.

다운로드

패지키 및 관련 종속성(dependency)을 다운로드하세요.

go get github.com/whatap/go-api

시작하기

init, shutdown

trace.Init() 함수를 이용해 모니터링 모듈을 시작하세요. defer trace.Shutdown()으로 모니터링 종료를 보장합니다.

Go
import "github.com/whatap/go-api/trace"

func main(){
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()

    ...
}

func Init(m map[string]string)

map[string]string 형식을 애플리케이션 초기에 설정할 수 있습니다. 또는 whatap.conf 파일에 설정할 수 있습니다. 에이전트와 TCP 접속이 정상적으로 이루어져야 성능 정보를 와탭 수집 서버로 보낼 수 있습니다. 기본 접속 정보로 127.0.0.1:6600을 통해 TCP로 통신합니다.

접속 정보를 변경하려면 Init 함수에 설정을 전달하거나 whatap.conf 파일에 설정하고 애플리케이션을 재시작하세요.

Go
m := make(map[string]string)
m["net_ipc_host"] = "127.0.0.1"
m["net_ipc_port"] = "6601"

trace.Init(m)

whatap.conf
accesskey={액세스 키}
whatap.server.host={수집 서버 IP 주소}
net_ipc_host=127.0.0.1
net_ipc_host=6600

Context

에이전트는 성능 정보를 트랜잭션 단위로 수집합니다. 트랜잭션의 구분은 whatap context(trace.TraceCtx)가 포함된 context를 기준으로 합니다. 트랜잭션에 연계되지 않는 성능 정보는 수집을 무시하거나 통계 정보로만 수집합니다.

트랜잭션 생성

go-api/trace 모듈의 Start, StartWithReqest 함수로 whatap context를 생성합니다. context 내부에 whatap 키로 TraceCtx 정보를 설정합니다.

Go
var traceCtx *TraceCtx
traceCtx.Txid = keygen.Next()
ctx = context.WithValue(ctx, "whatap", traceCtx)

트랜잭션, SQL, DBConnection, 외부 HTTP request, 일반 함수 추적 등의 API에서 시작 시점에는 반드시 whatap 키로 TraceCtx 객체가 존재하는 Context가 필요합니다.

트랜잭션 추적

웹 요청과 응답까지의 트랜잭션과 일반적인 작업 단위의 트랜잭션을 모두 추적합니다. 시작 및 종료 함수로 구성되어 있습니다. 하나의 트랜잭션으로 인식되어 히트맵 위젯에서 상세 보기와 TPS, 응답시간, 평균 응답시간 등의 통계 지표를 확인할 수 있습니다.

설정을 통해서 HTTP 파라미터, HTTP 헤더 정보를 수집할 수 있습니다.

웹 트랜잭션 추적

Go
http.HandleFunc("/index", func(w http.ResponseWriter, r *http.Request) {
    ctx, _ := trace.StartWithRequest(r)
    defer trace.End(ctx, nil)
}

trace.Func(), trace.HandlerFunc()
- net/http의 Handle, HandFunc을 래핑한 함수
- trace.StartWithRequest, trace.End를 동일하게 진행합니다.
- 웹 트랜잭션의 이름은 RequestURI로 설정됩니다.

trace.Step()

사용자가 전달하는 문자열을 프로파일 정보에 출력하는 기능을 제공합니다.

Go
http.HandleFunc("/wrapHandleFunc", trace.Func(func(w http.ResponseWriter, r *http.Request) {
    ...
}))

Go
http.Handle("/wrapHandleFunc1", trace.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    ...
}))

일반 트랜잭션 추적

Go
func main() {
    ...

    ctx := context.Background()
    ctx, _ := trace.Start(ctx, "Custom Transaction")

    ...

    trace.End(ctx, nil)

    ...
}

API

Go
func Start(ctx context.Context, name string) (context.Context, error)

Go
func End(ctx context.Context, err error) error

Go
func StartWithRequest(r *http.Request) (context.Context, error)

Go
func Step(ctx context.Context, title, message string, elapsed, value int) error

Go
func HandlerFunc(handler func(http.ResponseWriter, *http.Request)) http.HandlerFunc

Go
func Func(handler func(http.ResponseWriter, *http.Request)) func(http.ResponseWriter, *http.Request)

DB 연결 및 SQL 추적

DB 연결 정보, sql 구문, error 및 prepared 구문을 위한 파라미터를 API로 전달하면 실행 시간 및 오류 사항을 수집할 수 있습니다. SQL 구문은 최대 32KB까지 수집합니다. SQL Prepared 구문을 위한 파라미터는 최대 20개, 각각 256byte까지 수집합니다.

DB Connection

Go
import (
    whatapsql "github.com/whatap/go-api/sql"
)

func main(){
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()
    
    ctx, _ := trace.Start(context.Background(), "Trace Open DB")
    defer trace.End(ctx, nil)
    
    sqlCtx, _ := whatapsql.StartOpen(ctx, "id@tcp(x.x.x.x:3306)/test")
    db, err := sql.Open("mysql", "id:pwd@tcp(x.x.x.x:3306)/test")
    whatapsql.End(sqlCtx, err)
    defer db.Close()
}

Go
import (
    whatapsql "github.com/whatap/go-api/sql"
)

func main(){
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()
    
    ctx, _ := trace.Start(context.Background(), "Trace Query")
    defer trace.End(ctx, nil)
    
    query = "select id, subject from tbl_faq limit 10"
    sqlCtx, _ = whatapsql.Start(ctx, "id:pwd@tcp(x.x.x.x:3306)/test", query)
    rows, err := db.QueryContext(ctx, query)
    whatapsql.End(sqlCtx, err)
}

Go
import (
    whatapsql "github.com/whatap/go-api/sql"
)

func main(){
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()
    
    ctx, _ := trace.Start(context.Background(), "Trace Prepared Statement")
    defer trace.End(ctx, nil)
    
    // Prepared Statement 생성
    query = "select id, subject from tbl_faq where id = ? limit ?"
    stmt, err := db.Prepare(query)
    if err != nil {
      return
    }
    defer stmt.Close()
    
    params := make([]interface{}, 0)
    params = append(params, 8)
    params = append(params, 1)
    
    sqlCtx, _ := whatapsql.StartWithParamArray(ctx, "id:pwd(x.x.x.x:3306)/test", query, params)
    rows, err := stmt.QueryContext(ctx, params...)
    whatapsql.End(sqlCtx, err)
    

    sqlCtx, _ = whatapsql.StartWithParam(ctx, "id:pwd(x.x.x.x:3306)/test", query, params...)
    rows, err := stmt.QueryContext(ctx, params...)
    whatapsql.End(sqlCtx, err)
}

database/sql 패키지 설정

database/sql 패키지의 sql.Open 함수 대신 whatapsql.OpenContext 함수를 사용합니다. PrepareContext, QueryContext, ExecContext 등 context를 전달하는 함수를 이용하길 권장합니다. 전달하는 context는 trace.Start()를 통해서 whatap TraceCtx 정보가 있어야 합니다.

Go

import (
    _ "github.com/go-sql-driver/mysql"
    "github.com/whatap/go-api/instrumentation/database/sql/whatapsql"
)

func main() {
    config := make(map[string]string)
    trace.Init(config)
    defer trace.Shutdown()

    // whataphttp.Func 내부에서 whatap TraceCtx를 생성합니다.
    http.HandleFunc("/query", whataphttp.Func(func(w http.ResponseWriter, r *http.Request){
      ctx := r.Context()
    
      // Use WhaTap Driver. whatap의 TraceCtx가 있는 context 를 전달합니다.
      db, err := whatapsql.OpenContext(ctx, "mysql", dataSource)
      if err != nil {
        fmt.Println("Error whatapsql.Open ", err)
        return
      }
      defer db.Close()
      
      ...
      query := "select id, subject from tbl_faq limit 10"
      
      // whatap TraceCtx가 있는 context 를 전달합니다.
      if rows, err := db.QueryContext(ctx, query); err == nil {
        ...
      }
    }
    ...
}

API

Go
func Start(ctx context.Context, dbhost, sql string) (*SqlCtx, error)

Go
func StartOpen(ctx context.Context, dbhost string) (*SqlCtx, error)

Go
func End(sqlCtx *SqlCtx, err error) error

Go
func StartWithParam(ctx context.Context, dbhost, sql, param ...interface{}) (*SqlCtx, error)

Go
func StartWithParamArray(ctx context.Context, dbhost, sql string, param []interface{}) (*SqlCtx, error)

Go
func Trace(ctx context.Context, dbhost, sql, param string, elapsed int, err error) error

HTTP 요청 추적

Go
import (
    "github.com/whatap/go-api/httc"
)

func main(){
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()

    ctx, _ := trace.Start(context.Background(), "Trace Http Call")
    defer trace.End(ctx, nil)

    httpcCtx, _ := httpc.Start(ctx, callUrl)
    resp, err := http.Get(callUrl)
    if err == nil {
        httpc.End(httpcCtx, resp.StatusCode, "", nil)
    } else {
        httpc.End(httpcCtx, 0, "", err)
    }
}

http transport RoundTrip

RoundTrip을 설정할 수 있습니다.

Go
import (
    "github.com/whatap/go-api/instrumentation/net/http/whataphttp"
)

func main() {
    config := make(map[string]string)
    trace.Init(config)
    defer trace.Shutdown()

    ctx, _ := trace.Start(context.Background(), "Http call")
    defer trace.End(ctx, nil)

    callUrl := "http://aaa.com/xxx"
    client := http.DefaultClient
    // Use WhaTap RoundTrip. Passes the context with whatap's TraceCtx.
    client.Transport = whataphttp.NewRoundTrip(ctx, http.DefaultTransport)
    resp, err := client.Get(callUrl)
    if err != nil {
        ...
    }
    defer resp.Body.Close()
    ...
}

API

Go
func Start(ctx context.Context, url string) (*HttpcCtx, error)

Go
func End(httpcCtx *HttpcCtx, status int, reason string, err error) error

Go
func Trace(ctx context.Context, host string, port int, url string, elapsed int, status int, reason string, err error) error

멀티 트랜잭션 추적(분산 추적)

멀티 트랜잭션은 다른 에이전트나 프로젝트와 연관된 트랜잭션을 의미합니다. 와탭 프로젝트에 등록된 애플리케이션 서비스 간의 호출을 추적하는 것이 멀티 트랜잭션 추적입니다.

노트

Go 에이전트는 세 개의 HTTP 헤더 키값(x-wtap-po, x-wtap-mst, x-wtap-sp1)으로 멀티 트랜잭션을 추적합니다. 게이트웨이를 통과하는 HTTP 트랜잭션이 연계 추적되지 않는다면 HTTP 헤더 조건을 확인하세요.

오픈소스 추적을 위해 TraceContext를 지원합니다. (traceparent 헤더 추적)

에이전트 설정하기

멀티 트랜잭션 추적을 위해 에이전트 설정 파일(whatap.conf)에 다음과 같이 옵션을 설정하세요.

whatap.conf
# Activation option, Default: false
mtrace_enabled=true

# Sampling rate, Default: 10
mtrace_rate=100

Request Header 전달하기

분산 추적 정보(헤더 정보)를 확인하려면 Request Header를 전달해야 합니다.

Go
// import "github.com/whatap/go-api/trace"
func UpdateMtrace(traceCtx *trace.TraceCtx, header http.Header) 

trace.StartWithRequest 함수는 내부적으로 UpdateMtrace 함수를 호출합니다. trace.StartWithRequest 함수를 사용하지 않는다면 직접 호출하여 전달받은 헤더 정보를 분석해야 합니다.

Go
// func GetTraceContext(ctx context.Context) (context.Context, *TraceCtx)
// if v := ctx.Value("whatap"); v != nil {
//      return ctx, v.(*TraceCtx)
// }
ctx, traceCtx := trace.GetTraceContext(ctx);
if traceCtx != nil {
    trace.UpdateMtrace(traceCtx, header)
}

노트

trace.Start 함수 내부 코드 참조:

Go
func Start(ctx context.Context, name string) (context.Context, error) {
    ctx, traceCtx := NewTraceContext(ctx)
    traceCtx.Name = name
    traceCtx.StartTime = dateutil.SystemNow()
    // update multi trace info
    UpdateMtrace(traceCtx, http.Header{})

    ...

trace.StartWithRequest 함수 내부 코드 참조:

Go
func StartWithRequest(r *http.Request) (context.Context, error) {
    ctx, traceCtx := NewTraceContext(r.Context())
    traceCtx.Name = r.RequestURI
    traceCtx.StartTime = dateutil.SystemNow()
    // update multi trace info
    UpdateMtrace(traceCtx, r.Header)

    ...

외부로 HTTP 연결할 때 Request Header에 추적을 위한 Header 정보를 추가하세요.

Go
import (
    "github.com/whatap/go-api/trace"
)

func GetMTrace(ctx context.Context) http.Header

다음은 분산 추적에 필요한 Header를 조회하는 함수입니다. 반환되는 Header를 외부 Request 요청에 추가해야 합니다. context에는 'whatap' 항목의 trace.TraceContext 정보가 포함되어 있어야 합니다. 해당 정보는 trace.Start, StartWithRequest, StartWithContext 함수를 사용할 때 내부에 whatap context 정보가 추가됩니다.

Example code
headers := trace.GetMTrace(wCtx)
for key, _ := range headers {
    // req *http.Request
    // The Add function is also available.
    req.Header.Set(key, headers.Get(key))
}

Whatap transport(RoundTrip)에는 내부적으로 GetMTrace를 사용하는 코드가 이미 존재합니다. 옵션만 활성화하면 자동으로 Header 정보를 추가할 수 있습니다.

Example code
import (
    "net/http"
    "github.com/whatap/go-api/instrumentation/net/http/whataphttp"
)

...

//client := http.DefaultClient
client := http.Client{
    Timeout: timeout,
}
client.Transport = whataphttp.NewRoundTrip(ctx, http.DefaultTransport)
if resp, err := client.Get(callUrl); err == nil {
    ...
}

다음은 여러 개의 Transport 사용 예제입니다. context에는 'whatap' 항목의 trace.TraceContext 정보가 포함되어 있어야 합니다.

Exmple code
import (
    "net/http"
    "github.com/whatap/go-api/instrumentation/net/http/whataphttp"
)

...

client := http.DefaultClient
client.Transport = NewAccessLogRoundTrip(whataphttp.NewRoundTrip(ctx, http.DefaultTransport))	

...

함수 추적

사용자 함수 또는 원하는 구간의 실행 시간을 측정하기 위한 API 입니다. 함수 실행 전, 후로 API를 설정할 수 있습니다.

Go
import (
    "github.com/whatap/go-api/method"
)
func main(){
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()
  
    ctx, _ := trace.Start(context.Background(), "Trace Method")
    defer trace.End(ctx, nil)
  
    getUser(ctx)
}

func getUser(ctx context.Context) {
    methodCtx, _ := method.Start(ctx, "getUser")
    defer method.End(methodCtx, nil)
    time.Sleep(time.Duration(1) * time.Second)
}

API

Go
func Start(ctx context.Context, name string) (*MethodCtx, error)

Go
func End(methodCtx *MethodCtx, err error) error

Go
func Trace(ctx context.Context, name string, elapsed int, err error) error

Log

에이전트 설정하기

애플리케이션 실행 전에 whatap.conf 파일에 에이전트 옵션을 설정하세요.

whatap.conf
# Enable all log collection
logsink_enabled=true

# Enable stdout collection
logsink_stdout_enabled=true

# Enable stderr collection
logsink_stderr_enabled=true

# Optional. This is a setting for compressing data. 
logsin_zip_enabled=true

로그 라이브러리 초기화 전

로그 라이브러리 초기화 전에 trace.Init() 함수를 호출해야 합니다. 내부적으로 os.Stdout, os.Stderr를 래핑합니다. 이후 로그 라이브러리가 os.Stdout, os.Stderr를 설정하면 자동으로 로그를 수집합니다.

로그 라이브러리 초기화 후

로그 라이브러리 초기화 후에는 별도의 설정 함수를 통해서 래핑한 io.Writer를 설정할 수 있습니다.

logsink.GetWriterHookStdout(): os.Stderr를 래핑한 io.Writer를 반환합니다. os.Stdout에 출력하면서 동시에 해당 로그를 와탭 로그로 수집합니다.
logsink.GetWriterHookStderr(): os.Stderr를 래핑한 io.Writer를 반환합니다. 래핑한 io.Writer는 os.Stderr에 출력 후 로그 내용을 와탭 로그로 수집합니다.

API

os.Stdout를 래핑한 io.Writer를 반환합니다.
```
func GetWriterHookStdout() io.Writer
```
os.Stderr를 래핑한 io.Writer를 반환합니다.
```
func GetWriterHookStderr() io.Writer
```

다음 패키지별 코드 예제를 참조하세요.

log package

log 패키지는 import 시점(init 함수)에서 os.Stderr를 설정합니다. trace.Init 함수를 먼저 호출할 수 없기 때문에 래핑한 io.Writer (os.Stderr)를 log.SetOutput 함수를 통해 설정합니다.

이후 사용되는 log 패키지의 print 함수를 사용한 출력은 래핑한 io.Writer를 통해서 os.Stderr에 출력은 유지하면서 동시에 로그 내용을 와탭 로그로 수집합니다.

log package
import (
    "log"
    "github.com/whatap/go-api/logsink"
)

...

if logsink.GetWriterHookStderr() != nil {
    // set single writer
    log.SetOutput(logsink.GetWriterHookStderr())	
    
    // set multi writer 
    multi := io.MultiWriter(file, logsink.GetWriterFromStderr())
    log.SetOutput(logsink.GetWriterHookStderr())
}

// 
log.Println("aaaaa")
...

go.uber.org/zap

os.Stdout을 설정하기 전에 trace.Init() 함수를 호출하면 자동으로 로그를 수집합니다. os.Stdout 출력은 유지하면서 동시에 와탭 로그로 수집합니다.

go.uber.org/zap
import (
    "github.com/whatap/go-api/trace"
    "github.com/whatap/go-api/logsink"
    
    "go.uber.org/zap"
    "go.uber.org/zap/zapcore"
)

func main() {
    trace.Init(nil)
    //It must be executed before closing the app.
    defer trace.Shutdown()

    // fmt.Println("Logger stdout=", os.Stdout, zapcore.AddSync(os.Stdout))
    consoleCore := zapcore.NewCore(
        zapcore.NewConsoleEncoder(consoleEncoderConfig), 
        zapcore.AddSync(os.Stdout),                      
        zap.InfoLevel,
    )

    // Menggabungkan core file dan console
    core := zapcore.NewTee(consoleCore)
    Log = zap.New(core, zap.AddCaller(), zap.AddStacktrace(zapcore.ErrorLevel))
    Log.Info("logger started")

    ...
}

github.com/sirupsen/logrus

래핑한 io.Writer를 설정하면 os.Stderr 출력은 유지하면서 동시에 와탭 로그로 수집합니다.

github.com/sirupsen/logrus
package main

import (
    "time"

    log "github.com/sirupsen/logrus"

    "github.com/whatap/go-api/logsink"
    "github.com/whatap/go-api/trace"
)

func main() {
    trace.Init(nil)
    defer trace.Shutdown()

    //In WhaTap, set io.Writer wrapping os.Stderr as the output of logrus
    if logsink.GetWriterHookStderr() != nil {
        log.SetOutput(logsink.GetWriterHookStderr())
    }

    for i := 0; i < 100; i++ {
        log.WithFields(log.Fields{
            "animal":  "tiger",
            "habitat": "mountain",
        }).Info("Index:[", i, "] A tiger appears")

        time.Sleep(100 * time.Millisecond)
    }
}

API 가이드

다운로드

시작하기

init, shutdown

Context

트랜잭션 생성

트랜잭션 추적

웹 트랜잭션 추적

일반 트랜잭션 추적

API

DB 연결 및 SQL 추적

DB Connection

database/sql 패키지 설정

API

HTTP 요청 추적

http transport RoundTrip

API

멀티 트랜잭션 추적(분산 추적)

에이전트 설정하기

Request Header 전달하기

HTTP 연결 시 Header 정보 추가하기

자동으로 Header 추가하기

함수 추적

API

Log

에이전트 설정하기

로그 라이브러리 초기화 전

로그 라이브러리 초기화 후

API

log package

go.uber.org/zap

github.com/sirupsen/logrus

다운로드​

시작하기​

init, shutdown​

Context​

트랜잭션 생성​

트랜잭션 추적​

웹 트랜잭션 추적​

일반 트랜잭션 추적​

API​

DB 연결 및 SQL 추적​

DB Connection​

database/sql 패키지 설정​

API​

HTTP 요청 추적​

http transport RoundTrip​

API​

멀티 트랜잭션 추적(분산 추적)​

에이전트 설정하기​

Request Header 전달하기​

HTTP 연결 시 Header 정보 추가하기​

자동으로 Header 추가하기​

함수 추적​

API​

Log​

에이전트 설정하기​

로그 라이브러리 초기화 전​

로그 라이브러리 초기화 후​

API​

log package​

go.uber.org/zap​

github.com/sirupsen/logrus​

다운로드

시작하기

init, shutdown

Context

트랜잭션 생성

트랜잭션 추적

웹 트랜잭션 추적

일반 트랜잭션 추적

API

DB 연결 및 SQL 추적

DB Connection

database/sql 패키지 설정

API

HTTP 요청 추적

http transport RoundTrip

API

멀티 트랜잭션 추적(분산 추적)

에이전트 설정하기

Request Header 전달하기

HTTP 연결 시 Header 정보 추가하기

자동으로 Header 추가하기

함수 추적

API

Log

에이전트 설정하기

로그 라이브러리 초기화 전

로그 라이브러리 초기화 후

API

log package

go.uber.org/zap

github.com/sirupsen/logrus