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接続が正常に行われてこそ、性能情報をWhaTap収集サーバーに送ることができます。デフォルト接続情報として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が必要です。

トランザクションのトレース

Webリクエストと応答までのトランザクションと一般的なタスク単位のトランザクションの両方を追跡します。開始および終了のメソッドで構成されています。一つのトランザクションとして認識され、ヒットマップウィゼットで詳細やTPS、応答時間、平均応答時間などの統計指標を確認することができます。

設定を通じてHTTPパラメータ、HTTPヘッダー情報を収集できます。

Webトランザクション追跡

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​

トランザクションの作成​

トランザクションのトレース​

Webトランザクション追跡​

ノーマルトランザクション追跡​

API​

DB接続およびSQL追跡​

DB Connection​

database/sqlパッケージの設定​

API​

HTTPリクエスト追跡​

http transport RoundTripper​

API​

メソッド追跡​

API​

ダウンロード

はじめに

init、shutdown

Context

トランザクションの作成

トランザクションのトレース

Webトランザクション追跡

ノーマルトランザクション追跡

API

DB接続およびSQL追跡

DB Connection

database/sqlパッケージの設定

API

HTTPリクエスト追跡

http transport RoundTripper

API

メソッド追跡

API