ochttp

package
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 13, 2018 License: Apache-2.0 Imports: 15 Imported by: 885

Documentation

Overview

Package ochttp provides OpenCensus instrumentation for net/http package.

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

Index

Examples

Constants

View Source 
const (
	HostAttribute       = "http.host"
	MethodAttribute     = "http.method"
	PathAttribute       = "http.path"
	UserAgentAttribute  = "http.user_agent"
	StatusCodeAttribute = "http.status_code"
)

Attributes recorded on the span for the requests. Only trace exporters will need them.

Variables

View Source 
var (
	ClientRequestCount  = stats.Int64("opencensus.io/http/client/request_count", "Number of HTTP requests started", stats.UnitDimensionless)
	ClientRequestBytes  = stats.Int64("opencensus.io/http/client/request_bytes", "HTTP request body size if set as ContentLength (uncompressed)", stats.UnitBytes)
	ClientResponseBytes = stats.Int64("opencensus.io/http/client/response_bytes", "HTTP response body size (uncompressed)", stats.UnitBytes)
	ClientLatency       = stats.Float64("opencensus.io/http/client/latency", "End-to-end latency", stats.UnitMilliseconds)
)

The following client HTTP measures are supported for use in custom views.

View Source 
var (
	ServerRequestCount  = stats.Int64("opencensus.io/http/server/request_count", "Number of HTTP requests started", stats.UnitDimensionless)
	ServerRequestBytes  = stats.Int64("opencensus.io/http/server/request_bytes", "HTTP request body size if set as ContentLength (uncompressed)", stats.UnitBytes)
	ServerResponseBytes = stats.Int64("opencensus.io/http/server/response_bytes", "HTTP response body size (uncompressed)", stats.UnitBytes)
	ServerLatency       = stats.Float64("opencensus.io/http/server/latency", "End-to-end latency", stats.UnitMilliseconds)
)

The following server HTTP measures are supported for use in custom views:

View Source 
var (
	// 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.
	Host, _ = tag.NewKey("http.host")

	// StatusCode is the numeric HTTP response status code,
	// or "error" if a transport error occurred and no status code was read.
	StatusCode, _ = tag.NewKey("http.status")

	// 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.
	Path, _ = tag.NewKey("http.path")

	// Method is the HTTP method of the request, capitalized (GET, POST, etc.).
	Method, _ = tag.NewKey("http.method")

	// 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).
	KeyServerRoute, _ = tag.NewKey("http_server_route")
)

The following tags are applied to stats recorded by this package. Host, Path and Method are applied to all measures. StatusCode is not applied to ClientRequestCount or ServerRequestCount, since it is recorded before the status is known.

View Source 
var (
	DefaultSizeDistribution    = view.Distribution(0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296)
	DefaultLatencyDistribution = view.Distribution(0, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000)
)

Default distributions used by views in this package.

View Source 
var (
	ClientRequestCountView = &view.View{
		Name:        "opencensus.io/http/client/request_count",
		Description: "Count of HTTP requests started",
		Measure:     ClientRequestCount,
		Aggregation: view.Count(),
	}

	ClientRequestBytesView = &view.View{
		Name:        "opencensus.io/http/client/request_bytes",
		Description: "Size distribution of HTTP request body",
		Measure:     ClientRequestBytes,
		Aggregation: DefaultSizeDistribution,
	}

	ClientResponseBytesView = &view.View{
		Name:        "opencensus.io/http/client/response_bytes",
		Description: "Size distribution of HTTP response body",
		Measure:     ClientResponseBytes,
		Aggregation: DefaultSizeDistribution,
	}

	ClientLatencyView = &view.View{
		Name:        "opencensus.io/http/client/latency",
		Description: "Latency distribution of HTTP requests",
		Measure:     ClientLatency,
		Aggregation: DefaultLatencyDistribution,
	}

	ClientRequestCountByMethod = &view.View{
		Name:        "opencensus.io/http/client/request_count_by_method",
		Description: "Client request count by HTTP method",
		TagKeys:     []tag.Key{Method},
		Measure:     ClientRequestCount,
		Aggregation: view.Count(),
	}

	ClientResponseCountByStatusCode = &view.View{
		Name:        "opencensus.io/http/client/response_count_by_status_code",
		Description: "Client response count by status code",
		TagKeys:     []tag.Key{StatusCode},
		Measure:     ClientLatency,
		Aggregation: view.Count(),
	}

	ServerRequestCountView = &view.View{
		Name:        "opencensus.io/http/server/request_count",
		Description: "Count of HTTP requests started",
		Measure:     ServerRequestCount,
		Aggregation: view.Count(),
	}

	ServerRequestBytesView = &view.View{
		Name:        "opencensus.io/http/server/request_bytes",
		Description: "Size distribution of HTTP request body",
		Measure:     ServerRequestBytes,
		Aggregation: DefaultSizeDistribution,
	}

	ServerResponseBytesView = &view.View{
		Name:        "opencensus.io/http/server/response_bytes",
		Description: "Size distribution of HTTP response body",
		Measure:     ServerResponseBytes,
		Aggregation: DefaultSizeDistribution,
	}

	ServerLatencyView = &view.View{
		Name:        "opencensus.io/http/server/latency",
		Description: "Latency distribution of HTTP requests",
		Measure:     ServerLatency,
		Aggregation: DefaultLatencyDistribution,
	}

	ServerRequestCountByMethod = &view.View{
		Name:        "opencensus.io/http/server/request_count_by_method",
		Description: "Server request count by HTTP method",
		TagKeys:     []tag.Key{Method},
		Measure:     ServerRequestCount,
		Aggregation: view.Count(),
	}

	ServerResponseCountByStatusCode = &view.View{
		Name:        "opencensus.io/http/server/response_count_by_status_code",
		Description: "Server response count by status code",
		TagKeys:     []tag.Key{StatusCode},
		Measure:     ServerLatency,
		Aggregation: view.Count(),
	}
)

