telemetry

package
v1.71.0-rc.1 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2024 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling.

Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling.

Package telemetry implements a client for sending telemetry information to Datadog regarding usage of an APM library such as tracing or profiling.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Check added in v1.50.0 

func Check(t Errorfer, configuration []Configuration, key string, expected interface{})

Check is a testing utility to assert that a target key in config contains the expected value

func Disabled added in v1.49.0 

func Disabled() bool

Disabled returns whether instrumentation telemetry is disabled according to the DD_INSTRUMENTATION_TELEMETRY_ENABLED env var

func LoadIntegration added in v1.50.0 

func LoadIntegration(name string)

LoadIntegration notifies telemetry that an integration is being used.

func MockGlobalClient added in v1.50.0 

func MockGlobalClient(client Client) func()

MockGlobalClient replaces the global telemetry client with a custom implementation of TelemetryClient. It returns a function that can be deferred to reset the global telemetry client to its previous value.

func SetAgentlessEndpoint added in v1.49.0 

func SetAgentlessEndpoint(endpoint string) string

SetAgentlessEndpoint is used for testing purposes to replace the real agentless endpoint with a custom one

func Time added in v1.51.0 

func Time(namespace Namespace, name string, tags []string, common bool) (finish func())

Time is used to track a distribution metric that measures the time (ms) of some portion of code. It returns a function that should be called when the desired code finishes executing. For example, by adding: defer Time(namespace, "init_time", nil, true)() at the beginning of the tracer Start function, the tracer start time is measured and stored as a metric to be flushed by the global telemetry client.

Types

type AdditionalPayload added in v1.49.0 

type AdditionalPayload struct {
	Name  string      `json:"name"`
	Value interface{} `json:"value"`
}

AdditionalPayload can be used to add extra information to the app-started event

type AppStarted 

type AppStarted struct {
	Configuration     []Configuration     `json:"configuration,omitempty"`
	Products          Products            `json:"products,omitempty"`
	AdditionalPayload []AdditionalPayload `json:"additional_payload,omitempty"`
	Error             Error               `json:"error,omitempty"`
	RemoteConfig      *RemoteConfig       `json:"remote_config,omitempty"`
}

AppStarted corresponds to the "app-started" request type

type Application 

type Application struct {
	ServiceName     string `json:"service_name"`
	Env             string `json:"env"`
	ServiceVersion  string `json:"service_version"`
	TracerVersion   string `json:"tracer_version"`
	LanguageName    string `json:"language_name"`
	LanguageVersion string `json:"language_version"`
	RuntimeName     string `json:"runtime_name"`
	RuntimeVersion  string `json:"runtime_version"`
	RuntimePatches  string `json:"runtime_patches,omitempty"`
}

Application is identifying information about the app itself

type Body added in v1.49.0 

type Body struct {
	APIVersion  string      `json:"api_version"`
	RequestType RequestType `json:"request_type"`
	TracerTime  int64       `json:"tracer_time"`
	RuntimeID   string      `json:"runtime_id"`
	SeqID       int64       `json:"seq_id"`
	Debug       bool        `json:"debug"`
	Payload     interface{} `json:"payload"`
	Application Application `json:"application"`
	Host        Host        `json:"host"`
}

Body is the common high-level structure encapsulating a telemetry request body

type Client 

type Client interface {
	RegisterAppConfig(name string, val interface{}, origin Origin)
	ProductChange(namespace Namespace, enabled bool, configuration []Configuration)
	ConfigChange(configuration []Configuration)
	Record(namespace Namespace, metric MetricKind, name string, value float64, tags []string, common bool)
	Count(namespace Namespace, name string, value float64, tags []string, common bool)
	ApplyOps(opts ...Option)
	Stop()
}

Client buffers and sends telemetry messages to Datadog (possibly through an agent). 

var (
	// GlobalClient acts as a global telemetry client that the
	// tracer, profiler, and appsec products will use
	GlobalClient Client

	// LogPrefix specifies the prefix for all telemetry logging
	LogPrefix = "Instrumentation telemetry: "
)

type Configuration 

type Configuration struct {
	Name  string      `json:"name"`
	Value interface{} `json:"value"`
	// origin is the source of the config. It is one of {default, env_var, code, dd_config, remote_config}.
	Origin      Origin `json:"origin"`
	Error       Error  `json:"error"`
	IsOverriden bool   `json:"is_overridden"`
}

Configuration is a library-specific configuration value that should be initialized through StringConfig, IntConfig, FloatConfig, or BoolConfig

func BoolConfig added in v1.49.0 

func BoolConfig(key string, val bool) Configuration

BoolConfig returns a Configuration struct with a bool value

func FloatConfig added in v1.49.0 

func FloatConfig(key string, val float64) Configuration

FloatConfig returns a Configuration struct with a float value

func IntConfig added in v1.49.0 

func IntConfig(key string, val int) Configuration

IntConfig returns a Configuration struct with a int value

func Sanitize added in v1.59.0 

func Sanitize(c Configuration) Configuration

Sanitize ensures the configuration values are valid and compatible. It removes NaN and Inf values and converts string slices and maps into comma-separated strings.

