instrumentation

package
v2.12.0-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 14, 2026 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 19 Imported by: 71

Documentation

Index

Constants

View Source 
const (
	TelemetryOriginDefault = telemetry.OriginDefault
	TelemetryOriginEnvVar  = telemetry.OriginEnvVar
)
View Source 
const (
	// ServiceSourceWithServiceOption is the service source value used when the service
	// name is explicitly set via a WithService option.
	ServiceSourceWithServiceOption = "opt.with_service"
)
View Source 
const (
	// TelemetryNamespaceIAST is the namespace for IAST telemetry
	TelemetryNamespaceIAST = telemetry.NamespaceIAST
)

Variables

This section is empty.

Functions

func GetPackages 

func GetPackages() map[Package]PackageInfo

GetPackages returns a map of Package to the corresponding instrumented module.

func Register 

func Register(pkg Package, info PackageInfo)

Register registers a new Package instrumentation. Panics if called multiple times for the same Package.

func ReloadConfig 

func ReloadConfig()

ReloadConfig reloads config read from environment variables. This is useful for tests.

func ServiceNameWithSource added in v2.8.0 

func ServiceNameWithSource(name string, source string) tracer.StartSpanOption

ServiceNameWithSource returns a StartSpanOption that sets both the service name and its source. The source tracks the origin of the service name override for _dd.svc_src.

func Version added in v2.1.0 

func Version() string

Version returns the version of the dd-trace-go package.

Types

type AppEndpointAttributes added in v2.7.0 

type AppEndpointAttributes = telemetry.AppEndpointAttributes

type Component 

type Component int
const (
	ComponentDefault Component = iota
	ComponentServer
	ComponentClient
	ComponentProducer
	ComponentConsumer
)

type HeaderTags 

type HeaderTags interface {
	Iter(f func(header string, tag string))
}

func NewHeaderTags 

func NewHeaderTags(headers []string) HeaderTags

type Instrumentation 

type Instrumentation struct {
	// contains filtered or unexported fields
}

Instrumentation represents instrumentation for a package.

func Load 

func Load(pkg Package) *Instrumentation

Load attempts to load the requested package instrumentation. It panics if the package has not been registered.

func RegisterAndLoad 

func RegisterAndLoad(pkg Package, info PackageInfo) *Instrumentation

RegisterAndLoad registers a new Package instrumentation and immediately loads it, returning the associated Instrumentation instance. Panics if the package has already been registered previously.

func (*Instrumentation) APISecurityEndpointCollectionEnabled added in v2.7.0 

func (i *Instrumentation) APISecurityEndpointCollectionEnabled() bool

func (*Instrumentation) ActiveSpanKey 

func (i *Instrumentation) ActiveSpanKey() any

func (*Instrumentation) AnalyticsRate 

func (i *Instrumentation) AnalyticsRate(defaultGlobal bool) float64

func (*Instrumentation) AppSecEnabled 

func (i *Instrumentation) AppSecEnabled() bool

func (*Instrumentation) AppSecRASPEnabled 

func (i *Instrumentation) AppSecRASPEnabled() bool

func (*Instrumentation) CaptureStackTrace 

func (i *Instrumentation) CaptureStackTrace(category StackTraceCategory, options ...StackTraceOption) *StackTrace

CaptureStackTrace captures a stack trace for an event in category. It returns nil when no frames are captured or when a vulnerability or exploit event has no correlation ID. The caller is responsible for applying its product-specific enablement configuration.

func (*Instrumentation) DataStreamsEnabled 

func (i *Instrumentation) DataStreamsEnabled() bool

func (*Instrumentation) GlobalAnalyticsRate 

func (i *Instrumentation) GlobalAnalyticsRate() float64

func (*Instrumentation) HTTPHeadersAsTags 

func (i *Instrumentation) HTTPHeadersAsTags() HeaderTags

func (*Instrumentation) Logger 

func (i *Instrumentation) Logger() Logger

func (*Instrumentation) OperationName 

