telemetry

Documentation

Overview

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

Index

• type AppStarted
• type Application
• type Client
  • func (c *Client) Count(name string, value float64, tags []string, common bool)
  • func (c *Client) Gauge(name string, value float64, tags []string, common bool)
  • func (c *Client) Start(integrations []Integration, configuration []Configuration)
  • func (c *Client) Stop()
• type Configuration
• type Dependency
• type Host
• type Integration
• type Metrics
• type ProductDetails
• type Products
• type Request
• type RequestType
• type Series

Types

type AppStarted

type AppStarted struct {
	Integrations  []Integration   `json:"integrations"`
	Dependencies  []Dependency    `json:"dependencies"`
	Configuration []Configuration `json:"configuration"`
}

AppStarted corresponds to the "app-started" request type

type Application

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

Application is identifying information about the app itself

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
	// How often to send batched requests. Defaults to 60s
	SubmissionInterval time.Duration

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

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

	// Determines whether telemetry should actually run.
	// Defaults to false, but will be overridden by the environment variable
	// POBP_INSTRUMENTATION_TELEMETRY_ENABLED is set to 0 or false
	Disabled bool

	// Optional destination to record submission-related logging events
	Logger interface {
		Printf(msg string, args ...interface{})
	}
	// 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.

func (*Client) Count

func (c *Client) Count(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(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) Start

func (c *Client) Start(integrations []Integration, configuration []Configuration)

Start registers that the app has begun running with the given integrations and configuration.

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 should have a type that can be marshaled to JSON
	Value interface{} `json:"value"`
}

Configuration is a library-specific configuration value

type Dependency

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

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

type Host

type Host struct {
	ContainerID string `json:"container_id,omitempty"`
	Hostname    string `json:"hostname,omitempty"`
	OS          string `json:"os,omitempty"`
	OSVersion   string `json:"os_version,omitempty"`
	// TODO: Do we care about the kernel stuff? internal/osinfo gets most of
	// this information in OSName/OSVersion
	KernelName    string `json:"kernel_name,omitempty"`
	KernelRelease string `json:"kernel_release,omitempty"`
	KernelVersion string `json:"kernel_version,omitempty"`
}

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 available within the app and applicable to be traced

type Metrics

type Metrics struct {
	Namespace   string   `json:"namespace"`
	LibLanguage string   `json:"lib_language"`
	LibVersion  string   `json:"lib_version"`
	Series      []Series `json:"series"`
}

Metrics corresponds to the "generate-metrics" request type

type ProductDetails

type ProductDetails struct {
	Version string `json:"version"`
}

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 Request

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

Request is the common high-level structure encapsulating a telemetry request

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

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