appinsights

package
v0.4.4 Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2021 License: MIT Imports: 23 Imported by: 68

Documentation

Overview

Package appinsights provides an interface to submit telemetry to Application Insights. See more at https://azure.microsoft.com/en-us/services/application-insights/

Index

Constants

View Source 
const (
	Measurement contracts.DataPointType = contracts.Measurement
	Aggregation contracts.DataPointType = contracts.Aggregation
)

Type of the metric data measurement.

View Source 
const (
	Verbose     contracts.SeverityLevel = contracts.Verbose
	Information contracts.SeverityLevel = contracts.Information
	Warning     contracts.SeverityLevel = contracts.Warning
	Error       contracts.SeverityLevel = contracts.Error
	Critical    contracts.SeverityLevel = contracts.Critical
)

Defines the level of severity for the event.

View Source 
const (
	Version = "0.4.4"
)

Variables

This section is empty.

Functions

func GetCallstack added in v0.4.1 

func GetCallstack(skip int) []*contracts.StackFrame

Generates a callstack suitable for inclusion in Application Insights exception telemetry for the current goroutine, skipping a number of frames specified by skip.

func TrackPanic added in v0.4.1 

func TrackPanic(client TelemetryClient, rethrow bool)

Recovers from any active panics and tracks them to the specified TelemetryClient. If rethrow is set to true, then this will panic. Should be invoked via defer in functions to monitor.

Types

type AggregateMetricTelemetry added in v0.4.1 

type AggregateMetricTelemetry struct {
	BaseTelemetry
	BaseTelemetryNoMeasurements

	// Metric name
	Name string

	// Sum of individual measurements
	Value float64

	// Minimum value of the aggregated metric
	Min float64

	// Maximum value of the aggregated metric
	Max float64

	// Count of measurements in the sample
	Count int

	// Standard deviation of the aggregated metric
	StdDev float64

	// Variance of the aggregated metric.  As an invariant,
	// either this or the StdDev should be zero at any given time.
	// If both are non-zero then StdDev takes precedence.
	Variance float64
}

Aggregated metric telemetry items represent an aggregation of data points over time. These values can be calculated by the caller or with the AddData function.

func NewAggregateMetricTelemetry added in v0.4.1 

func NewAggregateMetricTelemetry(name string) *AggregateMetricTelemetry

Creates a new aggregated metric telemetry item with the specified name. Values should be set on the object returned before submission.

func (*AggregateMetricTelemetry) AddData added in v0.4.1 

func (agg *AggregateMetricTelemetry) AddData(values []float64)

Adds data points to the aggregate totals included in this telemetry item. This can be used for all the data at once or incrementally. Calculates Min, Max, Sum, Count, and StdDev (by way of Variance).

func (*AggregateMetricTelemetry) AddSampledData added in v0.4.1 

func (agg *AggregateMetricTelemetry) AddSampledData(values []float64)

Adds sampled data points to the aggregate totals included in this telemetry item. This can be used for all the data at once or incrementally. Differs from AddData in how it calculates standard deviation, and should not be used interchangeably with AddData.

func (*AggregateMetricTelemetry) TelemetryData added in v0.4.1 

func (agg *AggregateMetricTelemetry) TelemetryData() TelemetryData

type AvailabilityTelemetry added in v0.4.1 

type AvailabilityTelemetry struct {
	BaseTelemetry
	BaseTelemetryMeasurements

	// Identifier of a test run. Used to correlate steps of test run and
	// telemetry generated by the service.
	Id string

	// Name of the test that this result represents.
	Name string

	// Duration of the test run.
	Duration time.Duration

	// Success flag.
	Success bool

	// Name of the location where the test was run.
	RunLocation string

	// Diagnostic message for the result.
	Message string
}

Avaibility telemetry items represent the result of executing an availability test.

func NewAvailabilityTelemetry added in v0.4.1 

func NewAvailabilityTelemetry(name string, duration time.Duration, success bool) *AvailabilityTelemetry

Creates a new availability telemetry item with the specified test name, duration and success code.

func (*AvailabilityTelemetry) MarkTime added in v0.4.1 

func (telem *AvailabilityTelemetry) MarkTime(startTime, endTime time.Time)

Sets the timestamp and duration of this telemetry item based on the provided start and end times.

func (*AvailabilityTelemetry) TelemetryData added in v0.4.1 

func (telem *AvailabilityTelemetry) TelemetryData() TelemetryData

