pphttp

README

pphttp

Package pphttp instruments servers and clients that use net/http package.

Installation

$ go get github.com/pinpoint-apm/pinpoint-go-agent/plugin/http

import "github.com/pinpoint-apm/pinpoint-go-agent/plugin/http"

Usage

http server

This package instruments inbound requests handled by a http.ServeMux. Use NewServeMux to trace all handlers:

mux := pphttp.NewServeMux()
mux.HandleFunc("/bar", outGoing)

Use WrapHandler or WrapHandlerFunc to select the handlers you want to track:

http.HandleFunc("/", pphttp.WrapHandlerFunc(index))

For each request, a pinpoint.Tracer is stored in the request context. By using the pinpoint.FromContext function, this tracer can be obtained in your handler. Alternatively, the context of the request may be propagated where the context that contains the pinpoint.Tracer is required.

package main

import (
    "net/http"
    "github.com/pinpoint-apm/pinpoint-go-agent"
    "github.com/pinpoint-apm/pinpoint-go-agent/plugin/http"
)

func outGoing(w http.ResponseWriter, r *http.Request) {
    tracer := pinpoint.FromContext(r.Context())
    ctx := pinpoint.NewContext(context.Background(), tracer)
    // or ctx := r.Context()
    
    client := pphttp.WrapClientWithContext(ctx, &http.Client{})
    resp, err := client.Get("http://localhost:9000/async_wrapper?foo=bar&say=goodbye")
    ...
}

func main() {
    //setup agent
    opts := []pinpoint.ConfigOption{
        pinpoint.WithConfigFile(os.Getenv("HOME") + "/tmp/pinpoint-config.yaml"),
    }
    cfg, err := pinpoint.NewConfig(opts...)
    agent, err := pinpoint.NewAgent(cfg)
    defer agent.Shutdown()

    mux := pphttp.NewServeMux()
    mux.HandleFunc("/bar", outGoing)
    http.ListenAndServe("localhost:8000", mux)
}

This package supports URL Statistics feature. It aggregates response times, successes and failures for each router pattern. But, WrapHandler and WrapHandlerFunc function doesn't support URL Statistics feature.

Config Options

• Http.Server.StatusCodeErrors
• Http.Server.ExcludeUrl
• Http.Server.ExcludeMethod
• Http.Server.RecordRequestHeader
• Http.Server.RecordResponseHeader
• Http.Server.RecordRequestCookie
• Http.UrlStat.Enable
• Http.UrlStat.LimitSize

http client

This package instruments outbound requests and add distributed tracing headers. Use WrapClient, WrapClientWithContext or DoClient.

client := pphttp.WrapClient(&http.Client{})
client.Get(external_url)

req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
pphttp.DoClient(http.DefaultClient.Do, req)

It is necessary to pass the context containing the pinpoint.Tracer to the http.Request.

import (
    "net/http"
    "github.com/pinpoint-apm/pinpoint-go-agent"
    "github.com/pinpoint-apm/pinpoint-go-agent/plugin/http"
)

func wrapClient(w http.ResponseWriter, r *http.Request) {
    req, _ := http.NewRequestWithContext(r.Context(), "GET", "http://localhost:9000/async", nil)
    client := pphttp.WrapClient(&http.Client{})
    resp, err := client.Do(req)
    ...
}

func main() {
    ... //setup agent

    http.HandleFunc("/wrapclient", pphttp.WrapHandlerFunc(wrapClient))
    http.ListenAndServe(":8000", nil)
}

Full Example Source

Config Options

• Http.Client.RecordRequestHeader
• Http.Client.RecordResponseHeader
• Http.Client.RecordRequestCookie

Documentation

Overview

Package pphttp instruments Go standard HTTP library.

This package instruments inbound requests handled by a http.ServeMux. Use NewServeMux to trace all handlers:

mux := pphttp.NewServeMux()
mux.HandleFunc("/bar", outGoing)

Use WrapHandler or WrapHandlerFunc to select the handlers you want to track:

http.HandleFunc("/", pphttp.WrapHandlerFunc(index))

This package instruments outbound requests and add distributed tracing headers. Use WrapClient, WrapClientWithContext or DoClient.