func (i *Instrumentation) OperationName(component Component, opCtx OperationContext) string

OperationName returns the operation name to be set for the given instrumentation component.

func (*Instrumentation) PopExecutionTraced added in v2.7.0 

func (i *Instrumentation) PopExecutionTraced()

PopExecutionTraced pops the top executionTracedKey from the GLS stack. Must be paired with WithExecutionTraced when the traced scope ends.

func (*Instrumentation) RecordStackTrace 

func (i *Instrumentation) RecordStackTrace(span *tracer.Span, trace *StackTrace) bool

RecordStackTrace submits trace to the local root span's _dd.stack meta_struct entry. Calls from IAST, AppSec, and other producers are aggregated by event category and encoded when the span is serialized. Nil traces, traces without frames, and vulnerability or exploit traces without an ID are ignored. The caller is responsible for product-specific enablement.

The return value reports whether the trace passed validation and was submitted to the root span. The span API does not report whether a finished root rejected the tag.

func (*Instrumentation) ServiceName 

func (i *Instrumentation) ServiceName(component Component, opCtx OperationContext) string

ServiceName returns the default service name to be set for the given instrumentation component.

func (*Instrumentation) StatsdClient 

func (i *Instrumentation) StatsdClient(extraTags []string) (StatsdClient, error)

func (*Instrumentation) TelemetryLog added in v2.4.0 

func (i *Instrumentation) TelemetryLog() *telemetrylog.Logger

func (*Instrumentation) TelemetryMetrics 

func (i *Instrumentation) TelemetryMetrics() TelemetryMetricsClient

TelemetryMetrics returns the TelemetryMetricsClient that instrumentation should use to submit internal telemetry metrics data.

IMPORTANT: If you are not sure what this is for, you should probably be using *Instrumentation.StatsdClient instead.

func (*Instrumentation) TelemetryProductStartError 

func (i *Instrumentation) TelemetryProductStartError(ns TelemetryNamespace, err error)

TelemetryProductStartError declares a telemetry product as having failed to start because of the specified error.

func (*Instrumentation) TelemetryProductStarted 

func (i *Instrumentation) TelemetryProductStarted(ns TelemetryNamespace)

TelemetryProductStarted declares a telemetry product as having started.

func (*Instrumentation) TelemetryProductStopped 

func (i *Instrumentation) TelemetryProductStopped(ns TelemetryNamespace)

TelemetryProductStopped declares a telemetry product as having stopped.

func (*Instrumentation) TelemetryRegisterAppConfig added in v2.4.0 

func (i *Instrumentation) TelemetryRegisterAppConfig(key string, value any, origin TelemetryOrigin)

func (*Instrumentation) TelemetryRegisterAppEndpoint added in v2.7.0 

func (i *Instrumentation) TelemetryRegisterAppEndpoint(opName string, resName string, attrs AppEndpointAttributes)

func (*Instrumentation) TracerInitialized 

func (i *Instrumentation) TracerInitialized() bool

TracerInitialized returns whether the global tracer has been initialized or not.

func (*Instrumentation) WithExecutionTraced 

func (i *Instrumentation) WithExecutionTraced(ctx context.Context) context.Context

WithExecutionTraced marks ctx as being associated with an execution trace task. It is assumed that ctx already contains a trace task. The caller is responsible for ending the task.

This is intended for a specific case where the database/sql contrib package only creates spans *after* an operation, in case the operation was unavailable, and thus execution trace tasks tied to the span only capture the very end. This function enables creating a task *before* creating a span, and communicating to the APM tracer that it does not need to create a task. In general, APM instrumentation should prefer creating tasks around the operation rather than after the fact, if possible.

type Logger 

type Logger interface {
	Debug(msg string, args ...any)
	Info(msg string, args ...any)
	Warn(msg string, args ...any)
	Error(msg string, args ...any)
}

type OperationContext 

type OperationContext map[string]string

OperationContext holds metadata about an instrumentation operation.

type Package 

