traceid

Documentation

Overview

Package traceid allows storing and retrieving a Trace ID value associated with a context.Context and an HTTP request.

It provides functions to set and retrieve the trace ID from both the Context and the HTTP request headers.

The Trace ID is typically used in distributed systems to track requests as they propagate through different services. It can be used for debugging, performance monitoring, and troubleshooting purposes.

The Trace ID is expected to be a string that follows the regex pattern "^[0-9A-Za-z\-\_\.]{1,64}$". If the Trace ID does not match this pattern, the default value is used instead.

Index

• Constants
• func FromContext(ctx context.Context, defaultValue string) string
• func FromHTTPRequestHeader(r *http.Request, header, defaultValue string) string
• func NewContext(ctx context.Context, id string) context.Context
• func SetHTTPRequestHeaderFromContext(ctx context.Context, r *http.Request, header, defaultValue string) string

Examples

• FromContext
• FromHTTPRequestHeader
• NewContext
• SetHTTPRequestHeaderFromContext

Constants

const (
	// DefaultHeader is the default header name for the trace ID.
	DefaultHeader = "X-Request-ID"

	// DefaultValue is the default trace ID value.
	DefaultValue = ""

	// DefaultLogKey is the default log field key for the Trace ID.
	DefaultLogKey = "traceid"
)

Functions

func FromContext

func FromContext(ctx context.Context, defaultValue string) string

FromContext returns the trace ID associated with the context. If no trace ID is associated, then the default value returned.

Example

package main

import (
	"context"
	"fmt"

	"github.com/Vonage/gosrvlib/pkg/traceid"
)

func main() {
	// context without set id, should return the default value
	id1 := traceid.FromContext(context.Background(), "default-1-206951")

	fmt.Println(id1)

	// context with set id, should return the existing value
	ctx := traceid.NewContext(context.Background(), "default-2-616841")
	id2 := traceid.FromContext(ctx, "default-3-67890")

	fmt.Println(id2)

}

Output:

default-1-206951
default-2-616841

func FromHTTPRequestHeader

func FromHTTPRequestHeader(r *http.Request, header, defaultValue string) string

FromHTTPRequestHeader retrieves the trace ID from an HTTP Request. If not found the default value is returned instead.

Example

package main

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

	"github.com/Vonage/gosrvlib/pkg/traceid"
)

func main() {
	ctx := context.Background()

	// header not set should return default
	r1, err := http.NewRequestWithContext(ctx, http.MethodGet, "/", nil)
	if err != nil {
		log.Fatal(err)
	}

	v1 := traceid.FromHTTPRequestHeader(r1, traceid.DefaultHeader, "default-1-103993")

	fmt.Println(v1)

	// header set should return actual value
	r2, err := http.NewRequestWithContext(ctx, http.MethodGet, "/", nil)
	if err != nil {
		log.Fatal(err)
	}

	r2.Header.Add(traceid.DefaultHeader, "test-1-413579")

	v2 := traceid.FromHTTPRequestHeader(r2, traceid.DefaultHeader, "default-2-968041")

	fmt.Println(v2)

}

Output:

default-1-103993
test-1-413579

func NewContext

func NewContext(ctx context.Context, id string) context.Context

NewContext stores the trace ID value in the context if not already present.

Example

package main

import (
	"context"
	"fmt"

	"github.com/Vonage/gosrvlib/pkg/traceid"
)

func main() {
	// store value in context
	ctx := traceid.NewContext(context.Background(), "test-1-218549")

	// load the value from context and ignore default
	el1 := traceid.FromContext(ctx, "default-104173")

	fmt.Println(el1)

	// do not override the value in context
	ctx1 := traceid.NewContext(ctx, "test-2-563011")

	fmt.Println(ctx1)

}

Output:

test-1-218549
context.Background.WithValue(traceid.ctxKey, test-1-218549)

func SetHTTPRequestHeaderFromContext

func SetHTTPRequestHeaderFromContext(ctx context.Context, r *http.Request, header, defaultValue string) string

SetHTTPRequestHeaderFromContext set the trace ID HTTP Request Header with the value retrieved from the context. If the traceid is not found in the context, then the default value is set. Returns the set ID.

Example

package main

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

	"github.com/Vonage/gosrvlib/pkg/traceid"
)

func main() {
	ctx := context.Background()

	// header not set
	r1, err := http.NewRequestWithContext(ctx, http.MethodGet, "/", nil)
	if err != nil {
		log.Fatal(err)
	}

	id1 := traceid.SetHTTPRequestHeaderFromContext(context.Background(), r1, traceid.DefaultHeader, traceid.DefaultValue)

	fmt.Println(id1)
	fmt.Println(r1.Header.Get(traceid.DefaultHeader))

	// header set
	r2, err := http.NewRequestWithContext(ctx, http.MethodGet, "/", nil)
	if err != nil {
		log.Fatal(err)
	}

	ctx = traceid.NewContext(ctx, "test-904117")
	r2 = r2.WithContext(ctx)

	id2 := traceid.SetHTTPRequestHeaderFromContext(ctx, r2, traceid.DefaultHeader, traceid.DefaultValue)

	fmt.Println(id2)
	fmt.Println(r2.Header.Get(traceid.DefaultHeader))

}

Output:


test-904117
test-904117