client := pphttp.WrapClient(&http.Client{})
client.Get(external_url)

or

req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
pphttp.DoClient(http.DefaultClient.Do, req)

Index

• Constants
• func CollectUrlStat(tracer pinpoint.Tracer, url string, method string, status int)
• func DoClient(doFunc func(req *http.Request) (*http.Response, error), req *http.Request) (*http.Response, error)
• func EndHttpClientTracer(tracer pinpoint.Tracer, resp *http.Response, err error)
• func HandlerFuncName(f interface{}) string
• func NewHttpClientTracer(tracer pinpoint.Tracer, operationName string, req *http.Request) pinpoint.Tracer
• func NewHttpServerTracer(req *http.Request, operation string) (tracer pinpoint.Tracer)
• func NewServeMux() *serveMux
• func RecordClientHttpCookie(annotation pinpoint.Annotation, cookie Cookie)
• func RecordClientHttpRequestHeader(annotation pinpoint.Annotation, header Header)
• func RecordClientHttpResponseHeader(annotation pinpoint.Annotation, header Header)
• func RecordHttpHandlerError(tracer pinpoint.Tracer, err error)
• func RecordHttpServerResponse(tracer pinpoint.Tracer, status int, h http.Header)
• func WithHttpClientRecordRequestCookie(cookie []string) pinpoint.ConfigOption
• func WithHttpClientRecordRequestHeader(header []string) pinpoint.ConfigOption
• func WithHttpClientRecordRespondHeader(header []string) pinpoint.ConfigOption
• func WithHttpServerExcludeMethod(method []string) pinpoint.ConfigOption
• func WithHttpServerExcludeUrl(urlPath []string) pinpoint.ConfigOption
• func WithHttpServerRecordHandlerError(record bool) pinpoint.ConfigOption
• func WithHttpServerRecordRequestCookie(cookie []string) pinpoint.ConfigOption
• func WithHttpServerRecordRequestHeader(header []string) pinpoint.ConfigOption
• func WithHttpServerRecordRespondHeader(header []string) pinpoint.ConfigOption
• func WithHttpServerStatusCodeError(errors []string) pinpoint.ConfigOption
• func WrapClient(client *http.Client) *http.Client
• func WrapClientWithContext(ctx context.Context, client *http.Client) *http.Client
• func WrapHandle(agent pinpoint.Agent, handlerName string, pattern string, handler http.Handler) (string, http.Handler)
• func WrapHandleFunc(agent pinpoint.Agent, handlerName string, pattern string, ...) (string, func(http.ResponseWriter, *http.Request))
• func WrapHandler(handler http.Handler, serverName ...string) http.Handler
• func WrapHandlerFunc(handler func(http.ResponseWriter, *http.Request), serverName ...string) func(http.ResponseWriter, *http.Request)
• func WrapResponseWriter(w http.ResponseWriter, status *int) *responseWriter
• type Cookie
• type Header

Constants

const (
	CfgHttpServerStatusCodeErrors     = "Http.Server.StatusCodeErrors"
	CfgHttpServerExcludeUrl           = "Http.Server.ExcludeUrl"
	CfgHttpServerExcludeMethod        = "Http.Server.ExcludeMethod"
	CfgHttpServerRecordRequestHeader  = "Http.Server.RecordRequestHeader"
	CfgHttpServerRecordResponseHeader = "Http.Server.RecordResponseHeader"
	CfgHttpServerRecordRequestCookie  = "Http.Server.RecordRequestCookie"
	CfgHttpServerRecordHandlerError   = "Http.Server.RecordHandlerError"
	CfgHttpClientRecordRequestHeader  = "Http.Client.RecordRequestHeader"
	CfgHttpClientRecordResponseHeader = "Http.Client.RecordResponseHeader"
	CfgHttpClientRecordRequestCookie  = "Http.Client.RecordRequestCookie"
)

Functions

func CollectUrlStat

func CollectUrlStat(tracer pinpoint.Tracer, url string, method string, status int)

CollectUrlStat collects HTTP URL statistics.

func DoClient

