instrumentation

package
v2.13.0-dev Latest Latest
Warning

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

 Go to latest Published: Oct 13, 2026 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 20 Imported by: 76

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 added in v2.11.0 

func Register(pkg Package, info PackageInfo)

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

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 added in v2.11.0 

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 added in v2.11.0 

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) OTelSemanticsEnabled added in v2.12.0 

func (i *Instrumentation) OTelSemanticsEnabled() bool

OTelSemanticsEnabled `true` changes observability data to be emitted according to OpenTelemetry semantic conventions. Datadog conventions are used when `false`.

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. It backs the legacy DD_TRACE_SPAN_ATTRIBUTE_SCHEMA naming-schema feature; new integrations should not call it and should hardcode operation names as string literals instead. See https://github.com/DataDog/dd-trace-go/blob/main/contrib/INTEGRATIONS.md.

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 added in v2.11.0 

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. When the package has no naming entry, which is the recommended setup for new integrations, this returns the global DD_SERVICE. The per-component naming logic backs the legacy DD_TRACE_SPAN_ATTRIBUTE_SCHEMA feature.

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 added in v2.11.0 

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 added in v2.11.0 

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 added in v2.11.0 

func (i *Instrumentation) TelemetryProductStarted(ns TelemetryNamespace)

TelemetryProductStarted declares a telemetry product as having started.

func (*Instrumentation) TelemetryProductStopped added in v2.11.0 

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"
	PackageCloudEventsSDKGoV2   Package = "cloudevents/sdk-go.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"
	PackageOpenSearchProjectOpenSearchGoV4 Package = "opensearch-project/opensearch-go.v4"
	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 added in v2.11.0 

type StackFrame = stacktrace.StackFrame

StackFrame is a single frame of a StackTrace.

type StackTrace added in v2.11.0 

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 added in v2.11.0 

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 added in v2.11.0 

type StackTraceOption = stacktrace.Option

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

func WithStackTraceDepth added in v2.11.0 

func WithStackTraceDepth(depth int) StackTraceOption

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

func WithStackTraceID added in v2.11.0 

func WithStackTraceID(id string) StackTraceOption

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

func WithStackTraceMessage added in v2.11.0 

func WithStackTraceMessage(message string) StackTraceOption

WithStackTraceMessage sets the event message.

func WithStackTraceSkip added in v2.11.0 

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 added in v2.11.0 

func WithStackTraceType(eventType string) StackTraceOption

WithStackTraceType sets the event type.

type StatsdClient 

type StatsdClient = internal.StatsdClient

type TelemetryMetric added in v2.11.0 

type TelemetryMetric = telemetry.MetricHandle

TelemetryMetric is a handle to a telemetry metric.

type TelemetryMetrics added in v2.11.0 

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 added in v2.11.0 

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 added in v2.11.0 

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
testtracer
Package testtracer provides a compatibility wrapper over the inspectable tracer with the API of the testtracer package that existed before the inspectable tracer.
 Package testtracer provides a compatibility wrapper over the inspectable tracer with the API of the testtracer package that existed before the inspectable tracer.

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.