appinsightstrace

package module
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2022 License: MIT Imports: 7 Imported by: 4

README

Azure Application Insights Tracing

Wrapper over application insights package that allows for richer telemetry and w3c tracing support by exposing a more simplified interface

Installation

  1. Install module
go get github.com/BetaLixT/appInsightsTrace
  1. Import
import "github.com/BetaLixT/appInsightsTrace"

Usage

Create an application insights resource on Azure, and note down the instrumentation key

Construct a new AppInsightsCore instance using one of the existing constructors read the documentations on the constructors to learn more about them, for a quick start the NewBasic constructor is recommended but the NewAppInsightsCore with a custom implementation of ITraceExtractor is recommended for production use

In this example we use the NewBasic, provide the above mentioned instrumentationKey and the service name would be the name of the service/project you will be using this package in, this will be used as an application name when viewing the application map on Azure App Insights

tracer := appInsightsTrace.NewBasic(instrumentationKey, "WeatherService")

Once the struct has been created you can utilize one of the Trace functions to start tracing events, all telemetery you create with these functions will be batched and sent to application insights. Please read the documentation on these functions for more details, when using NewBasic (since this uses the default ITraceExtractor) it's recommended to use the WithIds functions so you can manually pass down the tracing information (instead of relying on context)

tracer.TraceRequestWithIds(
  "3251235485234561",
  "35623452",
  "35123514",
  "GET",
  "api/v1/weather",
  200,
  7000,
  "127.0.0.1",
  "Chrome",
  startTime,
  time.Now(),
  map[string]string{},
)

Recommendation

It's recommended that you create an implementation of ITraceExtractor according to how you handle w3c tracing within your service.

An example usage would be to have a request middleware that will check for trace-parent in the header or generate one if it doesn't exist, this trace-parent can then be parsed and along with the current request(span) id be injected into the context. You can then create an implementation of ITraceExtractor to extract said trace information from the context

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppInsightsCore 

type AppInsightsCore struct {
	Client appinsights.TelemetryClient

	ServName string
	// contains filtered or unexported fields
}

func NewAppInsightsCore 

func NewAppInsightsCore(
	optn *AppInsightsOptions,
	traceExtractor ITraceExtractor,
	lgr *zap.Logger,
) *AppInsightsCore

Constructs an instance of AppInsightsCore using the provided zap logger and a custom trace extractor, it's recommended to provide a custom trace extractor that will extract the w3c trace information from the context and take advantage of the context dependent trace functions, check documentation of ITraceExtractor for more information

func NewAppInsightsCoreFlatOptions added in v0.2.2 

func NewAppInsightsCoreFlatOptions(
	instrumentationKey string,
	serviceName string,
	traceExtractor ITraceExtractor,
	lgr *zap.Logger,
) *AppInsightsCore

Same as NewAppInsightsCorenbut without options, instead just taking values as strings

func NewBasic added in v0.2.2 

func NewBasic(
	instrumentationKey string,
	serviceName string,
) (*AppInsightsCore, error)

Constructs an instance of AppInsightsCore with defaults, including the default ITraceExtractor which does not provide any tracing information from the context it is recommended to use the non context dependent functions (functions that end with "WithIds") to take advangate of the tracing if you use this constructor

func NewBasicWithLogger added in v0.2.2 

func NewBasicWithLogger(
	instrumentationKey string,
	serviceName string,
	lgr zap.Logger,
) (*AppInsightsCore, error)

Constructs an instance of AppInsightsCore using the provided zap logger and the default ITraceExtractor which does not provide any tracing information from the context it is recommended to use the non context dependent functions (functions that end with "WithIds") to take advangate of the tracing if you use this constructor

func (*AppInsightsCore) Close 

func (insights *AppInsightsCore) Close()

func (*AppInsightsCore) ExtractTraceInfo added in v0.2.1 

func (ins *AppInsightsCore) ExtractTraceInfo(
	ctx context.Context,
) (ver, tid, pid, rid, flg string)

func (*AppInsightsCore) TraceDependency added in v0.2.0 

func (ins *AppInsightsCore) TraceDependency(
	ctx context.Context,
	spanId string,
	dependencyType string,
	serviceName string,
	commandName string,
	success bool,
	startTimestamp time.Time,
	eventTimestamp time.Time,
	fields map[string]string,
)

Transmits a new Dependency telemtery, this should be used to trace outgoing requests, database calls etc.

ctx: the current context of the execution, the ITraceExtractor.ExtractTraceInfo 

function will be utilized to extract traceId parentId and current requestId
from the context the default implementation of ITraceExtractor provided in
this package will leave these fields empty

spanId: optional id that can be provided, recommended to leave empty for most 

cases except if the dependency also follows w3c tracing (outgoing http calls)
just helps in forming an accurate trace tree

dependencyType: the type of the dependency, for example postgres, rabbitmq etc serviceName: unique name for the dependency (database address for example) commandName: name for the action being performed by the dependency, for example 

the method and path for an outgoing http request (GET /api/v1/weather)