type Package string
const (
	Package99DesignsGQLGen      Package = "99designs/gqlgen"
	PackageAerospikeClientGoV7  Package = "aerospike/aerospike-client-go.v7"
	PackageAWSSDKGo             Package = "aws/aws-sdk-go"
	PackageAWSSDKGoV2           Package = "aws/aws-sdk-go-v2"
	PackageAWSDatadogLambdaGo   Package = "aws/datadog-lambda-go"
	PackageBradfitzGoMemcache   Package = "bradfitz/gomemcache"
	PackageGCPPubsub            Package = "cloud.google.com/go/pubsub.v1"
	PackageGCPPubsubV2          Package = "cloud.google.com/go/pubsub.v2"
	PackageConfluentKafkaGo     Package = "confluentinc/confluent-kafka-go/kafka"
	PackageConfluentKafkaGoV2   Package = "confluentinc/confluent-kafka-go/kafka.v2"
	PackageDatabaseSQL          Package = "database/sql"
	PackageDimfeldHTTPTreeMuxV5 Package = "dimfeld/httptreemux.v5"
	PackageGoElasticSearchV6    Package = "elastic/go-elasticsearch.v6"
	PackageEmickleiGoRestfulV3  Package = "emicklei/go-restful.v3"
	PackageGin                  Package = "gin-gonic/gin"
	PackageGlobalsignMgo        Package = "globalsign/mgo"
	PackageMongoDriver          Package = "go.mongodb.org/mongo-driver"
	PackageMongoDriverV2        Package = "go.mongodb.org/mongo-driver.v2"
	PackageGoUberOrgZap         Package = "go.uber.org/zap"
	PackageChi                  Package = "go-chi/chi"
	PackageChiV5                Package = "go-chi/chi.v5"
	PackageGoPGV10              Package = "go-pg/pg.v10"
	PackageGoRedis              Package = "go-redis/redis"
	PackageGoRedisV7            Package = "go-redis/redis.v7"
	PackageGoRedisV8            Package = "go-redis/redis.v8"
	PackageGoCQL                Package = "gocql/gocql"
	PackageGoFiberV2            Package = "gofiber/fiber.v2"
	PackageRedigo               Package = "gomodule/redigo"
	PackageGoogleAPI            Package = "google.golang.org/api"
	PackageGRPC                 Package = "google.golang.org/grpc"

	PackageNetHTTP   Package = "net/http"
	PackageIBMSarama Package = "IBM/sarama"

	PackageValyalaFastHTTP           Package = "valyala/fasthttp"
	PackageUrfaveNegroni             Package = "urfave/negroni"
	PackageTwitchTVTwirp             Package = "twitchtv/twirp"
	PackageTidwallBuntDB             Package = "tidwall/buntdb"
	PackageSyndtrGoLevelDB           Package = "syndtr/goleveldb"
	PackageSirupsenLogrus            Package = "sirupsen/logrus"
	PackageRsZerolog                 Package = "rs/zerolog"
	PackageShopifySarama             Package = "Shopify/sarama"
	PackageSegmentioKafkaGo          Package = "segmentio/kafka-go"
	PackageTwmbFranzGo               Package = "twmb/franz-go"
	PackageRedisGoRedisV9            Package = "redis/go-redis.v9"
	PackageOlivereElasticV5          Package = "olivere/elastic.v5"
	PackageMiekgDNS                  Package = "miekg/dns"
	PackageLabstackEchoV4            Package = "labstack/echo.v4"
	PackageLabstackEchoV5            Package = "labstack/echo.v5"
	PackageK8SClientGo               Package = "k8s.io/client-go"
	PackageK8SGatewayAPI             Package = "k8s.io/gateway-api"
	PackageJulienschmidtHTTPRouter   Package = "julienschmidt/httprouter"
	PackageMark3LabsMCPGo            Package = "mark3labs/mcp-go"
	PackageJmoironSQLx               Package = "jmoiron/sqlx"
	PackageJackcPGXV5                Package = "jackc/pgx.v5"
	PackageHashicorpConsulAPI        Package = "hashicorp/consul"
	PackageHashicorpVaultAPI         Package = "hashicorp/vault"
	PackageGraphQLGoGraphQL          Package = "graphql-go/graphql"
	PackageGraphGophersGraphQLGo     Package = "graph-gophers/graphql-go"
	PackageGormIOGormV1              Package = "gorm.io/gorm.v1"
	PackageGorillaMux                Package = "gorilla/mux"
	PackageUptraceBun                Package = "uptrace/bun"
	PackageLogSlog                   Package = "log/slog"
	PackageModelContextProtocolGoSDK Package = "modelcontextprotocol/go-sdk"

	PackageValkeyIoValkeyGo               Package = "valkey-io/valkey-go"
	PackageAzureAPIMCallout               Package = "azure/apim-callout"
	PackageEnvoyProxyGoControlPlane       Package = "envoyproxy/go-control-plane"
	PackageHAProxyStreamProcessingOffload Package = "haproxy/stream-processing-offload"
	PackageOS                             Package = "os"
	PackageRedisRueidis                   Package = "redis/rueidis"
)
const (
	PackageEmickleiGoRestful Package = "emicklei/go-restful"
	PackageGaryburdRedigo    Package = "garyburd/redigo"
	PackageGopkgJinZhuGormV1 Package = "gopkg.in/jinzhu/gorm.v1"
	PackageGojiV1Web         Package = "zenazn/goji.v1/web"
	PackageJinzhuGorm        Package = "jinzhu/gorm"
	PackageLabstackEcho      Package = "labstack/echo"
)

These packages have been removed in v2, but they are kept here for the transitional version.

type PackageInfo 

type PackageInfo struct {
	TracedPackage string
	IsStdLib      bool
	EnvVarPrefix  string
	// contains filtered or unexported fields
}

type ServiceOverride added in v2.8.0 

type ServiceOverride = internal.ServiceOverride

ServiceOverride bundles a service name with its source for use with span.SetTag(ext.KeyServiceSource, instrumentation.ServiceOverride{...}). This should be used instead of span.SetTag(ext.ServiceName, ...) to preserve the service source information.

type StackFrame 

type StackFrame = stacktrace.StackFrame

StackFrame is a single frame of a StackTrace.

type StackTrace 

type StackTrace = stacktrace.Event

StackTrace is a stack-trace event captured by an Instrumentation. Its fields must not be mutated after passing it to Instrumentation.RecordStackTrace.

type StackTraceCategory 

type StackTraceCategory = stacktrace.EventCategory

StackTraceCategory identifies the kind of event associated with a stack trace. 

const (
	// StackTraceCategoryException identifies an exception stack trace.
	StackTraceCategoryException StackTraceCategory = stacktrace.ExceptionEvent
	// StackTraceCategoryVulnerability identifies a vulnerability stack trace.
	StackTraceCategoryVulnerability StackTraceCategory = stacktrace.VulnerabilityEvent
	// StackTraceCategoryExploit identifies an exploit stack trace.
	StackTraceCategoryExploit StackTraceCategory = stacktrace.ExploitEvent
)

type StackTraceOption 

type StackTraceOption = stacktrace.Option

StackTraceOption configures a captured stack-trace event. Values are created by the WithStackTrace functions in this package.

func WithStackTraceDepth 

func WithStackTraceDepth(depth int) StackTraceOption

WithStackTraceDepth sets the maximum number of frames to capture. A non-positive depth uses the default depth.

func WithStackTraceID 

func WithStackTraceID(id string) StackTraceOption

WithStackTraceID sets the event correlation ID. Vulnerability and exploit stack traces require a non-empty ID.

func WithStackTraceMessage 

func WithStackTraceMessage(message string) StackTraceOption

WithStackTraceMessage sets the event message.

func WithStackTraceSkip 

func WithStackTraceSkip(skip int) StackTraceOption

WithStackTraceSkip sets the number of caller frames to skip after the stacktrace capture machinery. Negative values are treated as zero.

