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 InjectCorrelationID(h http.Handler, opts ...InboundHandlerOption) http.Handler
• func NewInstrumentedRoundTripper(delegate http.RoundTripper, opts ...InstrumentedRoundTripperOption) http.RoundTripper
• func RandomID() (string, error)
• type InboundHandlerOption
  • func WithPropagation() InboundHandlerOption
  • func WithSetResponseHeader() InboundHandlerOption
• type InstrumentedRoundTripperOption
  • func WithClientName(clientName string) InstrumentedRoundTripperOption

Examples

• ExtractFromContext (ForLogging)
• InjectCorrelationID
• NewInstrumentedRoundTripper

Constants

const FieldName = "correlation_id"

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 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 attempts to generate 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 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