success: whether the requet was successful or not startTimestamp: timestamp of when the dependency has been invoked by this 

service

eventTimestamp: timestamp of when the dependency has been completed fields: additional custom values to include in the telemetry

func (*AppInsightsCore) TraceDependencyWithIds added in v0.2.1 

func (ins *AppInsightsCore) TraceDependencyWithIds(
	traceId string,
	requestId string,
	spanId string,
	dependencyType string,
	serviceName string,
	commandName string,
	success bool,
	startTimestamp time.Time,
	eventTimestamp time.Time,
	fields map[string]string,
)

Transmits a new Dependency telemtery, this should be used to trace outgoing requests, database calls etc. it uses the provied traceId and requestId instead of trying to extract the same from the context.

traceId: is a common identifier for all dependents and dependencies for the 

request, can be left as an empty string but this would reduce tracablility

requestId is the unique Id for the request, generated at the start of the 

request, can be left as an empty string but this would reduce tracablility

spanId: optional id that can be provided, recommended to leave empty for most 

cases except if the dependency also follows w3c tracing (outgoing http calls)
just helps in forming an accurate trace tree

dependencyType: the type of the dependency, for example postgres, rabbitmq etc serviceName: unique name for the dependency (database address for example) commandName: name for the action being performed by the dependency, for example 

the method and path for an outgoing http request (GET /api/v1/weather)

success: whether the requet was successful or not startTimestamp: timestamp of when the dependency has been invoked by this 

service

eventTimestamp: timestamp of when the dependency has been completed fields: additional custom values to include in the telemetry

func (*AppInsightsCore) TraceEvent added in v0.2.3 

func (ins *AppInsightsCore) TraceEvent(
	ctx context.Context,
	name string,
	key string,
	statusCode int,
	startTimestamp time.Time,
	eventTimestamp time.Time,
	fields map[string]string,
)

Transmits a new Request telemtery for events, this should be used to trace incoming events (from a middleware for example).

ctx: the current context of the execution, the ITraceExtractor.ExtractTraceInfo 

function will be utilized to extract traceId parentId and current requestId
from the context the default implementation of ITraceExtractor provided in
this package will leave these fields empty

name: the custom name of the trace key: the routing key of the event statusCode: the response http status code (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) startTimestamp: timestamp of when the event was received by this service eventTimestamp: timestamp of when the event has completed processing by this 

service

func (*AppInsightsCore) TraceEventWithIds added in v0.2.3 

func (ins *AppInsightsCore) TraceEventWithIds(
	traceId string,
	parentId string,
	requestId string,
	name string,
	key string,
	statusCode int,
	startTimestamp time.Time,
	eventTimestamp time.Time,
	fields map[string]string,
)

Transmits a new Request telemtery for events, this should be used to trace incoming events (from a middleware for example).

traceId: is a common identifier for all dependents and dependencies for the 

request, can be left as an empty string but this would reduce tracablility

parentId is and id unique to the current request's direct dependent, can be left 

as an empty string but this would reduce tracablility

requestId is the unique Id for the request, generated at the start of the 

request, can be left as an empty string but this would reduce tracablility

name: the custom name of the trace key: the routing key of the event statusCode: the response http status code (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) startTimestamp: timestamp of when the event was received by this service eventTimestamp: timestamp of when the event has completed processing by this 

service

func (*AppInsightsCore) TraceException added in v0.2.2 

func (ins *AppInsightsCore) TraceException(
	ctx context.Context,
	err interface{},
	skip int,
	fields map[string]string,
)

Transmits a new exception telemetry, should be used to track unexpected errors or panics.

ctx: the current context of the execution, the ITraceExtractor.ExtractTraceInfo 

function will be utilized to extract traceId parentId and current requestId
from the context the default implementation of ITraceExtractor provided in
this package will leave these fields empty

err: the unexpected error object skip: the number of levels to skip on the call stack (set to 0 if unsure) severityLevel: the severity level (Critical, Error, Warning, Information, 

Verbose), it's recommended to use the constants of the same name provided
in this package

fields: additional custom values to include in the telemetry

func (*AppInsightsCore) TraceExceptionWithIds added in v0.2.2 

func (ins *AppInsightsCore) TraceExceptionWithIds(
	traceId string,
	requestId string,
	err interface{},
	skip int,
	fields map[string]string,
)

Transmits a new exception telemetry, should be used to track unexpected errors or panics. It uses the provied traceId and requestId instead of trying to extract the same from the context.

traceId: is a common identifier for all dependents and dependencies for the 

request, can be left as an empty string but this would reduce tracablility

requestId is the unique Id for the request, generated at the start of the 

request, can be left as an empty string but this would reduce tracablility

err: the unexpected error object skip: the number of levels to skip on the call stack (set to 0 if unsure) severityLevel: the severity level (Critical, Error, Warning, Information, 

Verbose), it's recommended to use the constants of the same name provided
in this package

fields: additional custom values to include in the telemetry

func (*AppInsightsCore) TraceLog added in v0.2.2 

