httpmetrics

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.

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 GenerateRelatedTraceID ¶ added in v1.35.0

func GenerateRelatedTraceID(ctx context.Context) oteltrace.TraceID

GenerateRelatedTraceID returns a new trace id carrying the same GCP export decision as the trace in ctx, for re-rooting work without dangling links under sampling. Requires both services to run the same OTEL_TRACE_SAMPLING_RATE. Without a span in ctx the id is fully random. An all-zero (invalid) result is possible in principle; the SDK generates a fresh root id when an invalid id is planted, so no retry here.

package main

import (
	"context"

	"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/trace"
)

func main() {
	// Re-root work as its own trace whose export decision matches the
	// caller's: plant the related trace id (no span id) and the SDK adopts
	// it as a new root. Real servers receive the caller span context via
	// inbound propagation; the example plants one. See pkg/tracesplit for
	// the packaged version of this pattern.
	ctx := trace.ContextWithRemoteSpanContext(context.Background(),
		trace.NewSpanContext(trace.SpanContextConfig{
			TraceID:    trace.TraceID{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16},
			SpanID:     trace.SpanID{1, 2, 3, 4, 5, 6, 7, 8},
			TraceFlags: trace.FlagsSampled,
			Remote:     true,
		}))

	// Derive and link only when there is a real caller trace.
	var opts []trace.SpanStartOption
	if caller := trace.SpanContextFromContext(ctx); caller.IsValid() {
		ctx = trace.ContextWithSpanContext(ctx, trace.NewSpanContext(trace.SpanContextConfig{
			TraceID: httpmetrics.GenerateRelatedTraceID(ctx),
		}))
		opts = append(opts, trace.WithLinks(trace.Link{SpanContext: caller}))
	}
	_, span := otel.Tracer("example").Start(ctx, "build", opts...)
	defer span.End()
}

Output:

func GitHubPathBucket ¶ added in v1.41.0

func GitHubPathBucket(path string) string

GitHubPathBucket maps a GitHub REST API path to its bounded-cardinality bucket (e.g. "/repos/{org}/{repo}/pulls/{number}"), the same bucket the instrumented transport stamps on github_api_call log lines. Paths matching no known endpoint collapse into "unknown_gh_path". It is exported so services that front the GitHub API can label their own metrics consistently.

func Handler ¶

func Handler(name string, handler http.Handler) http.Handler

Handler wraps a given http handler in standard metrics handlers.

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.

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 ScrapeDiskUsage(ctx context.Context)

func ServeMetrics ¶

func ServeMetrics()

ServeMetrics serves the metrics endpoint if the METRICS_PORT env var is set.

func ServerRevisionHandler ¶ added in v1.47.7

func ServerRevisionHandler(revision string, handler http.Handler) http.Handler

ServerRevisionHandler adds revision to HTTP responses before calling handler, including responses with error statuses. Pass the service's K_REVISION value at startup; an empty revision leaves responses unchanged. It passes the original ResponseWriter through, preserving support for streaming and hijacking. Place it inside authentication middleware to report only on authenticated requests. The handler is safe for concurrent use if handler is.

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)

func main() {
	// In Cloud Run, supply the process's K_REVISION value at startup.
	handler := httpmetrics.ServerRevisionHandler("api-00042-abc", http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
		w.WriteHeader(http.StatusNoContent)
	}))
	response := httptest.NewRecorder()
	handler.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/", nil))
	fmt.Println(response.Header().Get(httpmetrics.ServerRevisionHeader))
}

Output:
api-00042-abc

func ServerRevisionStreamInterceptor ¶ added in v1.47.7

func ServerRevisionStreamInterceptor(revision string) grpc.StreamServerInterceptor

ServerRevisionStreamInterceptor identifies the serving revision in streaming gRPC response headers, including application errors. Metadata is queued for the stream's normal header send. Pass the service's K_REVISION value at startup. An empty revision emits no metadata. Install it once, after authentication, and reserve ServerRevisionHeader for this interceptor. It is safe for concurrent use. If headers cannot be added (for example, an earlier interceptor already sent them), the application handler still runs unchanged.

package main

import (
	"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
	"google.golang.org/grpc"
)

func main() {
	server := grpc.NewServer(grpc.ChainStreamInterceptor(
		// Add authentication before the revision interceptor.
		httpmetrics.ServerRevisionStreamInterceptor("api-00042-abc"),
	))
	defer server.Stop()
}

Output:

func ServerRevisionUnaryInterceptor ¶ added in v1.47.7

func ServerRevisionUnaryInterceptor(revision string) grpc.UnaryServerInterceptor

ServerRevisionUnaryInterceptor identifies the serving revision in unary gRPC response headers, including application errors. Pass the service's K_REVISION value at startup. An empty revision emits no metadata. Install it once, after authentication, and reserve ServerRevisionHeader for this interceptor. It is safe for concurrent use. If headers cannot be added (for example, an earlier interceptor already sent them), the application handler still runs unchanged.

package main

import (
	"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
	"google.golang.org/grpc"
)

func main() {
	server := grpc.NewServer(grpc.ChainUnaryInterceptor(
		// Add authentication before the revision interceptor.
		httpmetrics.ServerRevisionUnaryInterceptor("api-00042-abc"),
	))
	defer server.Stop()
}

Output:

func SetBucketSuffixes ¶

func SetBucketSuffixes(bs map[string]string)

SetBucketSuffixes configures suffix-based host-to-label mappings. Must be called before the first HTTP request for the mappings to take effect.

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 ¶

func SetBuckets(b map[string]string)

SetBuckets configures exact host-to-label mappings. Must be called before the first HTTP request for the mappings to take effect.

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

func SetupMetrics(ctx context.Context) func()

SetupMetrics setups a prometheus exporter for otel metrics, and starts memusage.Heartbeat, which logs the container's memory use while it is at or over half its limit. The heartbeat outlives ctx so that it still logs while the process drains after SIGTERM.

Expected usage:

defer metrics.SetupMetrics(ctx)()

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 ¶

func SetupTracer(ctx context.Context) func()

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)()

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 SetupTracerWith ¶ added in v1.55.1

func SetupTracerWith(ctx context.Context, opts ...TracerOption) func()

SetupTracerWith is SetupTracer configured by opts.

package main

import (
	"context"

	"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)

func main() {
	// A process that cannot reach the metadata server skips the probe; an
	// exporter named in OTEL_TRACES_EXPORTER still installs.
	ctx := context.Background()
	cleanup := httpmetrics.SetupTracerWith(ctx, httpmetrics.NoGCPDetection())
	defer cleanup()
}

Output:

func WithGitHubAppID ¶ added in v1.0.4

func WithGitHubAppID(ctx context.Context, appID int64) context.Context

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

func WithGitHubInstallationID(ctx context.Context, installationID int64) context.Context

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.

package main

import (
	"net/http"

	"github.com/chainguard-dev/terraform-infra-common/pkg/httpmetrics"
)

func main() {
	t := httpmetrics.WrapTransport(http.DefaultTransport)
	_ = t
}

Output:

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: