package ochttp

Import Path
	go.opencensus.io/plugin/ochttp (on go.dev)

Dependency Relation
	imports 15 packages, and imported by 10 packages

Involved Source Files

	      client.go
	      client_stats.go
	   d➜ doc.go
		Package ochttp provides OpenCensus instrumentation for net/http package.

		For server instrumentation, see Handler. For client-side instrumentation,
		see Transport.

	      route.go
	      server.go
	      span_annotating_client_trace.go
	      stats.go
	      trace.go
	      wrapped_body.go
Code Examples

	Handler
		package main
		
		import (
			"go.opencensus.io/plugin/ochttp"
			"log"
			"net/http"
		)
		
		var usersHandler http.Handler
		
		func main() {
			// import "go.opencensus.io/plugin/ochttp"
		
			http.Handle("/users", ochttp.WithRouteTag(usersHandler, "/users"))
		
			// If no handler is specified, the default mux is used.
			log.Fatal(http.ListenAndServe("localhost:8080", &ochttp.Handler{}))
		}


	Handler_mux
		package main
		
		import (
			"go.opencensus.io/plugin/ochttp"
			"go.opencensus.io/plugin/ochttp/propagation/b3"
			"log"
			"net/http"
		)
		
		var usersHandler http.Handler
		
		func main() {
			// import "go.opencensus.io/plugin/ochttp"
		
			mux := http.NewServeMux()
			mux.Handle("/users", ochttp.WithRouteTag(usersHandler, "/users"))
			log.Fatal(http.ListenAndServe("localhost:8080", &ochttp.Handler{
				Handler:     mux,
				Propagation: &b3.HTTPFormat{},
			}))
		}


	Transport
		package main
		
		import (
			"go.opencensus.io/plugin/ochttp"
			"go.opencensus.io/stats/view"
			"go.opencensus.io/tag"
			"log"
			"net/http"
		)
		
		func main() {
			// import (
			// 		"go.opencensus.io/plugin/ochttp"
			//		"go.opencensus.io/stats/view"
			// )
		
			if err := view.Register(
				// Register a few default views.
				ochttp.ClientSentBytesDistribution,
				ochttp.ClientReceivedBytesDistribution,
				ochttp.ClientRoundtripLatencyDistribution,
				// Register a custom view.
				&view.View{
					Name:        "httpclient_latency_by_path",
					TagKeys:     []tag.Key{ochttp.KeyClientPath},
					Measure:     ochttp.ClientRoundtripLatency,
					Aggregation: ochttp.DefaultLatencyDistribution,
				},
			); err != nil {
				log.Fatal(err)
			}
		
			client := &http.Client{
				Transport: &ochttp.Transport{},
			}
		
			// Use client to perform requests.
			_ = client
		}


