httpsnoop

https://pkg.go.dev/github.com/felixge/httpsnoop
Admin
httpsnoop is a Go package that provides an easy way to capture HTTP-related metrics like response...
Tokens:2,369
Snippets:28
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### httpsnoop Usage Example

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

This example demonstrates how to wrap an existing http.Handler with httpsnoop.CaptureMetrics to log request details.

```APIDOC
## Capture HTTP Metrics

### Description
This endpoint demonstrates how to use `httpsnoop.CaptureMetrics` to wrap an existing `http.Handler` and capture metrics such as response time, bytes written, and HTTP status code.

### Method
Not Applicable (This is a library usage example, not an HTTP endpoint)

### Endpoint
Not Applicable

### Parameters
Not Applicable

### Request Body
Not Applicable

### Response
Not Applicable

### Usage Example
```go
// myH is your app's http handler, perhaps a http.ServeMux or similar.
var myH http.Handler
// wrappedH wraps myH in order to log every request.
wrappedH := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	m := httpsnoop.CaptureMetrics(myH, w, r)
	log.Printf(
		"%s %s (code=%d dt=%s written=%d)",
		r.Method,
		r.URL,
		m.Code,
		m.Duration,
		m.Written,
	)
})
http.ListenAndServe(":8080", wrappedH)
```
```

--------------------------------

### Benchmark Comparison for CaptureMetrics

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

These benchmarks compare the performance overhead of using CaptureMetrics against a baseline http.Handler. The results indicate a negligible performance impact per request.

```go
BenchmarkBaseline-8      	   20000	     94912 ns/op
```

```go
BenchmarkCaptureMetrics-8	   20000	     95461 ns/op
```

--------------------------------

### CaptureMetrics Function

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

CaptureMetrics wraps an http.Handler, executes it, and returns the captured metrics. This function is a convenient way to instrument handlers for performance monitoring.

```go
func CaptureMetrics(hnd http.Handler, w http.ResponseWriter, r *http.Request) Metrics
```

--------------------------------

### Wrap HTTP Response Writer with Hooks

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Wrap returns a modified http.ResponseWriter that intercepts method calls based on provided hooks. If no hooks are set, it behaves identically to the original. Hooks can modify arguments or return values, and unsupported hooks are ignored.

```go
func Wrap(w http.ResponseWriter, hooks Hooks) http.ResponseWriter
```

--------------------------------

### CaptureMetricsFn Function

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

CaptureMetricsFn wraps an http.ResponseWriter and executes a provided function, returning the captured metrics. This is useful for applications not strictly using the http.Handler interface.

```go
func CaptureMetricsFn(w http.ResponseWriter, fn func(http.ResponseWriter)) Metrics
```

--------------------------------

### httpsnoop Low-Level API

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Details on using the low-level API for more granular control over ResponseWriter wrapping.

```APIDOC
## Low-Level ResponseWriter Wrapping

### Description
For users requiring more control, the `httpsnoop` package exposes its `http.ResponseWriter` wrapping capabilities directly. This allows for advanced scenarios where you need to interact with the underlying `http.ResponseWriter` or implement custom logic.

### Method
Not Applicable (This is a library usage example, not an HTTP endpoint)

### Endpoint
Not Applicable

### Parameters
Not Applicable

### Request Body
Not Applicable

### Response
Not Applicable

### Notes
- The package handles edge cases like `WriteHeader` not being called or being called multiple times.
- It also manages concurrent calls to `http.ResponseWriter` methods and calls made after the handler has returned.
- To access the underlying `http.ResponseWriter`, use `httpsnoop.Unwrap(w)` and then type-assert the result to its other interfaces if needed.
```

--------------------------------

### Capture HTTP Request Metrics

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Wrap your existing http.Handler with httpsnoop.CaptureMetrics to log request details like status code, duration, and bytes written. Ensure your application's http handler is assigned to 'myH' before wrapping.

```go
import (
	"log"
	"net/http"
	"github.com/felixge/httpsnoop"
)

// myH is your app's http handler, perhaps a http.ServeMux or similar.
var myH http.Handler
// wrappedH wraps myH in order to log every request.
wrappedH := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	m := httpsnoop.CaptureMetrics(myH, w, r)
	log.Printf(
		"%s %s (code=%d dt=%s written=%d)",
		r.Method,
		r.URL,
		m.Code,
		m.Duration,
		m.Written,
	)
})
http.ListenAndServe(":8080", wrappedH)
```

--------------------------------

### Unwrap http.ResponseWriter

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Utility to retrieve the original http.ResponseWriter from wrapped layers.

```APIDOC
## func Unwrap(w http.ResponseWriter) http.ResponseWriter

### Description
Unwrap returns the underlying http.ResponseWriter from within zero or more layers of httpsnoop wrappers.
```

--------------------------------

### Define WriteHeaderFunc type

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Represents the function signature for capturing HTTP status codes.

```go
type WriteHeaderFunc func(code int)
```

--------------------------------

### Metrics.CaptureMetrics Method

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

This method wraps an http.ResponseWriter, executes a function, and updates the Metrics receiver with the results. It allows for customizing the initial Metrics object.

```go
func (m *Metrics) CaptureMetrics(w http.ResponseWriter, fn func(http.ResponseWriter))
```

