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 RoundTripper

RoundTripper를 설정할 수 있습니다.

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 RoundTripper. whatap의 TraceCtx가 있는 context 를 전달합니다.   
    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

함수 추적

사용자 함수 또는 원하는 구간의 실행 시간을 측정하기 위한 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

다운로드​

시작하기​

init, shutdown​

Context​

트랜잭션 생성​

트랜잭션 추적​

웹 트랜잭션 추적​

일반 트랜잭션 추적​

API​

DB 연결 및 SQL 추적​

DB Connection​

database/sql 패키지 설정​

API​

HTTP 요청 추적​

http transport RoundTripper​

API​

함수 추적​

API​

다운로드

시작하기

init, shutdown

Context

트랜잭션 생성

트랜잭션 추적

웹 트랜잭션 추적

일반 트랜잭션 추적

API

DB 연결 및 SQL 추적

DB Connection

database/sql 패키지 설정

API

HTTP 요청 추적

http transport RoundTripper

API

함수 추적

API