Package-Level Type Names (total 11, in which 2 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Handler (struct)
		Handler is an http.Handler wrapper to instrument your HTTP server with
		OpenCensus. It supports both stats and tracing.

		Tracing

		This handler is aware of the incoming request's span, reading it from request
		headers as configured using the Propagation field.
		The extracted span can be accessed from the incoming request's
		context.

		   span := trace.FromContext(r.Context())

		The server span will be automatically ended at the end of ServeHTTP.

		Fields (total 7, all are exported)
			FormatSpanName func(*http.Request) string
				FormatSpanName holds the function to use for generating the span name
				from the information found in the incoming HTTP Request. By default the
				name equals the URL Path.

			GetStartOptions func(*http.Request) trace.StartOptions
				GetStartOptions allows to set start options per request. If set,
				StartOptions is going to be ignored.

			Handler http.Handler
				Handler is the handler used to handle the incoming request.

			IsHealthEndpoint func(*http.Request) bool
				IsHealthEndpoint holds the function to use for determining if the
				incoming HTTP request should be considered a health check. This is in
				addition to the private isHealthEndpoint func which may also indicate
				tracing should be skipped.

			IsPublicEndpoint bool
				IsPublicEndpoint should be set to true for publicly accessible HTTP(S)
				servers. If true, any trace metadata set on the incoming request will
				be added as a linked trace instead of being added as a parent of the
				current trace.

			Propagation propagation.HTTPFormat
				Propagation defines how traces are propagated. If unspecified,
				B3 propagation will be used.

			StartOptions trace.StartOptions
				StartOptions are applied to the span started by this Handler around each
				request.

				StartOptions.SpanKind will always be set to trace.SpanKindServer
				for spans started by this transport.

		Methods (total 4, in which 1 are exported)
			(*T) ServeHTTP(w http.ResponseWriter, r *http.Request)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			(*T) extractSpanContext(r *http.Request) (trace.SpanContext, bool)
			(*T) startStats(w http.ResponseWriter, r *http.Request) (http.ResponseWriter, func(tags *addedTags))
			(*T) startTrace(w http.ResponseWriter, r *http.Request) (*http.Request, func())
		Implements (at least one exported)
			*T : net/http.Handler

	 type Transport (struct)
		Transport is an http.RoundTripper that instruments all outgoing requests with
		OpenCensus stats and tracing.

		The zero value is intended to be a useful default, but for
		now it's recommended that you explicitly set Propagation, since the default
		for this may change.

		Fields (total 6, all are exported)
			Base http.RoundTripper
				Base may be set to wrap another http.RoundTripper that does the actual
				requests. By default http.DefaultTransport is used.

				If base HTTP roundtripper implements CancelRequest,
				the returned round tripper will be cancelable.

			FormatSpanName func(*http.Request) string
				NameFromRequest holds the function to use for generating the span name
				from the information found in the outgoing HTTP Request. By default the
				name equals the URL Path.

			GetStartOptions func(*http.Request) trace.StartOptions
				GetStartOptions allows to set start options per request. If set,
				StartOptions is going to be ignored.

			NewClientTrace func(*http.Request, *trace.Span) *httptrace.ClientTrace
				NewClientTrace may be set to a function allowing the current *trace.Span
				to be annotated with HTTP request event information emitted by the
				httptrace package.

			Propagation propagation.HTTPFormat
				Propagation defines how traces are propagated. If unspecified, a default
				(currently B3 format) will be used.

			StartOptions trace.StartOptions
				StartOptions are applied to the span started by this Transport around each
				request.

				StartOptions.SpanKind will always be set to trace.SpanKindClient
				for spans started by this transport.

		Methods (total 3, in which 2 are exported)
			(*T) CancelRequest(req *http.Request)
				CancelRequest cancels an in-flight request by closing its connection.

			(*T) RoundTrip(req *http.Request) (*http.Response, error)
				RoundTrip implements http.RoundTripper, delegating to Base and recording stats and traces for the request.

			/* one unexported ... *//* one unexported: */
			(*T) base() http.RoundTripper
		Implements (at least one exported)
			*T : net/http.RoundTripper

	/* 9 unexporteds ... *//* 9 unexporteds: */
	 type addedTags (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			t []tag.Mutator

	 type addedTagsKey (struct)
	 type bodyTracker (struct)
		bodyTracker wraps a response.Body and invokes
		trace.EndSpan on encountering io.EOF on reading
		the body of the original response.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			rc io.ReadCloser
			span *trace.Span
		Methods (total 2, both are exported)
			(*T) Close() error
			(*T) Read(b []byte) (int, error)
		Implements (at least 4, all are exported)
			*T : github.com/jbenet/go-context/io.Reader
			*T : io.Closer
			*T : io.ReadCloser
			*T : io.Reader

	 type spanAnnotator (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			sp *trace.Span
		Methods (total 14, none are exported)
			/* 14 unexporteds ... *//* 14 unexporteds: */
			( T) connectDone(network, addr string, err error)
			( T) connectStart(network, addr string)
			( T) dnsDone(info httptrace.DNSDoneInfo)
			( T) dnsStart(info httptrace.DNSStartInfo)
			( T) getConn(hostPort string)
			( T) got100Continue()
			( T) gotConn(info httptrace.GotConnInfo)
			( T) gotFirstResponseByte()
			( T) putIdleConn(err error)
				PutIdleConn implements a httptrace.ClientTrace hook

			( T) tlsHandshakeDone(_ tls.ConnectionState, err error)
			( T) tlsHandshakeStart()
			( T) wait100Continue()
			( T) wroteHeaders()
			( T) wroteRequest(info httptrace.WroteRequestInfo)

	 type statsTransport (struct)
		statsTransport is an http.RoundTripper that collects stats for the outgoing requests.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			base http.RoundTripper
		Methods (total 2, both are exported)
			( T) CancelRequest(req *http.Request)
				CancelRequest cancels an in-flight request by closing its connection.

			( T) RoundTrip(req *http.Request) (*http.Response, error)
				RoundTrip implements http.RoundTripper, delegating to Base and recording stats for the request.

		Implements (at least one exported)
			 T : net/http.RoundTripper

	 type taggedHandlerFunc (func)
		taggedHandlerFunc is a http.Handler that returns tags describing the
		processing of the request. These tags will be recorded along with the
		measures in this package at the end of the request.

		Methods (only one, which is exported)
			( T) ServeHTTP(w http.ResponseWriter, r *http.Request)
		Implements (at least one exported)
			 T : net/http.Handler

	 type traceTransport (struct)

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			base http.RoundTripper
			format propagation.HTTPFormat
			formatSpanName func(*http.Request) string
			newClientTrace func(*http.Request, *trace.Span) *httptrace.ClientTrace
			startOptions trace.StartOptions
		Methods (total 2, both are exported)
			(*T) CancelRequest(req *http.Request)
				CancelRequest cancels an in-flight request by closing its connection.

			(*T) RoundTrip(req *http.Request) (*http.Response, error)
				RoundTrip creates a trace.Span and inserts it into the outgoing request's headers.
				The created span can follow a parent span, if a parent is presented in
				the request's context.

		Implements (at least one exported)
			*T : net/http.RoundTripper

	 type tracker (struct)

		Fields (total 8, none are exported)
			/* 8 unexporteds ... *//* 8 unexporteds: */
			body io.ReadCloser
			ctx context.Context
			endOnce sync.Once
			reqSize int64
			respContentLength int64
			respSize int64
			start time.Time
			statusCode int
		Methods (total 3, in which 2 are exported)
			(*T) Close() error
			(*T) Read(b []byte) (int, error)
			/* one unexported ... *//* one unexported: */
			(*T) end()
		Implements (at least 4, all are exported)
			*T : github.com/jbenet/go-context/io.Reader
			*T : io.Closer
			*T : io.ReadCloser
			*T : io.Reader

	 type trackingResponseWriter (struct)

		Fields (total 8, none are exported)
			/* 8 unexporteds ... *//* 8 unexporteds: */
			ctx context.Context
			endOnce sync.Once
			reqSize int64
			respSize int64
			start time.Time
			statusCode int
			statusLine string
			writer http.ResponseWriter
		Methods (total 5, in which 3 are exported)
			(*T) Header() http.Header
			(*T) Write(data []byte) (int, error)
			(*T) WriteHeader(statusCode int)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*T) end(tags *addedTags)
			(*T) wrappedResponseWriter() http.ResponseWriter
				wrappedResponseWriter returns a wrapped version of the original
				 ResponseWriter and only implements the same combination of additional
				interfaces as the original.
				This implementation is based on https://github.com/felixge/httpsnoop.

		Implements (at least 4, all are exported)
			*T : github.com/go-git/go-git/v5/plumbing/protocol/packp/sideband.Progress
			*T : github.com/jbenet/go-context/io.Writer
			*T : io.Writer
			*T : net/http.ResponseWriter


Package-Level Functions (total 10, in which 5 are exported)

	 func NewSpanAnnotatingClientTrace(_ *http.Request, s *trace.Span) *httptrace.ClientTrace
		NewSpanAnnotatingClientTrace returns a httptrace.ClientTrace which annotates
		all emitted httptrace events on the provided Span.

	 func NewSpanAnnotator(r *http.Request, s *trace.Span) *httptrace.ClientTrace
		NewSpanAnnotator returns a httptrace.ClientTrace which annotates
		all emitted httptrace events on the provided Span.
		Deprecated: Use NewSpanAnnotatingClientTrace instead

	 func SetRoute(ctx context.Context, route string)
		SetRoute sets the http_server_route tag to the given value.
		It's useful when an HTTP framework does not support the http.Handler interface
		and using WithRouteTag is not an option, but provides a way to hook into the request flow.

	 func TraceStatus(httpStatusCode int, statusLine string) trace.Status
		TraceStatus is a utility to convert the HTTP status code to a trace.Status that
		represents the outcome as closely as possible.

	 func WithRouteTag(handler http.Handler, route string) http.Handler
		WithRouteTag returns an http.Handler that records stats with the
		http_server_route tag set to the given value.

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 func isHealthEndpoint(path string) bool
	 func requestAttrs(r *http.Request) []trace.Attribute
	 func responseAttrs(resp *http.Response) []trace.Attribute
	 func spanNameFromURL(req *http.Request) string
	 func wrappedBody(wrapper io.ReadCloser, body io.ReadCloser) io.ReadCloser
		wrappedBody returns a wrapped version of the original
		Body and only implements the same combination of additional
		interfaces as the original.


Package-Level Variables (total 42, in which 40 are exported)

	  var ClientCompletedCount *view.View
		Package ochttp provides some convenience views for client measures.
		You still need to register these views for data to actually be collected.

	  var ClientLatency *stats.Float64Measure
		Deprecated: Use ClientRoundtripLatency.

	  var ClientLatencyView *view.View
		Deprecated: Use ClientRoundtripLatencyDistribution instead.

	  var ClientReceivedBytes *stats.Int64Measure
		The following client HTTP measures are supported for use in custom views.

	  var ClientReceivedBytesDistribution *view.View
		Package ochttp provides some convenience views for client measures.
		You still need to register these views for data to actually be collected.

	  var ClientRequestBytes *stats.Int64Measure
		Deprecated: Use ClientSentBytes.

	  var ClientRequestBytesView *view.View
		Deprecated: Use ClientSentBytesDistribution.

	  var ClientRequestCount *stats.Int64Measure
		Deprecated: Use a Count aggregation over one of the other client measures to achieve the same effect.

	  var ClientRequestCountByMethod *view.View
		Deprecated: Use ClientCompletedCount instead.

	  var ClientRequestCountView *view.View
		Deprecated: No direct replacement, but see ClientCompletedCount.

	  var ClientResponseBytes *stats.Int64Measure
		Deprecated: Use ClientReceivedBytes.

	  var ClientResponseBytesView *view.View
		Deprecated: Use ClientReceivedBytesDistribution instead.

	  var ClientResponseCountByStatusCode *view.View
		Deprecated: Use ClientCompletedCount instead.

	  var ClientRoundtripLatency *stats.Float64Measure
		The following client HTTP measures are supported for use in custom views.

	  var ClientRoundtripLatencyDistribution *view.View
		Package ochttp provides some convenience views for client measures.
		You still need to register these views for data to actually be collected.

	  var ClientSentBytes *stats.Int64Measure
		The following client HTTP measures are supported for use in custom views.

	  var ClientSentBytesDistribution *view.View
		Package ochttp provides some convenience views for client measures.
		You still need to register these views for data to actually be collected.

	  var DefaultClientViews []*view.View
		DefaultClientViews are the default client views provided by this package.
		Deprecated: No replacement. Register the views you would like individually.

	  var DefaultLatencyDistribution *view.Aggregation
		Default distributions used by views in this package.

	  var DefaultServerViews []*view.View
		DefaultServerViews are the default server views provided by this package.
		Deprecated: No replacement. Register the views you would like individually.

	  var DefaultSizeDistribution *view.Aggregation
		Default distributions used by views in this package.

	  var Host tag.Key
		Host is the value of the HTTP Host header.

		The value of this tag can be controlled by the HTTP client, so you need
		to watch out for potentially generating high-cardinality labels in your
		metrics backend if you use this tag in views.

	  var KeyClientHost tag.Key
		KeyClientHost is the value of the request Host header.

	  var KeyClientMethod tag.Key
		KeyClientMethod is the HTTP method, capitalized (i.e. GET, POST, PUT, DELETE, etc.).

	  var KeyClientPath tag.Key
		KeyClientPath is the URL path (not including query string).

	  var KeyClientStatus tag.Key
		KeyClientStatus is the HTTP status code as an integer (e.g. 200, 404, 500.), or "error" if no response status line was received.

	  var KeyServerRoute tag.Key
		KeyServerRoute is a low cardinality string representing the logical
		handler of the request. This is usually the pattern registered on the a
		ServeMux (or similar string).

	  var Method tag.Key
		Method is the HTTP method of the request, capitalized (GET, POST, etc.).

	  var Path tag.Key
		Path is the URL path (not including query string) in the request.

		The value of this tag can be controlled by the HTTP client, so you need
		to watch out for potentially generating high-cardinality labels in your
		metrics backend if you use this tag in views.

	  var ServerLatency *stats.Float64Measure
		The following server HTTP measures are supported for use in custom views:

	  var ServerLatencyView *view.View
		Package ochttp provides some convenience views for server measures.
		You still need to register these views for data to actually be collected.

	  var ServerRequestBytes *stats.Int64Measure
		The following server HTTP measures are supported for use in custom views:

	  var ServerRequestBytesView *view.View
		Package ochttp provides some convenience views for server measures.
		You still need to register these views for data to actually be collected.

	  var ServerRequestCount *stats.Int64Measure
		The following server HTTP measures are supported for use in custom views:

	  var ServerRequestCountByMethod *view.View
		Package ochttp provides some convenience views for server measures.
		You still need to register these views for data to actually be collected.

	  var ServerRequestCountView *view.View
		Package ochttp provides some convenience views for server measures.
		You still need to register these views for data to actually be collected.

	  var ServerResponseBytes *stats.Int64Measure
		The following server HTTP measures are supported for use in custom views:

	  var ServerResponseBytesView *view.View
		Package ochttp provides some convenience views for server measures.
		You still need to register these views for data to actually be collected.

	  var ServerResponseCountByStatusCode *view.View
		Package ochttp provides some convenience views for server measures.
		You still need to register these views for data to actually be collected.

	  var StatusCode tag.Key
		StatusCode is the numeric HTTP response status code,
		or "error" if a transport error occurred and no status code was read.

	/* 2 unexporteds ... *//* 2 unexporteds: */
	  var codeToStr map[int32]string
	  var defaultFormat propagation.HTTPFormat
Package-Level Constants (total 6, all are exported)

	const HostAttribute = "http.host"
		Attributes recorded on the span for the requests.
		Only trace exporters will need them.

	const MethodAttribute = "http.method"
		Attributes recorded on the span for the requests.
		Only trace exporters will need them.

	const PathAttribute = "http.path"
		Attributes recorded on the span for the requests.
		Only trace exporters will need them.

	const StatusCodeAttribute = "http.status_code"
		Attributes recorded on the span for the requests.
		Only trace exporters will need them.

	const URLAttribute = "http.url"
		Attributes recorded on the span for the requests.
		Only trace exporters will need them.

	const UserAgentAttribute = "http.user_agent"
		Attributes recorded on the span for the requests.
		Only trace exporters will need them.

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.