telemetry

package
v1.49.1-rc.1 Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2023 License: Apache-2.0, BSD-3-Clause, Apache-2.0 Imports: 20 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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

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

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"`
}

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 struct {
	// URL for the Datadog agent or Datadog telemetry endpoint
	URL string
	// APIKey should be supplied if the endpoint is not a Datadog agent,
	// i.e. you are sending telemetry directly to Datadog
	APIKey string

	// e.g. "tracers", "profilers", "appsec"
	Namespace Namespace

	// App-specific information
	Service string
	Env     string
	Version string

	// Client will be used for telemetry uploads. This http.Client, if
	// provided, should be the same as would be used for any other
	// interaction with the Datadog agent, e.g. if the agent is accessed
	// over UDS, or if the user provides their own http.Client to the
	// profiler/tracer to access the agent over a proxy.
	//
	// If Client is nil, an http.Client with the same Transport settings as
	// http.DefaultTransport and a 5 second timeout will be used.
	Client *http.Client
	// contains filtered or unexported fields
}

Client buffers and sends telemetry messages to Datadog (possibly through an agent). Client.Start should be called before any other methods.

Client is safe to use from multiple goroutines concurrently. The client will send all telemetry requests in the background, in order to avoid blocking the caller since telemetry should not disrupt an application. Metrics are aggregated by the Client. 

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

func (*Client) ApplyOps added in v1.49.0 

func (c *Client) ApplyOps(opts ...Option)

ApplyOps sets various fields of the client

func (*Client) Count 

func (c *Client) Count(namespace Namespace, name string, value float64, tags []string, common bool)

Count adds the value to a count with the given name and tags. If the metric is not language-specific, common should be set to true

func (*Client) Gauge 

func (c *Client) Gauge(namespace Namespace, name string, value float64, tags []string, common bool)

Gauge sets the value for a gauge with the given name and tags. If the metric is not language-specific, common should be set to true

func (*Client) ProductChange added in v1.49.0 

func (c *Client) ProductChange(namespace Namespace, enabled bool, configuration []Configuration)

ProductChange enqueues an app-product-change event that signals a product has been turned on/off. The caller can also specify additional configuration changes (e.g. profiler config info), which will be sent via the app-client-configuration-change event. The enabled field is meant to specify when a product has be enabled/disabled during runtime. For example, an app-product-change message with enabled=true can be sent when the profiler starts, and another app-product-change message with enabled=false can be sent when the profiler stops. Product enablement messages do not apply to the tracer, since the tracer is not considered a product by the instrumentation telemetry API.

func (*Client) Start 

func (c *Client) Start(configuration []Configuration)

Start registers that the app has begun running with the app-started event Start also configures the telemetry client based on the following telemetry environment variables: DD_INSTRUMENTATION_TELEMETRY_ENABLED, DD_TELEMETRY_HEARTBEAT_INTERVAL, DD_INSTRUMENTATION_TELEMETRY_DEBUG, and DD_TELEMETRY_DEPENDENCY_COLLECTION_ENABLED. TODO: implement passing in error information about tracer start

func (*Client) Stop 

func (c *Client) Stop()

Stop notifies the telemetry endpoint that the app is closing. All outstanding messages will also be sent. No further messages will be sent until the client is started again

type Configuration 

type Configuration struct {
	Name  string      `json:"name"`
	Value interface{} `json:"value"`
	// origin is the source of the config. It is one of {env_var, code, dd_config, remote_config}
	Origin      string `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 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:"conf_key_values"`
	RemoteConfig  RemoteConfig    `json:"remote_config"`
}

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 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 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 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 (
	// NamespaceTracers is for distributed tracing
	NamespaceTracers Namespace = "tracers"
	// NamespaceProfilers is for continuous profiling
	NamespaceProfilers Namespace = "profilers"
	// NamespaceASM is for application security monitoring
	NamespaceASM Namespace = "appsec" // This was defined before the appsec -> ASM change
)

type Option added in v1.49.0 

type Option func(*Client)

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

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 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 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
	Error           Error  `json:"error"`
}

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, and integrations and
	// dependencies 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 all metrics accumulated by the
	// client, and is sent periodically along with the heartbeat
	RequestTypeGenerateMetrics RequestType = "generate-metrics"
	// 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"
)

type Series 

type Series struct {
	Metric string       `json:"metric"`
	Points [][2]float64 `json:"points"`
	Type   string       `json:"type"`
	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
	// assumed the metric is common. So we can't "omitempty" even though the
	// field is technically optional.
	Common bool `json:"common"`
}

Series is a sequence of observations for a single named metric

Source Files

View all Source files

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.