Package ochttp provides some convenience views. You need to register the views for data to actually be collected.

View Source 
var DefaultClientViews = []*view.View{
	ClientRequestCountView,
	ClientRequestBytesView,
	ClientResponseBytesView,
	ClientLatencyView,
	ClientRequestCountByMethod,
	ClientResponseCountByStatusCode,
}

DefaultClientViews are the default client views provided by this package.

View Source 
var DefaultServerViews = []*view.View{
	ServerRequestCountView,
	ServerRequestBytesView,
	ServerResponseBytesView,
	ServerLatencyView,
	ServerRequestCountByMethod,
	ServerResponseCountByStatusCode,
}

DefaultServerViews are the default server views provided by this package.

Functions

func NewSpanAnnotatingClientTrace added in v0.16.0 

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 deprecated added in v0.15.0 

func NewSpanAnnotator(r *http.Request, s *trace.Span) *httptrace.ClientTrace

Deprecated: Use NewSpanAnnotatingClientTrace instead

func TraceStatus added in v0.9.0 

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 added in v0.16.0 

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.

Types

type Handler 

type Handler struct {
	// Propagation defines how traces are propagated. If unspecified,
	// B3 propagation will be used.
	Propagation propagation.HTTPFormat

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

	// 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.
	StartOptions trace.StartOptions

	// 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.
	IsPublicEndpoint bool

	// 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.
	FormatSpanName func(*http.Request) string
}

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.

Example 
package main

import (
	"log"
	"net/http"

	"go.opencensus.io/plugin/ochttp"
)

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{}))
}

Output:
Example (Mux) 
package main

import (
	"log"
	"net/http"

	"go.opencensus.io/plugin/ochttp"
	"go.opencensus.io/plugin/ochttp/propagation/b3"
)

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{},
	}))
}

Output:

func (*Handler) ServeHTTP 

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Transport 

type Transport struct {
	// 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.
	Base http.RoundTripper

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

	// 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.
	StartOptions trace.StartOptions

	// 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.
	FormatSpanName func(*http.Request) string

	// 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.
	NewClientTrace func(*http.Request, *trace.Span) *httptrace.ClientTrace
}

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.

Example 
package main

import (
	"log"
	"net/http"

	"go.opencensus.io/plugin/ochttp"
	"go.opencensus.io/stats/view"
	"go.opencensus.io/tag"
)

func main() {
	// import (
	// 		"go.opencensus.io/plugin/ochttp"
	//		"go.opencensus.io/stats/view"
	// )

	if err := view.Register(
		// Register a few default views.
		ochttp.ClientRequestCountByMethod,
		ochttp.ClientResponseCountByStatusCode,
		ochttp.ClientLatencyView,

		// Register a custom view.
		&view.View{
			Name:        "httpclient_latency_by_hostpath",
			TagKeys:     []tag.Key{ochttp.Host, ochttp.Path},
			Measure:     ochttp.ClientLatency,
			Aggregation: ochttp.DefaultLatencyDistribution,
		},
	); err != nil {
		log.Fatal(err)
	}

	client := &http.Client{
		Transport: &ochttp.Transport{},
	}

	// Use client to perform requests.
	_ = client
}

Output:

func (*Transport) CancelRequest 

func (t *Transport) CancelRequest(req *http.Request)

CancelRequest cancels an in-flight request by closing its connection.

func (*Transport) RoundTrip 

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements http.RoundTripper, delegating to Base and recording stats and traces for the request.

Source Files

View all Source files

Directories

Path Synopsis
propagation
b3
Package b3 contains a propagation.HTTPFormat implementation for B3 propagation.
 Package b3 contains a propagation.HTTPFormat implementation for B3 propagation.
tracecontext
Package tracecontext contains HTTP propagator for TraceContext standard.
 Package tracecontext contains HTTP propagator for TraceContext standard.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.