--------------------------------

### Unwrapper Interface

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

The Unwrapper interface provides a method to retrieve the underlying http.ResponseWriter. It is implemented by wrapped response writers.

```go
type Unwrapper interface {
	Unwrap() http.ResponseWriter
}
```

--------------------------------

### Unwrap HTTP Response Writer

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Use Unwrap to retrieve the underlying http.ResponseWriter from wrapped instances. This is useful for accessing the original writer when multiple layers of wrappers are present.

```go
func Unwrap(w http.ResponseWriter) http.ResponseWriter
```

--------------------------------

### Capture Metrics

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Functions to capture metrics from HTTP handlers or functions.

```APIDOC
## func CaptureMetrics(hnd http.Handler, w http.ResponseWriter, r *http.Request) Metrics

### Description
Wraps the given hnd, executes it with the given w and r, and returns the metrics it captured.

## func CaptureMetricsFn(w http.ResponseWriter, fn func(http.ResponseWriter)) Metrics

### Description
Wraps w and calls fn with the wrapped w, returning the resulting metrics.
```

--------------------------------

### Wrap http.ResponseWriter

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Wraps an existing http.ResponseWriter with custom hooks to intercept method calls.

```APIDOC
## func Wrap(w http.ResponseWriter, hooks Hooks) http.ResponseWriter

### Description
Returns a wrapped version of w that provides the exact same interface as w. If no hooks are set, the wrapped version behaves exactly as w.

### Parameters
- **w** (http.ResponseWriter) - Required - The original response writer.
- **hooks** (Hooks) - Required - A set of method interceptors for methods included in http.ResponseWriter.
```

--------------------------------

### Metrics Struct for HTTP Request Data

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Metrics holds captured data from HTTP requests, including response code, duration, and bytes written. The Code field defaults to 200 if WriteHeader is not called. Written tracks bytes passed to Write or ReadFrom.

```go
type Metrics struct {
	// Code is the first http response code passed to the WriteHeader func of
	// the ResponseWriter. If no such call is made, a default code of 200 is
	// assumed instead.
	Code int
	// Duration is the time it took to execute the handler.
	Duration time.Duration
	// Written is the number of bytes successfully written by the Write or
	// ReadFrom function of the ResponseWriter. ResponseWriters may also write
	// data to their underlaying connection directly (e.g. headers), but those
	// are not tracked. Therefor the number of Written bytes will usually match
	// the size of the response body.
	Written int64
}
```

--------------------------------

### Define HijackFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

HijackFunc is a type alias for functions that implement the http.Hijacker interface, allowing for direct network connection manipulation.

```go
type HijackFunc func() (net.Conn, *bufio.ReadWriter, error)
```

--------------------------------

### WriteHeaderFunc Type Definition

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Defines the function signature for capturing HTTP status codes in the http.ResponseWriter interface.

```APIDOC
## WriteHeaderFunc

### Description
WriteHeaderFunc is a function type used as part of the http.ResponseWriter interface to intercept or capture the HTTP status code being written.

### Definition
```go
type WriteHeaderFunc func(code int)
```

### Parameters
- **code** (int) - The HTTP status code being passed to the response writer.
```

--------------------------------

### Define PushFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

PushFunc is a type alias for functions implementing the http.Pusher interface, used for server push operations.

```go
type PushFunc func(target string, opts *http.PushOptions) error
```

--------------------------------

### Define Hooks for ResponseWriter Interception

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

Hooks defines a struct for intercepting various methods of http.ResponseWriter and other related interfaces. These act as middleware for function calls, allowing modification of arguments and return values.

```go
type Hooks struct {
	Header      func(HeaderFunc) HeaderFunc
	WriteHeader func(WriteHeaderFunc) WriteHeaderFunc
	Write       func(WriteFunc) WriteFunc
	Flush       func(FlushFunc) FlushFunc
	CloseNotify func(CloseNotifyFunc) CloseNotifyFunc
	Hijack      func(HijackFunc) HijackFunc
	ReadFrom    func(ReadFromFunc) ReadFromFunc
	Push        func(PushFunc) PushFunc
}
```

--------------------------------

### Define ReadFromFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

ReadFromFunc is a type alias for functions implementing the io.ReaderFrom interface, used for reading data from a source reader.

```go
type ReadFromFunc func(src io.Reader) (int64, error)
```

--------------------------------

### Define FlushFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

FlushFunc is a type alias for functions that implement the http.Flusher interface, used to flush buffered data.

```go
type FlushFunc func()
```

--------------------------------

### Define HeaderFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

HeaderFunc is a type alias for functions that return the response headers, part of the http.ResponseWriter interface.

```go
type HeaderFunc func() http.Header
```

--------------------------------

### Define CloseNotifyFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

CloseNotifyFunc is a type alias for functions that implement the http.CloseNotifier interface, returning a channel that signals connection closure.

```go
type CloseNotifyFunc func() <-chan bool
```

--------------------------------

### Define WriteFunc

Source: https://pkg.go.dev/github.com/felixge/httpsnoop

WriteFunc is a type alias for functions implementing the http.ResponseWriter interface's Write method, used for writing response bodies.

```go
type WriteFunc func(b []byte) (int, error)
```
Tokens:
Raw