type BaseTelemetry 

type BaseTelemetry struct {
	// The time this when this item was measured
	Timestamp time.Time

	// Custom properties
	Properties map[string]string

	// Telemetry Context containing extra, optional tags.
	Tags contracts.ContextTags
}

BaseTelemetry is the common base struct for telemetry items.

func (*BaseTelemetry) ContextTags added in v0.4.1 

func (item *BaseTelemetry) ContextTags() map[string]string

Gets context data containing extra, optional tags. Overrides values found on client TelemetryContext.

func (*BaseTelemetry) GetProperties added in v0.4.1 

func (item *BaseTelemetry) GetProperties() map[string]string

Gets custom properties to submit with the telemetry item.

func (*BaseTelemetry) SetTime added in v0.4.1 

func (item *BaseTelemetry) SetTime(t time.Time)

SetTime sets the timestamp to the specified time.

func (*BaseTelemetry) Time added in v0.4.1 

func (item *BaseTelemetry) Time() time.Time

Time returns the timestamp when this was measured.

type BaseTelemetryMeasurements added in v0.4.1 

type BaseTelemetryMeasurements struct {
	// Custom measurements
	Measurements map[string]float64
}

BaseTelemetryMeasurements provides the Measurements field for telemetry items that support it.

func (*BaseTelemetryMeasurements) GetMeasurements added in v0.4.1 

func (item *BaseTelemetryMeasurements) GetMeasurements() map[string]float64

Gets custom measurements to submit with the telemetry item.

type BaseTelemetryNoMeasurements added in v0.4.1 

type BaseTelemetryNoMeasurements struct {
}

BaseTelemetryNoMeasurements provides no Measurements field for telemetry items that omit it.

func (*BaseTelemetryNoMeasurements) GetMeasurements added in v0.4.1 

func (item *BaseTelemetryNoMeasurements) GetMeasurements() map[string]float64

GetMeasurements returns nil for telemetry items that do not support measurements.

type DiagnosticsMessageHandler added in v0.4.1 

type DiagnosticsMessageHandler func(string) error

Handler function for receiving diagnostics messages. If this returns an error, then the listener will be removed.

type DiagnosticsMessageListener 

type DiagnosticsMessageListener interface {
	// Stop receiving diagnostics messages from this listener.
	Remove()
}

Listener type returned by NewDiagnosticsMessageListener.

func NewDiagnosticsMessageListener 

func NewDiagnosticsMessageListener(handler DiagnosticsMessageHandler) DiagnosticsMessageListener

Subscribes the specified handler to diagnostics messages from the SDK. The returned interface can be used to unsubscribe.

type EventTelemetry 

type EventTelemetry struct {
	BaseTelemetry
	BaseTelemetryMeasurements

	// Event name
	Name string
}

Event telemetry items represent structured event records.

func NewEventTelemetry 

func NewEventTelemetry(name string) *EventTelemetry

Creates an event telemetry item with the specified name.

func (*EventTelemetry) TelemetryData added in v0.4.1 

func (event *EventTelemetry) TelemetryData() TelemetryData

type ExceptionTelemetry added in v0.4.1 

type ExceptionTelemetry struct {
	BaseTelemetry
	BaseTelemetryMeasurements

	// Panic message: string, error, or Stringer
	Error interface{}

	// List of stack frames. Use GetCallstack to generate this data.
	Frames []*contracts.StackFrame

	// Severity level.
	SeverityLevel contracts.SeverityLevel
}

Exception telemetry items represent a handled or unhandled exceptions that occurred during execution of the monitored application.

func NewExceptionTelemetry added in v0.4.1 

func NewExceptionTelemetry(err interface{}) *ExceptionTelemetry

Creates a new exception telemetry item with the specified error and the current callstack. This should be used directly from a function that handles a recover(), or to report an unexpected error return value from a function.

func (*ExceptionTelemetry) TelemetryData added in v0.4.1 

func (telem *ExceptionTelemetry) TelemetryData() TelemetryData

type InMemoryChannel 

type InMemoryChannel struct {
	// contains filtered or unexported fields
}

A telemetry channel that stores events exclusively in memory. Presently the only telemetry channel implementation available.

func NewInMemoryChannel 

func NewInMemoryChannel(config *TelemetryConfiguration) *InMemoryChannel

Creates an InMemoryChannel instance and starts a background submission goroutine.

