README
¶
tracr
simple lib for retrieving (or creating) and adding a correlation id / trace id to the context
TODO - Build / Release Pipe
tl;dr ?
Have a look at the chi, gin or stdlib examples.
(coming soon, Gorilla Mux and Echo)
correlation-id
tracr is a Go lib that allows clients to add / retrieve a correlation id header (with header name of their choice) to / from the current go context.
The library provides the following:
1. Middleware for incoming requests
The middleware checks for a correlation ID header in the current request. If none is found, it generates a new correlation ID and adds it to the request context.
Correlation ID generation
nb: If no correlation ID is found in the context, a new correlation id will be generated and added to the context:
- Users can provide their own correlation id generator function, when instantiating the middleware. OR
- The library, https://github.com/gofrs/uuid, will be used by default to generate the correlation id (in the form of a uuid)
Preferred Header Name
During middleware instantiation, users can provide a func that will return the preferred name for the correlation id http header.
e.g. x-correlation-id, x-request-id, trace-id, trace_id, etc...
If no names are provided, the default header will be used: (nb: header names are case insensitive)
x-correlation-id
2. Adding correlation id to outgoing requests
See request.go.
A method is provided to allow the addition of a correlation id (and correlation id http header) to outgoing requests
3. Add middleware that logs all http request
See ./middleware/http_logger.go. See example usage in cmd/examples/stdlib/stdlib.go
Installation
Installation with go get.
go get -u github.com/micklove/tracr
Examples
See the examples folder, for chi, gin and stdlib
TODO - Diagram
add mermaid diagram(s)
References
Pages reviewed / consulted / borrowed from, when coming up with this lib
- https://github.com/auroratechnologies/vangoh
- https://kevin.burke.dev/kevin/how-to-write-go-middleware/
- https://community.developers.refinitiv.com/questions/57029/how-to-generate-signature-in-golang-any-one-help-m.html
- https://www.reddit.com/r/golang/comments/mnht8z/getting_response_headers_and_body_in_middleware/
- https://medium.com/@matryer/writing-middleware-in-golang-and-how-go-makes-it-so-much-fun-4375c1246e81
- https://upgear.io/blog/golang-tip-wrapping-http-response-writer-for-middleware/
- https://github.com/alexsergivan/blog-examples/blob/master/middleware/main.go
Issues to consider
If an error occurs in the middleware func, the current implementation will just write an http 500 to to the response, if there is an issue retrieving the correlation id - TODO - add a method to override this behaviour
TODO - contributing
Documentation
¶
Index ¶
- Variables
- func AddCorrelationIDToRequest(ctx context.Context, req *http.Request, options CorrelationIDOptions) (*http.Request, error)
- func ContextWithCID(ctx context.Context, correlationID string, cidGenerator CorrelationIDGenerator) (context.Context, error)
- func FromContext[T any](key contextKey, ctx context.Context) (T, error)
- func GetCID(ctx context.Context) (string, error)
- type CorrelationIDGenerator
- type CorrelationIDHeaderFn
- type CorrelationIDOptions
- type Service
Constants ¶
This section is empty.
Variables ¶
var ( ErrContextIncompatibleType = errors.New("value from context did not match expected type") ErrContextValueNotFound = errors.New("context value not found") )
Functions ¶
func AddCorrelationIDToRequest ¶
func AddCorrelationIDToRequest(ctx context.Context, req *http.Request, options CorrelationIDOptions) (*http.Request, error)
AddCorrelationIDToRequest - For http clients. Adds a CorrelationID, from the given context, as a request Header to the request. If the context does not contain an existing CorrelationID, a new one will be generated using the correlationIDGeneratorFn provided. Note, If context or request are null, new ones will be returned
func ContextWithCID ¶
func ContextWithCID(ctx context.Context, correlationID string, cidGenerator CorrelationIDGenerator) (context.Context, error)
ContextWithCID adds the correlation id to the given context. Context is immutable so a new context is returned. If not correlation ID exists, a new one is generated, using the provided correlation id generator.
func FromContext ¶
FromContext - Get value from context
Types ¶
type CorrelationIDGenerator ¶
type CorrelationIDHeaderFn ¶
CorrelationIDHeaderFn - allows users of the lib to use their own correlation id http header name strategy e.g. x-correlation-id, trace-id, request-id, etc.. Allows clients to load the http header name from the ENV, config file, etc...
type CorrelationIDOptions ¶
type CorrelationIDOptions struct {
CorrelationIDHttpHeaderFn CorrelationIDHeaderFn
CorrelationIDGeneratorFn CorrelationIDGenerator
}
CorrelationIDOptions Struct to be passed into tracr methods to allow retrieval of the preferred correlation id http header name, e.g. x-correlation-id, x-tracer-id, x-request-id, etc... and the actual correlation id Note, a struct, with funcs is used here, to allow callers to use whatever method / strategy is preferred to retrieve the header name, env variables, config file, db, ssm, etc... and the correlation id that will be generated if no correlation ID was provided in the request.
func (*CorrelationIDOptions) GetCorrelationID ¶
func (o *CorrelationIDOptions) GetCorrelationID() (string, error)
GetCorrelationID - returns a correlation ID Allows users of the lib to use their own correlation id generation strategy e.g. Database, different library, etc...
func (*CorrelationIDOptions) GetCorrelationIDHttpHeaderName ¶
func (o *CorrelationIDOptions) GetCorrelationIDHttpHeaderName() (string, error)
Source Files
Directories