telemetry

package
v2.0.0-beta.5 Latest Latest
Warning

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

 Go to latest Published: Nov 4, 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 

func Check(t *testing.T, 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 

func Disabled() bool

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

func LoadIntegration 

func LoadIntegration(name string)

LoadIntegration notifies telemetry that an integration is being used.

func MockGlobalClient 

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 

func SetAgentlessEndpoint(endpoint string) string

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

func Time 

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 

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 

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 

func BoolConfig(key string, val bool) Configuration

BoolConfig returns a Configuration struct with a bool value

func FloatConfig 

func FloatConfig(key string, val float64) Configuration

FloatConfig returns a Configuration struct with a float value

func IntConfig 

func IntConfig(key string, val int) Configuration

IntConfig returns a Configuration struct with a int value

func Sanitize 

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 

func StringConfig(key string, val string) Configuration

StringConfig returns a Configuration struct with a string value

type ConfigurationChange 

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 

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 

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

DistributionMetrics corresponds to the "distributions" request type

type DistributionSeries 

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 

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

Error stores error information about various tracer events

type Host 

type Host struct {
	Hostname  string `json:"hostname"`
	OS        string `json:"os"`
	OSVersion string `json:"os_version,omitempty"`
	// TODO: Do we care about the kernel stuff? internal/osinfo gets most of
	// this information in OSName/OSVersion
	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 

func Integrations() []Integration

Integrations returns which integrations are tracked by telemetry.

type IntegrationsChange 

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

IntegrationsChange corresponds to the app-integrations-change requesty type

type MetricKind 

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 

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"
)

type Option 

type Option func(*client)

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

func WithAPIKey 

func WithAPIKey(v string) Option

WithAPIKey sets the DD API KEY for the telemetry client

func WithEnv 

func WithEnv(env string) Option

WithEnv sets the app specific environment for the telemetry client

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient specifies the http client for the telemetry client

func WithNamespace 

func WithNamespace(name Namespace) Option

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

func WithService 

func WithService(service string) Option

WithService sets the app specific service for the telemetry client

func WithURL 

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 

func WithVersion(version string) Option

WithVersion sets the app specific version for the telemetry client

type Origin 

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

func (Origin) MarshalJSON 

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

func (Origin) String 

func (o Origin) String() string

type ProductDetails 

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 

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

Products specifies information about available products.

type ProductsPayload 

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

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

type RemoteConfig 

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.