func (*InMemoryChannel) Close 

func (channel *InMemoryChannel) Close(timeout ...time.Duration) <-chan struct{}

Flushes and tears down the submission goroutine and closes internal channels. Returns a channel that is closed when all pending telemetry items have been submitted and it is safe to shut down without losing telemetry.

If retryTimeout is specified and non-zero, then failed submissions will be retried until one succeeds or the timeout expires, whichever occurs first. A retryTimeout of zero indicates that failed submissions will be retried as usual. An omitted retryTimeout indicates that submissions should not be retried if they fail.

Note that the returned channel may not be closed before retryTimeout even if it is specified. This is because retryTimeout only applies to the latest telemetry buffer. This may be typical for applications that submit a large amount of telemetry or are prone to being throttled. When exiting, you should select on the result channel and your own timer to avoid long delays.

func (*InMemoryChannel) EndpointAddress 

func (channel *InMemoryChannel) EndpointAddress() string

The address of the endpoint to which telemetry is sent

func (*InMemoryChannel) Flush 

func (channel *InMemoryChannel) Flush()

Forces the current queue to be sent

func (*InMemoryChannel) IsThrottled 

func (channel *InMemoryChannel) IsThrottled() bool

Returns true if this channel has been throttled by the data collector.

func (*InMemoryChannel) Send 

func (channel *InMemoryChannel) Send(item *contracts.Envelope)

Queues a single telemetry item

func (*InMemoryChannel) Stop 

func (channel *InMemoryChannel) Stop()

Tears down the submission goroutines, closes internal channels. Any telemetry waiting to be sent is discarded. Further calls to Send() have undefined behavior. This is a more abrupt version of Close().

type MetricTelemetry 

type MetricTelemetry struct {
	BaseTelemetry
	BaseTelemetryNoMeasurements

	// Metric name
	Name string

	// Sampled value
	Value float64
}

Metric telemetry items each represent a single data point.

func NewMetricTelemetry 

func NewMetricTelemetry(name string, value float64) *MetricTelemetry

Creates a metric telemetry sample with the specified name and value.

func (*MetricTelemetry) TelemetryData added in v0.4.1 

func (metric *MetricTelemetry) TelemetryData() TelemetryData

type PageViewTelemetry added in v0.4.1 

type PageViewTelemetry struct {
	BaseTelemetry
	BaseTelemetryMeasurements

	// Request URL with all query string parameters
	Url string

	// Request duration.
	Duration time.Duration

	// Event name.
	Name string
}

Page view telemetry items represent generic actions on a page like a button click.

func NewPageViewTelemetry added in v0.4.1 

func NewPageViewTelemetry(name, url string) *PageViewTelemetry

Creates a new page view telemetry item with the specified name and url.

func (*PageViewTelemetry) MarkTime added in v0.4.1 

func (telem *PageViewTelemetry) MarkTime(startTime, endTime time.Time)

Sets the timestamp and duration of this telemetry item based on the provided start and end times.

func (*PageViewTelemetry) TelemetryData added in v0.4.1 

func (telem *PageViewTelemetry) TelemetryData() TelemetryData

type RemoteDependencyTelemetry added in v0.4.1 

type RemoteDependencyTelemetry struct {
	BaseTelemetry
	BaseTelemetryMeasurements

	// Name of the command that initiated this dependency call. Low cardinality
	// value. Examples are stored procedure name and URL path template.
	Name string

	// Identifier of a dependency call instance. Used for correlation with the
	// request telemetry item corresponding to this dependency call.
	Id string

	// Result code of a dependency call. Examples are SQL error code and HTTP
	// status code.
	ResultCode string

	// Duration of the remote call.
	Duration time.Duration

	// Indication of successful or unsuccessful call.
	Success bool

	// Command initiated by this dependency call. Examples are SQL statement and
	// HTTP URL's with all the query parameters.
	Data string

	// Dependency type name. Very low cardinality. Examples are SQL, Azure table,
	// and HTTP.
	Type string

	// Target site of a dependency call. Examples are server name, host address.
	Target string
}

Remote dependency telemetry items represent interactions of the monitored component with a remote component/service like SQL or an HTTP endpoint.

func NewRemoteDependencyTelemetry added in v0.4.1 

func NewRemoteDependencyTelemetry(name, dependencyType, target string, success bool) *RemoteDependencyTelemetry

Builds a new Remote Dependency telemetry item, with the specified name, dependency type, target site, and success status.

