correlation

Documentation

Overview

Package correlation is the primary entrypoint into LabKit's correlation utilities.

Provided Functionality

Provides http middlewares for general purpose use cases:

Generating a correlation-id for an incoming HTTP request using .

Obtaining the correlation-id from the context.

Injecting the correlation-id from the context into an outgoing request.

Still to be implemented

Extracting a correlation-id from an incoming HTTP request into the context.

Index

• Constants
• func ContextWithClientName(ctx context.Context, clientName string) context.Context
• func ContextWithCorrelation(ctx context.Context, correlationID string) context.Context
• func ExtractClientNameFromContext(ctx context.Context) string
• func ExtractFromContext(ctx context.Context) string
• func ExtractFromContextOrGenerate(ctx context.Context) string
• func InjectCorrelationID(h http.Handler, opts ...InboundHandlerOption) http.Handler
• func NewInstrumentedRoundTripper(delegate http.RoundTripper, opts ...InstrumentedRoundTripperOption) http.RoundTripper
• func RandomID() (string, error)
• func SafeRandomID() string
• type InboundHandlerOption
  • func WithCIDRsTrustedForPropagation(trustedCIDRs []string) InboundHandlerOption
  • func WithCIDRsTrustedForXForwardedFor(trustedCIDRs []string) InboundHandlerOption
  • func WithPropagation() InboundHandlerOption
  • func WithSetResponseHeader() InboundHandlerOption
• type InstrumentedRoundTripperOption
  • func WithClientName(clientName string) InstrumentedRoundTripperOption
• type XFFAllowedFunc

Examples

• ExtractFromContext (ForLogging)
• InjectCorrelationID
• NewInstrumentedRoundTripper

Constants

const FieldName = "correlation_id"

FieldName is the field used in structured logs that represents the correlationID.

Functions

func ContextWithClientName

func ContextWithClientName(ctx context.Context, clientName string) context.Context

ContextWithClientName will create a new context containing client_name metadata.

func ContextWithCorrelation

func ContextWithCorrelation(ctx context.Context, correlationID string) context.Context

ContextWithCorrelation will create a new context containing the provided Correlation-ID value. This can be extracted using ExtractFromContext.

func ExtractClientNameFromContext

func ExtractClientNameFromContext(ctx context.Context) string

ExtractClientNameFromContext extracts client name from incoming context. It will return an empty string if client name does not exist in the context.

func ExtractFromContext

func ExtractFromContext(ctx context.Context) string

ExtractFromContext extracts the CollectionID from the provided context. Returns an empty string if it's unable to extract the CorrelationID for any reason.

Example (ForLogging)

package main

import (
	"context"
	"log"

	"gitlab.com/gitlab-org/labkit/correlation"
)

func main() {
	ctx := context.Background()
	correlationID := correlation.ExtractFromContext(ctx)
	log.Printf("event occurred. cid=%v", correlationID)
}

func ExtractFromContextOrGenerate

func ExtractFromContextOrGenerate(ctx context.Context) string

ExtractFromContextOrGenerate extracts the CollectionID from the provided context or generates a random id if context does not contain one.

func InjectCorrelationID

func InjectCorrelationID(h http.Handler, opts ...InboundHandlerOption) http.Handler

InjectCorrelationID is an HTTP middleware to generate an Correlation-ID for the incoming request, or extract the existing Correlation-ID from the incoming request. By default, any upstream Correlation-ID, passed in via the `X-Request-ID` header will be ignored. To enable this behaviour, the `WithPropagation` option should be passed into the options. Whether the Correlation-ID is generated or propagated, once inside this handler the request context will have a Correlation-ID associated with it.

Example

package main

import (
	"fmt"
	"net/http"

	"gitlab.com/gitlab-org/labkit/correlation"
)

func main() {
	http.ListenAndServe(":8080",
		correlation.InjectCorrelationID(
			http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
				clientName := correlation.ExtractClientNameFromContext(r.Context())
				fmt.Fprintf(w, clientName)
			})))
}

func NewInstrumentedRoundTripper

func NewInstrumentedRoundTripper(delegate http.RoundTripper, opts ...InstrumentedRoundTripperOption) http.RoundTripper

NewInstrumentedRoundTripper acts as a "client-middleware" for outbound http requests adding instrumentation to the outbound request and then delegating to the underlying transport.

If will extract the current Correlation-ID from the request context and pass this via the X-Request-ID request header to downstream services.

Example

package main

import (
	"context"
	"log"
	"net/http"

	"gitlab.com/gitlab-org/labkit/correlation"
)

func main() {
	// correlation.NewInstrumentedRoundTripper will set the appropriate headers
	// on any outbound requests
	httpTransport := correlation.NewInstrumentedRoundTripper(http.DefaultTransport)
	httpClient := &http.Client{
		Transport: httpTransport,
	}

	request, err := http.NewRequest("GET", "https://example.gitlab.com/api/v4/projects", nil)
	if err != nil {
		log.Fatalf("unable to send request: %v", err)
	}

	// Importantly, we need to set the context on the request
	ctx := correlation.ContextWithClientName(
		context.Background(),
		"clientname",
	)
	request = request.WithContext(ctx)
	_, err = httpClient.Do(request)
	if err != nil {
		log.Fatalf("unable to read response: %v", err)
	}
}

func RandomID

func RandomID() (string, error)

RandomID generates a random correlation ID. Deprecated: use SafeRandomID instead. Note, that this method will not return an error, it is here for compatibility reasons only.

func SafeRandomID

func SafeRandomID() string

SafeRandomID generates a random correlation ID.

Types

type InboundHandlerOption

type InboundHandlerOption func(*inboundHandlerConfig)

InboundHandlerOption will configure a correlation handler currently there are no options, but this gives us the option to extend the interface in a backwards compatible way.

func WithCIDRsTrustedForPropagation

func WithCIDRsTrustedForPropagation(trustedCIDRs []string) InboundHandlerOption

WithCIDRsTrustedForPropagation will configure the handler to set a list of trusted CIDR blocks to allow propagation of correlation_ids.

func WithCIDRsTrustedForXForwardedFor

func WithCIDRsTrustedForXForwardedFor(trustedCIDRs []string) InboundHandlerOption

WithCIDRsTrustedForXForwardedFor will configure the handler to trust X-Forwarded-For from trusted CIDR blocks.

func WithPropagation

func WithPropagation() InboundHandlerOption

WithPropagation will configure the handler to propagate existing correlation_ids passed in from upstream services. This is not the default behaviour.

func WithSetResponseHeader

func WithSetResponseHeader() InboundHandlerOption

WithSetResponseHeader will configure the handler to set the correlation_id in the http response headers.

type InstrumentedRoundTripperOption

type InstrumentedRoundTripperOption func(*instrumentedRoundTripperConfig)

InstrumentedRoundTripperOption will configure a correlation handler currently there are no options, but this gives us the option to extend the interface in a backwards compatible way.

func WithClientName

func WithClientName(clientName string) InstrumentedRoundTripperOption

WithClientName will configure the X-GitLab-Client-Name header on the http client.

type XFFAllowedFunc

type XFFAllowedFunc func(ip string) bool

XFFAllowedFunc decides whether X-Forwarded-For headers are to be trusted.