func StringConfig added in v1.49.0 

func StringConfig(key string, val string) Configuration

StringConfig returns a Configuration struct with a string value

type ConfigurationChange added in v1.49.0 

type ConfigurationChange struct {
	Configuration []Configuration `json:"configuration"`
	RemoteConfig  *RemoteConfig   `json:"remote_config,omitempty"`
}

ConfigurationChange corresponds to the `AppClientConfigurationChange` event that contains information about configuration changes since the app-started event

type Dependencies added in v1.49.0 

type Dependencies struct {
	Dependencies []Dependency `json:"dependencies"`
}

Dependencies stores a list of dependencies

type Dependency 

type Dependency struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

Dependency is a Go module on which the application depends. This information can be accesed at run-time through the runtime/debug.ReadBuildInfo API.

type DistributionMetrics added in v1.51.0 

type DistributionMetrics struct {
	Namespace Namespace            `json:"namespace"`
	Series    []DistributionSeries `json:"series"`
}

DistributionMetrics corresponds to the "distributions" request type

type DistributionSeries added in v1.51.0 

type DistributionSeries struct {
	Metric string    `json:"metric"`
	Points []float64 `json:"points"`
	Tags   []string  `json:"tags"`
	// Common distinguishes metrics which are cross-language vs.
	// language-specific.
	//
	// NOTE: If this field isn't present in the request, the API assumes
	// the metric is common. So we can't "omitempty" even though the
	// field is technically optional.
	Common bool `json:"common"`
}

DistributionSeries is a sequence of observations for a distribution metric. Unlike `Series`, DistributionSeries does not store timestamps in `Points`

type Error added in v1.49.0 

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

Error stores error information about various tracer events

type Errorfer 

type Errorfer interface {
	Errorf(format string, args ...any)
}

Errorfer is an interface that allows to call the `Errorf` method. This is the same interface as `testing.T` because the goal of this interface is to remove the need to import `testing` in this package that is actually imported by users.

type Host 

type Host struct {
	Hostname      string `json:"hostname"`
	OS            string `json:"os"`
	OSVersion     string `json:"os_version,omitempty"`
	Architecture  string `json:"architecture"`
	KernelName    string `json:"kernel_name"`
	KernelRelease string `json:"kernel_release"`
	KernelVersion string `json:"kernel_version"`
}

Host is identifying information about the host on which the app is running

type Integration 

type Integration struct {
	Name        string `json:"name"`
	Enabled     bool   `json:"enabled"`
	Version     string `json:"version,omitempty"`
	AutoEnabled bool   `json:"auto_enabled,omitempty"`
	Compatible  bool   `json:"compatible,omitempty"`
	Error       string `json:"error,omitempty"`
}

Integration is an integration that is configured to be traced automatically.

func Integrations added in v1.50.0 

func Integrations() []Integration

Integrations returns which integrations are tracked by telemetry.

type IntegrationsChange added in v1.50.0 

type IntegrationsChange struct {
	Integrations []Integration `json:"integrations"`
}

IntegrationsChange corresponds to the app-integrations-change requesty type

type MetricKind added in v1.51.0 

type MetricKind string

MetricKind specifies the type of metric being reported. Metric types mirror Datadog metric types - for a more detailed description of metric types, see: https://docs.datadoghq.com/metrics/types/?tab=count#metric-types 

var (
	// MetricKindGauge represents a gauge type metric
	MetricKindGauge MetricKind = "gauge"
	// MetricKindCount represents a count type metric
	MetricKindCount MetricKind = "count"
	// MetricKindDist represents a distribution type metric
	MetricKindDist MetricKind = "distribution"
)

type Metrics 

type Metrics struct {
	Namespace Namespace `json:"namespace"`
	Series    []Series  `json:"series"`
}

Metrics corresponds to the "generate-metrics" request type

type Namespace added in v1.41.0 

type Namespace string

Namespace describes an APM product to distinguish telemetry coming from different products used by the same application 

const (
	// NamespaceGeneral is for general use
	NamespaceGeneral Namespace = "general"
	// NamespaceTracers is for distributed tracing
	NamespaceTracers Namespace = "tracers"
	// NamespaceProfilers is for continuous profiling
	NamespaceProfilers Namespace = "profilers"
	// NamespaceAppSec is for application security management
	NamespaceAppSec Namespace = "appsec"
	// NamespaceCiVisibility is for CI Visibility
	NamespaceCiVisibility Namespace = "civisibility"
)

type Option added in v1.49.0 

type Option func(*client)

An Option is used to configure the telemetry client's settings

func SyncFlushOnStop added in v1.70.0 

func SyncFlushOnStop() Option

SyncFlushOnStop forces a sync flush on client stop

func WithAPIKey added in v1.49.0 

func WithAPIKey(v string) Option

WithAPIKey sets the DD API KEY for the telemetry client

func WithEnv added in v1.49.0 

func WithEnv(env string) Option

WithEnv sets the app specific environment for the telemetry client

func WithHTTPClient added in v1.49.0 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient specifies the http client for the telemetry client

func WithNamespace added in v1.49.0 