func (*RemoteDependencyTelemetry) MarkTime added in v0.4.1 

func (telem *RemoteDependencyTelemetry) MarkTime(startTime, endTime time.Time)

Sets the timestamp and duration of this telemetry item based on the provided start and end times.

func (*RemoteDependencyTelemetry) TelemetryData added in v0.4.1 

func (telem *RemoteDependencyTelemetry) TelemetryData() TelemetryData

type RequestTelemetry 

type RequestTelemetry struct {
	BaseTelemetry
	BaseTelemetryMeasurements

	// Identifier of a request call instance. Used for correlation between request
	// and other telemetry items.
	Id string

	// Request name. For HTTP requests it represents the HTTP method and URL path template.
	Name string

	// URL of the request with all query string parameters.
	Url string

	// Duration to serve the request.
	Duration time.Duration

	// Results of a request execution. HTTP status code for HTTP requests.
	ResponseCode string

	// Indication of successful or unsuccessful call.
	Success bool

	// Source of the request. Examplese are the instrumentation key of the caller
	// or the ip address of the caller.
	Source string
}

Request telemetry items represents completion of an external request to the application and contains a summary of that request execution and results.

func NewRequestTelemetry 

func NewRequestTelemetry(method, uri string, duration time.Duration, responseCode string) *RequestTelemetry

Creates a new request telemetry item for HTTP requests. The success value will be computed from responseCode, and the timestamp will be set to the current time minus the duration.

func (*RequestTelemetry) MarkTime added in v0.4.1 

func (request *RequestTelemetry) MarkTime(startTime, endTime time.Time)

Sets the timestamp and duration of this telemetry item based on the provided start and end times.

func (*RequestTelemetry) TelemetryData added in v0.4.1 

func (request *RequestTelemetry) TelemetryData() TelemetryData

type Telemetry 

type Telemetry interface {
	// Gets the time when this item was measured
	Time() time.Time

	// Sets the timestamp to the specified time.
	SetTime(time.Time)

	// Gets context data containing extra, optional tags.  Overrides
	// values found on client TelemetryContext.
	ContextTags() map[string]string

	// Gets the data contract as it will be submitted to the data
	// collector.
	TelemetryData() TelemetryData

	// Gets custom properties to submit with the telemetry item.
	GetProperties() map[string]string

	// Gets custom measurements to submit with the telemetry item.
	GetMeasurements() map[string]float64
}

Common interface implemented by telemetry items that can be passed to TelemetryClient.Track

type TelemetryChannel 

type TelemetryChannel interface {
	// The address of the endpoint to which telemetry is sent
	EndpointAddress() string

	// Queues a single telemetry item
	Send(*contracts.Envelope)

	// Forces the current queue to be sent
	Flush()

	// Tears down the submission goroutines, closes internal channels.
	// Any telemetry waiting to be sent is discarded.  Further calls to
	// Send() have undefined behavior.  This is a more abrupt version of
	// Close().
	Stop()

	// Returns true if this channel has been throttled by the data
	// collector.
	IsThrottled() bool

	// Flushes and tears down the submission goroutine and closes
	// internal channels.  Returns a channel that is closed when all
	// pending telemetry items have been submitted and it is safe to
	// shut down without losing telemetry.
	//
	// If retryTimeout is specified and non-zero, then failed
	// submissions will be retried until one succeeds or the timeout
	// expires, whichever occurs first.  A retryTimeout of zero
	// indicates that failed submissions will be retried as usual.  An
	// omitted retryTimeout indicates that submissions should not be
	// retried if they fail.
	//
	// Note that the returned channel may not be closed before
	// retryTimeout even if it is specified.  This is because
	// retryTimeout only applies to the latest telemetry buffer.  This
	// may be typical for applications that submit a large amount of
	// telemetry or are prone to being throttled.  When exiting, you
	// should select on the result channel and your own timer to avoid
	// long delays.
	Close(retryTimeout ...time.Duration) <-chan struct{}
}

Implementations of TelemetryChannel are responsible for queueing and periodically submitting telemetry items.

type TelemetryClient 