func WithStackTraceType 

func WithStackTraceType(eventType string) StackTraceOption

WithStackTraceType sets the event type.

type StatsdClient 

type StatsdClient = internal.StatsdClient

type TelemetryMetric 

type TelemetryMetric = telemetry.MetricHandle

TelemetryMetric is a handle to a telemetry metric.

type TelemetryMetrics 

type TelemetryMetrics interface {
	// Count obtains a [TelemetryMetric] for a counter (representing the sum of
	// submitted values for a given interval).
	Count(ns telemetry.Namespace, name string, tags []string) TelemetryMetric
	// Rate obtains a [TelemetryMetric] for a rate metric (representing the value
	// per interval).
	Rate(ns telemetry.Namespace, name string, tags []string) TelemetryMetric
	// Count obtains a [TelemetryMetric] for a gauge (representing the last
	// submitted value for a given interval).
	Gauge(ns telemetry.Namespace, name string, tags []string) TelemetryMetric
	// Distribution obtains a [TelemetryMetric] for a distribution metric
	// (representing the distribution of submitted values for a given interval).
	Distribution(ns telemetry.Namespace, name string, tags []string) TelemetryMetric
}

TelemetryMetrics is the interface used to submit instrumentation telemetry metrics data.

IMPORTANT: If you are not sure what this is for, you should probably be using StatsdClient instead.

type TelemetryMetricsClient 

type TelemetryMetricsClient interface {
	TelemetryMetrics
	// OnHeartbeat registers a function to be called at each time the telemetry
	// client flushes metrics. This is useful for emitting heartbeat metrics.
	OnHeartbeat(ticket func(TelemetryMetrics))
}

TelemetryMetricsClient is the interface used to manage instrumentation telemetry metrics data.

IMPORTANT: If you are not sure what this is for, you should probably be using StatsdClient instead.

type TelemetryNamespace 

type TelemetryNamespace = telemetry.Namespace

type TelemetryOrigin added in v2.4.0 

type TelemetryOrigin = telemetry.Origin

Source Files

View all Source files

Directories

Path Synopsis
appsec
dyngo
Package dyngo is the Go implementation of Datadog's Instrumentation Gateway which provides an event-based instrumentation API based on a stack representation of instrumented functions along with nested event listeners.
 Package dyngo is the Go implementation of Datadog's Instrumentation Gateway which provides an event-based instrumentation API based on a stack representation of instrumented functions along with nested event listeners.
emitter
Package emitter provides functions and types used to instrument go libraries to integrate them with Datadog AppSec features.
 Package emitter provides functions and types used to instrument go libraries to integrate them with Datadog AppSec features.
emitter/graphqlsec
Package graphqlsec is the GraphQL instrumentation API and contract for AppSec defining an abstract run-time representation of AppSec middleware.
 Package graphqlsec is the GraphQL instrumentation API and contract for AppSec defining an abstract run-time representation of AppSec middleware.
emitter/grpcsec
Package grpcsec is the gRPC instrumentation API and contract for AppSec defining an abstract run-time representation of gRPC handlers.
 Package grpcsec is the gRPC instrumentation API and contract for AppSec defining an abstract run-time representation of gRPC handlers.
emitter/httpsec
Package httpsec defines is the HTTP instrumentation API and contract for AppSec.
 Package httpsec defines is the HTTP instrumentation API and contract for AppSec.
emitter/ossec
emitter/sqlsec
emitter/waf/actions
emitter/waf/addresses
httpsec
proxy
trace
Package httpmem provides an in-memory HTTP server and client, for testing
 Package httpmem provides an in-memory HTTP server and client, for testing
Package httptrace provides functionalities to trace HTTP requests that are commonly required and used across contrib/** integrations.
 Package httptrace provides functionalities to trace HTTP requests that are commonly required and used across contrib/** integrations.
internal
namingschema
net
http/pattern
Deprecated: this package was not meant to be exported.
 Deprecated: this package was not meant to be exported.
sql

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.