func WithNamespace(name Namespace) Option

WithNamespace sets name as the telemetry client's namespace (tracer, profiler, appsec)

func WithService added in v1.49.0 

func WithService(service string) Option

WithService sets the app specific service for the telemetry client

func WithURL added in v1.49.0 

func WithURL(agentless bool, agentURL string) Option

WithURL sets the URL for where telemetry information is flushed to. For the URL, uploading through agent goes through 

${AGENT_URL}/telemetry/proxy/api/v2/apmtelemetry

for agentless: 

https://instrumentation-telemetry-intake.datadoghq.com/api/v2/apmtelemetry

with an API key

func WithVersion added in v1.49.0 

func WithVersion(version string) Option

WithVersion sets the app specific version for the telemetry client

type Origin added in v1.65.0 

type Origin int
const (
	OriginDefault Origin = iota
	OriginCode
	OriginDDConfig
	OriginEnvVar
	OriginRemoteConfig
)

func (Origin) MarshalJSON added in v1.65.0 

func (o Origin) MarshalJSON() ([]byte, error)

func (Origin) String added in v1.65.0 

func (o Origin) String() string

type ProductDetails added in v1.39.0 

type ProductDetails struct {
	Enabled bool   `json:"enabled"`
	Version string `json:"version,omitempty"`
	Error   Error  `json:"error,omitempty"`
}

ProductDetails specifies details about a product.

type Products added in v1.39.0 

type Products struct {
	AppSec   ProductDetails `json:"appsec,omitempty"`
	Profiler ProductDetails `json:"profiler,omitempty"`
}

Products specifies information about available products.

type ProductsPayload added in v1.60.0 

type ProductsPayload struct {
	Products Products `json:"products"`
}

ProductsPayload is the top-level key for the app-product-change payload.

type RemoteConfig added in v1.49.0 

type RemoteConfig struct {
	UserEnabled     string `json:"user_enabled"`     // whether the library has made a request to fetch remote-config
	ConfigsRecieved bool   `json:"configs_received"` // whether the library receives a valid config response
	RcID            string `json:"rc_id,omitempty"`
	RcRevision      string `json:"rc_revision,omitempty"`
	RcVersion       string `json:"rc_version,omitempty"`
	Error           Error  `json:"error,omitempty"`
}

RemoteConfig contains information about remote-config

type Request 

type Request struct {
	Body       *Body
	Header     *http.Header
	HTTPClient *http.Client
	URL        string
}

Request captures all necessary information for a telemetry event submission

type RequestType 

type RequestType string

RequestType determines how the Payload of a request should be handled 

const (
	// RequestTypeAppStarted is the first message sent by the telemetry
	// client, containing the configuration loaded at startup
	RequestTypeAppStarted RequestType = "app-started"
	// RequestTypeAppHeartbeat is sent periodically by the client to indicate
	// that the app is still running
	RequestTypeAppHeartbeat RequestType = "app-heartbeat"
	// RequestTypeGenerateMetrics contains count, gauge, or rate metrics accumulated by the
	// client, and is sent periodically along with the heartbeat
	RequestTypeGenerateMetrics RequestType = "generate-metrics"
	// RequestTypeDistributions is to send distribution type metrics accumulated by the
	// client, and is sent periodically along with the heartbeat
	RequestTypeDistributions RequestType = "distributions"
	// RequestTypeAppClosing is sent when the telemetry client is stopped
	RequestTypeAppClosing RequestType = "app-closing"
	// RequestTypeDependenciesLoaded is sent if DD_TELEMETRY_DEPENDENCY_COLLECTION_ENABLED
	// is enabled. Sent when Start is called for the telemetry client.
	RequestTypeDependenciesLoaded RequestType = "app-dependencies-loaded"
	// RequestTypeAppClientConfigurationChange is sent if there are changes
	// to the client library configuration
	RequestTypeAppClientConfigurationChange RequestType = "app-client-configuration-change"
	// RequestTypeAppProductChange is sent when products are enabled/disabled
	RequestTypeAppProductChange RequestType = "app-product-change"
	// RequestTypeAppIntegrationsChange is sent when the telemetry client starts
	// with info on which integrations are used.
	RequestTypeAppIntegrationsChange RequestType = "app-integrations-change"
)

type Series 

type Series struct {
	Metric string       `json:"metric"`
	Points [][2]float64 `json:"points"`
	// Interval is required for gauge and rate metrics
	Interval int      `json:"interval,omitempty"`
	Type     string   `json:"type,omitempty"`
	Tags     []string `json:"tags"`
	// Common distinguishes metrics which are cross-language vs.
	// language-specific.
	//
	// NOTE: If this field isn't present in the request, the API assumes
	// the metric is common. So we can't "omitempty" even though the
	// field is technically optional.
	Common    bool   `json:"common"`
	Namespace string `json:"namespace"`
}

Series is a sequence of observations for a single named metric. The `Points` field will store a timestamp and value.

Source Files

View all Source files

Directories

Path Synopsis
Package telemetrytest provides a mock implementation of the telemetry client for testing purposes
 Package telemetrytest provides a mock implementation of the telemetry client for testing purposes

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.