Documentation
¶
Overview ¶
Package httpmetrics provides HTTP middleware and transport wrappers that instrument requests with Prometheus metrics, OpenTelemetry tracing, and structured logging for Cloud Run services.
Index ¶
- Constants
- Variables
- func ExtractInnerTransport(rt http.RoundTripper) http.RoundTripper
- func Handler(name string, handler http.Handler) http.Handler
- func HandlerFunc(name string, f func(http.ResponseWriter, *http.Request)) http.HandlerFunc
- func NewIDTokenClient(ctx context.Context, audience string, opts ...idtoken.ClientOption) (*http.Client, error)
- func ScrapeDiskUsage(ctx context.Context)
- func ServeMetrics()
- func SetBucketSuffixes(bs map[string]string)
- func SetBuckets(b map[string]string)
- func SetupMetrics(ctx context.Context) func()
- func SetupTracer(ctx context.Context) func()
- func WithGitHubAppID(ctx context.Context, appID int64) context.Context
- func WithGitHubInstallationID(ctx context.Context, installationID int64) context.Context
- func WrapTransport(t http.RoundTripper, opts ...TransportOption) http.RoundTripper
- type MetricsTransport
- type TransportOption
- type TransportUnwrapper
Examples ¶
Constants ¶
const ( DiskUsageScrapeInterval = 5 * time.Second DiskUsageScrapeIntervalEnv = "DISK_USAGE_SCRAPE_INTERVAL" )
const ( CeTypeHeader string = "ce-type" GoogClientTraceHeader string = "googclient_traceparent" OriginalTraceHeader string = "original-traceparent" )
Variables ¶
var Transport = WrapTransport(http.DefaultTransport)
Transport is an http.RoundTripper that records metrics for each request.
Functions ¶
func ExtractInnerTransport ¶ added in v0.5.156
func ExtractInnerTransport(rt http.RoundTripper) http.RoundTripper
ExtractInnerTransport recursively unwraps layers of RoundTripper wrapping (MetricsTransport and any TransportUnwrapper) to find the base transport. Stops after maxUnwrapDepth iterations to prevent infinite loops.
Example ¶
package main
import (
"net/http"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
wrapped := httpmetrics.WrapTransport(http.DefaultTransport)
inner := httpmetrics.ExtractInnerTransport(wrapped)
_ = inner
}
Output:
func Handler ¶
Handler wraps a given http handler in standard metrics handlers.
Example ¶
package main
import (
"net/http"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
inner := http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusOK)
})
h := httpmetrics.Handler("my-handler", inner)
_ = h
}
Output:
func HandlerFunc ¶
func HandlerFunc(name string, f func(http.ResponseWriter, *http.Request)) http.HandlerFunc
HandlerFunc wraps a given http handler func in standard metrics handlers.
Example ¶
package main
import (
"net/http"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
h := httpmetrics.HandlerFunc("my-handler", func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusOK)
})
_ = h
}
Output:
func NewIDTokenClient ¶ added in v0.5.156
func NewIDTokenClient(ctx context.Context, audience string, opts ...idtoken.ClientOption) (*http.Client, error)
NewIDTokenClient creates a new http.Client based on idtoken.Client, with metrics.
func ScrapeDiskUsage ¶ added in v0.5.156
func ServeMetrics ¶
func ServeMetrics()
ServeMetrics serves the metrics endpoint if the METRICS_PORT env var is set.
func SetBucketSuffixes ¶
SetBucketSuffixes configures suffix-based host-to-label mappings. Must be called before the first HTTP request for the mappings to take effect.
Example ¶
package main
import (
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
httpmetrics.SetBucketSuffixes(map[string]string{
"example.com": "example",
})
}
Output:
func SetBuckets ¶
SetBuckets configures exact host-to-label mappings. Must be called before the first HTTP request for the mappings to take effect.
Example ¶
package main
import (
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
httpmetrics.SetBuckets(map[string]string{
"api.example.com": "example-api",
})
}
Output:
func SetupMetrics ¶ added in v1.0.1
SetupMetrics setups a prometheus exporter for otel metrics
Expected usage:
defer metrics.SetupMetrics(ctx)()
Example ¶
package main
import (
"context"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
ctx := context.Background()
cleanup := httpmetrics.SetupMetrics(ctx)
defer cleanup()
}
Output:
func SetupTracer ¶
Fractions >= 1 will always sample. Fractions < 0 are treated as zero. To respect the parent trace's `SampledFlag`, the `TraceIDRatioBased` sampler should be used as a delegate of a `Parent` sampler.
Expected usage:
defer metrics.SetupTracer(ctx)()
Example ¶
package main
import (
"context"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
ctx := context.Background()
cleanup := httpmetrics.SetupTracer(ctx)
defer cleanup()
}
Output:
func WithGitHubAppID ¶ added in v1.0.4
WithGitHubAppID returns a copy of ctx with the GitHub App ID attached. The transport reads this value to label rate limit metrics with the app that made the request, enabling per-app visibility into quota consumption.
func WithGitHubInstallationID ¶ added in v1.0.4
WithGitHubInstallationID returns a copy of ctx with the GitHub installation ID attached. The transport reads this value to label rate limit metrics with the installation that made the request. GitHub enforces rate limits per installation, so this label identifies which (app, org) pair is consuming quota.
func WrapTransport ¶
func WrapTransport(t http.RoundTripper, opts ...TransportOption) http.RoundTripper
WrapTransport wraps an http.RoundTripper with instrumentation.
Example ¶
package main
import (
"net/http"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
t := httpmetrics.WrapTransport(http.DefaultTransport)
_ = t
}
Output:
Example (SkipBucketize) ¶
package main
import (
"net/http"
"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)
func main() {
t := httpmetrics.WrapTransport(http.DefaultTransport, httpmetrics.WithSkipBucketize(true))
_ = t
}
Output:
Types ¶
type MetricsTransport ¶ added in v0.5.156
type MetricsTransport struct {
http.RoundTripper
// contains filtered or unexported fields
}
type TransportOption ¶ added in v0.6.168
type TransportOption func(*metricsTransportOptions)
func WithSkipBucketize ¶ added in v0.6.168
func WithSkipBucketize(skip bool) TransportOption
WithSkipBucketize is a TransportOption that skips the bucketization of the host. This is useful for transports that talk to an unbounded number of hosts, where bucketization would cause excessive metric cardinality. If true, the host label will be set to "unbucketized".
type TransportUnwrapper ¶ added in v1.0.3
type TransportUnwrapper interface {
Unwrap() http.RoundTripper
}
TransportUnwrapper is implemented by RoundTripper wrappers that can expose their underlying transport. This follows the same convention as errors.Unwrap.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cloudevents provides helpers for creating CloudEvents HTTP clients and targets that are instrumented with httpmetrics middleware.
|
Package cloudevents provides helpers for creating CloudEvents HTTP clients and targets that are instrumented with httpmetrics middleware. |