func DoClient(doFunc func(req *http.Request) (*http.Response, error), req *http.Request) (*http.Response, error)

DoClient instruments and executes a given doFunc. It is necessary to pass the context containing the pinpoint.Tracer to the http.Request.

req, _ := http.NewRequestWithContext(pinpoint.NewContext(context.Background(), tracer), "GET", url, nil)
pphttp.DoClient(http.DefaultClient.Do, req)

func EndHttpClientTracer

func EndHttpClientTracer(tracer pinpoint.Tracer, resp *http.Response, err error)

EndHttpClientTracer is deprecated.

func HandlerFuncName

func HandlerFuncName(f interface{}) string

HandlerFuncName returns the name of handler function.

func NewHttpClientTracer

func NewHttpClientTracer(tracer pinpoint.Tracer, operationName string, req *http.Request) pinpoint.Tracer

NewHttpClientTracer is deprecated. Use WrapClient or DoClient.

func NewHttpServerTracer

func NewHttpServerTracer(req *http.Request, operation string) (tracer pinpoint.Tracer)

NewHttpServerTracer returns a pinpoint.Tracer that instruments the request handler for http server. The tracer extracts the pinpoint header from the http request header, and then creates a span that initiates or continues the transaction.

func NewServeMux

func NewServeMux() *serveMux

NewServeMux wraps http.NewServeMux and returns a http.ServeMux ready to instrument.

func RecordClientHttpCookie

func RecordClientHttpCookie(annotation pinpoint.Annotation, cookie Cookie)

func RecordClientHttpRequestHeader

func RecordClientHttpRequestHeader(annotation pinpoint.Annotation, header Header)

func RecordClientHttpResponseHeader

func RecordClientHttpResponseHeader(annotation pinpoint.Annotation, header Header)

func RecordHttpHandlerError

func RecordHttpHandlerError(tracer pinpoint.Tracer, err error)

RecordHttpHandlerError records error returned by http handler.

func RecordHttpServerResponse

func RecordHttpServerResponse(tracer pinpoint.Tracer, status int, h http.Header)

RecordHttpServerResponse records http status and response header to span.

func WithHttpClientRecordRequestCookie

func WithHttpClientRecordRequestCookie(cookie []string) pinpoint.ConfigOption

WithHttpClientRecordRequestCookie sets HTTP request cookies to be logged on the client side. If sets to HEADERS-ALL, it records all request cookies.

pphttp.WithHttpClientRecordRequestCookie([]string{"HEADERS-ALL"})

or

pphttp.WithHttpClientRecordRequestCookie([]string{"foo", "bar"})

func WithHttpClientRecordRequestHeader

func WithHttpClientRecordRequestHeader(header []string) pinpoint.ConfigOption

WithHttpClientRecordRequestHeader sets HTTP request headers to be logged on the client side. If sets to HEADERS-ALL, it records all request headers.

pphttp.WithHttpClientRecordRequestHeader([]string{"HEADERS-ALL"})

or

pphttp.WithHttpClientRecordRequestHeader([]string{"foo", "bar"})

func WithHttpClientRecordRespondHeader

func WithHttpClientRecordRespondHeader(header []string) pinpoint.ConfigOption

WithHttpClientRecordRespondHeader sets HTTP response headers to be logged on the client side. If sets to HEADERS-ALL, it records all response headers.

pphttp.WithHttpClientRecordRespondHeader([]string{"HEADERS-ALL"})

or

pphttp.WithHttpClientRecordRespondHeader([]string{"foo", "bar"})

func WithHttpServerExcludeMethod

func WithHttpServerExcludeMethod(method []string) pinpoint.ConfigOption

WithHttpServerExcludeMethod sets HTTP Request methods to exclude from tracking.

pphttp.WithHttpServerExcludeMethod([]string{"put", "delete"})

func WithHttpServerExcludeUrl

func WithHttpServerExcludeUrl(urlPath []string) pinpoint.ConfigOption

WithHttpServerExcludeUrl sets URLs to exclude from tracking. It supports ant style pattern. e.g. /aa/*.html, /??/exclude.html

pphttp.WithHttpServerExcludeUrl([]string{"/wrap_*", "/**/*.do"})