type TelemetryClient interface {
	// Gets the telemetry context for this client. Values found on this
	// context will get written out to every telemetry item tracked by
	// this client.
	Context() *TelemetryContext

	// Gets the instrumentation key assigned to this telemetry client.
	InstrumentationKey() string

	// Gets the telemetry channel used to submit data to the backend.
	Channel() TelemetryChannel

	// Gets whether this client is enabled and will accept telemetry.
	IsEnabled() bool

	// Enables or disables the telemetry client. When disabled, telemetry
	// is silently swallowed by the client. Defaults to enabled.
	SetIsEnabled(enabled bool)

	// Submits the specified telemetry item.
	Track(telemetry Telemetry)

	// Log a user action with the specified name
	TrackEvent(name string)

	// Log a numeric value that is not specified with a specific event.
	// Typically used to send regular reports of performance indicators.
	TrackMetric(name string, value float64)

	// Log a trace message with the specified severity level.
	TrackTrace(name string, severity contracts.SeverityLevel)

	// Log an HTTP request with the specified method, URL, duration and
	// response code.
	TrackRequest(method, url string, duration time.Duration, responseCode string)

	// Log a dependency with the specified name, type, target, and
	// success status.
	TrackRemoteDependency(name, dependencyType, target string, success bool)

	// Log an availability test result with the specified test name,
	// duration, and success status.
	TrackAvailability(name string, duration time.Duration, success bool)

	// Log an exception with the specified error, which may be a string,
	// error or Stringer. The current callstack is collected
	// automatically.
	TrackException(err interface{})
}

Application Insights telemetry client provides interface to track telemetry items.

func NewTelemetryClient 

func NewTelemetryClient(iKey string) TelemetryClient

Creates a new telemetry client instance that submits telemetry with the specified instrumentation key.

func NewTelemetryClientFromConfig 

func NewTelemetryClientFromConfig(config *TelemetryConfiguration) TelemetryClient

Creates a new telemetry client instance configured by the specified TelemetryConfiguration object.

type TelemetryConfiguration 

type TelemetryConfiguration struct {
	// Instrumentation key for the client.
	InstrumentationKey string

	// Endpoint URL where data will be submitted.
	EndpointUrl string

	// Maximum number of telemetry items that can be submitted in each
	// request.  If this many items are buffered, the buffer will be
	// flushed before MaxBatchInterval expires.
	MaxBatchSize int

	// Maximum time to wait before sending a batch of telemetry.
	MaxBatchInterval time.Duration

	// Customized http client if desired (will use http.DefaultClient otherwise)
	Client *http.Client
}

Configuration data used to initialize a new TelemetryClient.

func NewTelemetryConfiguration 

func NewTelemetryConfiguration(instrumentationKey string) *TelemetryConfiguration

Creates a new TelemetryConfiguration object with the specified instrumentation key and default values.

type TelemetryContext 

type TelemetryContext struct {

	// Collection of tag data to attach to the telemetry item.
	Tags contracts.ContextTags

	// Common properties to add to each telemetry item.  This only has
	// an effect from the TelemetryClient's context instance.  This will
	// be nil on telemetry items.
	CommonProperties map[string]string
	// contains filtered or unexported fields
}

Encapsulates contextual data common to all telemetry submitted through a TelemetryClient instance such as including instrumentation key, tags, and common properties.

func NewTelemetryContext added in v0.4.1 

func NewTelemetryContext(ikey string) *TelemetryContext

Creates a new, empty TelemetryContext

func (*TelemetryContext) InstrumentationKey 

func (context *TelemetryContext) InstrumentationKey() string

Gets the instrumentation key associated with this TelemetryContext. This will be an empty string on telemetry items' context instances.

type TelemetryData added in v0.4.1 

type TelemetryData interface {
	EnvelopeName(string) string
	BaseType() string
	Sanitize() []string
}

Common interface implemented by telemetry data contracts

type TraceTelemetry 

type TraceTelemetry struct {
	BaseTelemetry
	BaseTelemetryNoMeasurements

	// Trace message
	Message string

	// Severity level
	SeverityLevel contracts.SeverityLevel
}

Trace telemetry items represent printf-like trace statements that can be text searched.

func NewTraceTelemetry 

func NewTraceTelemetry(message string, severityLevel contracts.SeverityLevel) *TraceTelemetry

Creates a trace telemetry item with the specified message and severity level.

func (*TraceTelemetry) TelemetryData added in v0.4.1 

func (trace *TraceTelemetry) TelemetryData() TelemetryData

Source Files

View all Source files

Directories

Path Synopsis
Data contract definitions for telemetry submitted to Application Insights.
 Data contract definitions for telemetry submitted to Application Insights.

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.