ddtrace

Documentation

Overview

Package ddtrace contains the interfaces that specify the implementations of Datadog's tracing library, as well as a set of sub-packages containing various implementations: our native implementation ("tracer") and a mock tracer to be used for testing ("mocktracer"). Additionally, package "ext" provides a set of tag names and values specific to Datadog's APM product.

To get started, visit the documentation for any of the packages you'd like to begin with by accessing the subdirectories of this package: https://godoc.org/github.com/DataDog/dd-trace-go/v2/ddtrace#pkg-subdirectories.

Example (Datadog)

The below example illustrates a simple use case using the "tracer" package, our native Datadog APM tracing client integration. For thorough documentation and further examples, visit its own godoc page.

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func main() {
	// Start the tracer and defer the Stop method.
	tracer.Start(tracer.WithAgentAddr("host:port"))
	defer tracer.Stop()

	// Start a root span.
	span := tracer.StartSpan("get.data")
	defer span.Finish()

	// Create a child of it, computing the time needed to read a file.
	child := span.StartChild("read.file")
	child.SetTag(ext.ResourceName, "test.json")

	fmt.Printf("128 bit trace id = %s\n", child.Context().TraceID())

	// Perform an operation.
	_, err := os.ReadFile("~/test.json")

	// We may finish the child span using the returned error. If it's
	// nil, it will be disregarded.
	child.Finish(tracer.WithError(err))
	if err != nil {
		log.Fatal(err)
	}
}

Example (Mocking)

The code below illustrates a scenario of how one could use a mock tracer in tests to assert that spans are created correctly.

package main

import (
	"github.com/DataDog/dd-trace-go/v2/ddtrace/mocktracer"
	"github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func main() {
	// Setup the test environment: start the mock tracer.
	mt := mocktracer.Start()
	defer mt.Stop()

	// Run test code: in this example we will simply create a span to illustrate.
	tracer.StartSpan("test.span").Finish()

	// Assert the results: query the mock tracer for finished spans.
	spans := mt.FinishedSpans()
	if len(spans) != 1 {
		// fail
		panic("expected 1 span")
	}
	if spans[0].OperationName() != "test.span" {
		// fail
		panic("unexpected operation name")
	}
}

Index

• type SpanContext

Examples

• Package (Datadog)
• Package (Mocking)

Types

type SpanContext

type SpanContext interface {
	// SpanID returns the span ID that this context is carrying.
	SpanID() uint64

	// TraceID returns the trace ID that this context is carrying.
	TraceID() string

	// TraceID128 returns the raw bytes of the 128-bit trace ID that this context is carrying.
	TraceIDBytes() [16]byte

	// TraceIDLower returns the lower part of the trace ID that this context is carrying.
	TraceIDLower() uint64

	// ForeachBaggageItem provides an iterator over the key/value pairs set as
	// baggage within this context. Iteration stops when the handler returns
	// false.
	ForeachBaggageItem(handler func(k, v string) bool)
}

SpanContext represents a span state that can propagate to descendant spans and across process boundaries. It contains all the information needed to spawn a direct descendant of the span that it belongs to. It can be used to create distributed tracing by propagating it using the provided interfaces.