func WithHttpServerRecordHandlerError

func WithHttpServerRecordHandlerError(record bool) pinpoint.ConfigOption

WithHttpServerRecordHandlerError sets whether to record the error returned by http handler.

pphttp.WithHttpServerRecordHandlerError(false)

func WithHttpServerRecordRequestCookie

func WithHttpServerRecordRequestCookie(cookie []string) pinpoint.ConfigOption

WithHttpServerRecordRequestCookie sets HTTP request cookies to be logged on the server side. If sets to HEADERS-ALL, it records all request cookies.

pphttp.WithHttpServerRecordRequestCookie([]string{"HEADERS-ALL"})

or

pphttp.WithHttpServerRecordRequestCookie([]string{"foo", "bar"})

func WithHttpServerRecordRequestHeader

func WithHttpServerRecordRequestHeader(header []string) pinpoint.ConfigOption

WithHttpServerRecordRequestHeader sets HTTP request headers to be logged on the server side. If sets to HEADERS-ALL, it records all request headers.

pphttp.WithHttpServerRecordRequestHeader([]string{"HEADERS-ALL"})

or

pphttp.WithHttpServerRecordRequestHeader([]string{"foo", "bar"})

func WithHttpServerRecordRespondHeader

func WithHttpServerRecordRespondHeader(header []string) pinpoint.ConfigOption

WithHttpServerRecordRespondHeader sets HTTP response headers to be logged on the server side. If sets to HEADERS-ALL, it records all response headers.

pphttp.WithHttpServerRecordRespondHeader([]string{"HEADERS-ALL"})

or

pphttp.WithHttpServerRecordRespondHeader([]string{"foo", "bar", "set-cookie"})

func WithHttpServerStatusCodeError

func WithHttpServerStatusCodeError(errors []string) pinpoint.ConfigOption

WithHttpServerStatusCodeError sets HTTP status code with request failure.

pphttp.WithHttpServerStatusCodeError([]string{"5xx", "4xx", "302"})

func WrapClient

func WrapClient(client *http.Client) *http.Client

WrapClient returns a new *http.Client ready to instrument. It is necessary to pass the context containing the pinpoint.Tracer to the http.Request.

req, _ := http.NewRequestWithContext(pinpoint.NewContext(context.Background(), tracer), "GET", url, nil)
client := pphttp.WrapClient(&http.Client{})
client.Do(req)

func WrapClientWithContext

func WrapClientWithContext(ctx context.Context, client *http.Client) *http.Client

WrapClientWithContext returns a new *http.Client ready to instrument. It is possible to trace only when the given context contains a pinpoint.Tracer.

client := pphttp.WrapClientWithContext(pinpoint.NewContext(context.Background(), tracer), &http.Client{})
client.Get(external_url)

func WrapHandle

func WrapHandle(agent pinpoint.Agent, handlerName string, pattern string, handler http.Handler) (string, http.Handler)

WrapHandle is deprecated. Use WrapHandler.

func WrapHandleFunc

func WrapHandleFunc(agent pinpoint.Agent, handlerName string, pattern string, handler func(http.ResponseWriter, *http.Request)) (string, func(http.ResponseWriter, *http.Request))

WrapHandleFunc is deprecated. Use WrapHandlerFunc.

func WrapHandler

func WrapHandler(handler http.Handler, serverName ...string) http.Handler

WrapHandler wraps the given http handler and adds the pinpoint.Tracer to the request's context. By using the pinpoint.FromContext function, this tracer can be obtained.

func WrapHandlerFunc

func WrapHandlerFunc(handler func(http.ResponseWriter, *http.Request), serverName ...string) func(http.ResponseWriter, *http.Request)

WrapHandlerFunc wraps the given http handler function and adds the pinpoint.Tracer to the request's context. By using the pinpoint.FromContext function, this tracer can be obtained.

func WrapResponseWriter

func WrapResponseWriter(w http.ResponseWriter, status *int) *responseWriter

Types

type Cookie

type Cookie interface {
	VisitAll(f func(name string, value string))
}

type Header

type Header interface {
	Values(key string) []string
	VisitAll(f func(name string, values []string))
}