func (ins *AppInsightsCore) TraceLog(
	ctx context.Context,
	message string,
	severityLevel SeverityLevel,
	fields map[string]string,
)

Transmits a new trace log telemetry.

ctx: the current context of the execution, the ITraceExtractor.ExtractTraceInfo 

function will be utilized to extract traceId parentId and current requestId
from the context the default implementation of ITraceExtractor provided in
this package will leave these fields empty

message: the message that is to be traced severityLevel: the severity level (Critical, Error, Warning, Information, 

Verbose), it's recommended to use the constants of the same name provided
in this package

fields: additional custom values to include in the telemetry

func (*AppInsightsCore) TraceLogWithIds added in v0.2.2 

func (ins *AppInsightsCore) TraceLogWithIds(
	traceId string,
	requestId string,
	message string,
	severityLevel contracts.SeverityLevel,
	timestamp time.Time,
	fields map[string]string,
)

Transmits a new trace log telemetry. It uses the provied traceId and requestId instead of trying to extract the same from the context.

traceId: is a common identifier for all dependents and dependencies for the 

request, can be left as an empty string but this would reduce tracablility

requestId is the unique Id for the request, generated at the start of the 

request, can be left as an empty string but this would reduce tracablility

message: the message that is to be traced severityLevel: the severity level (Critical, Error, Warning, Information, 

Verbose), it's recommended to use the constants of the same name provided
in this package

fields: additional custom values to include in the telemetry

func (*AppInsightsCore) TraceRequest added in v0.2.0 

func (ins *AppInsightsCore) TraceRequest(
	ctx context.Context,
	method string,
	path string,
	query string,
	statusCode int,
	bodySize int,
	ip string,
	userAgent string,
	startTimestamp time.Time,
	eventTimestamp time.Time,
	fields map[string]string,
)

Transmits a new Request telemtery, this should be used to trace incoming requests (from a middleware for example).

ctx: the current context of the execution, the ITraceExtractor.ExtractTraceInfo 

function will be utilized to extract traceId parentId and current requestId
from the context the default implementation of ITraceExtractor provided in
this package will leave these fields empty

method: the http request method (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) path: the path for the request (ex: /api/v1/weather) query: any query paramters provided with the request statusCode: the response http status code (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) bodySize: the size of the response body ip: ip of the client making the request userAgent: the user agent of the client making the request (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) startTimestamp: timestamp of when the request was received by this service eventTimestamp: timestamp of when the request has completed processing by this 

service

func (*AppInsightsCore) TraceRequestWithIds added in v0.2.2 

func (ins *AppInsightsCore) TraceRequestWithIds(
	traceId string,
	parentId string,
	requestId string,
	method string,
	path string,
	query string,
	statusCode int,
	bodySize int,
	ip string,
	userAgent string,
	startTimestamp time.Time,
	eventTimestamp time.Time,
	fields map[string]string,
)

Transmits a new Request telemtery, this should be used to trace incoming requests (from a middleware for example). it uses the provied traceId, parentId and requestId instead of trying to extract the same from the context. The said IDs follow the W3C trace-context spec (https://www.w3.org/TR/trace-context/).

traceId: is a common identifier for all dependents and dependencies for the 

request, can be left as an empty string but this would reduce tracablility

parentId is and id unique to the current request's direct dependent, can be left 

as an empty string but this would reduce tracablility

requestId is the unique Id for the request, generated at the start of the 

request, can be left as an empty string but this would reduce tracablility

method: the http request method (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) path: the path for the request (ex: /api/v1/weather) query: any query paramters provided with the request statusCode: the response http status code (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) bodySize: the size of the response body ip: ip of the client making the request userAgent: the user agent of the client making the request (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) startTimestamp: timestamp of when the request was received by this service eventTimestamp: timestamp of when the request has completed processing by this 

service

fields: additional custom values to include in the telemetry

type AppInsightsOptions added in v0.1.1 

type AppInsightsOptions struct {
	InstrumentationKey string
	ServiceName        string
}

type DefaultTraceExtractor added in v0.2.2 

type DefaultTraceExtractor struct {
}

func (*DefaultTraceExtractor) ExtractTraceInfo added in v0.2.2 

func (*DefaultTraceExtractor) ExtractTraceInfo(
	_ context.Context,
) (ver, tid, pid, rid, flg string)

type ITraceExtractor added in v0.2.1 

type ITraceExtractor interface {
	ExtractTraceInfo(
		ctx context.Context,
	) (ver, tid, pid, rid, flg string)
}

Implement this to extract w3c-trace information from the context, an example usage would be to build a middleware for incoming http calls to inject trace information into the context and create an implementation of ITraceExtractor to get the trace (using ctx.Value and with the correct key(s))

type SeverityLevel added in v0.2.2 

type SeverityLevel int
const (
	Verbose     SeverityLevel = 0
	Information SeverityLevel = 1
	Warning     SeverityLevel = 2
	Error       SeverityLevel = 3
	Critical    SeverityLevel = 4
)

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.