Documentation
¶
Overview ¶
Package pinpoint provides the APIs to instrument Go applications for Pinpoint (https://github.com/pinpoint-apm/pinpoint).
This package enables you to monitor Go applications using Pinpoint. Go applications must be instrumented manually at the source code level, because Go is a compiled language and does not have a virtual machine like Java. Developers can instrument Go applications using the APIs provided in this package. It has support for instrumenting Go’s built-in http package, database/sql drivers and plug-ins for popular frameworks and toolkits (like Gin and gRPC, ...).
In Pinpoint, a transaction consists of a group of Spans. Each span represents a trace of a single logical node where the transaction has gone through. A span records important function invocations and their related data(arguments, return value, etc.) before encapsulating them as SpanEvents in a call stack like representation. The span itself and each of its SpanEvents represents a function invocation. Find out more about the concept of Pinpoint at the links below:
Index ¶
- Constants
- func AddConfig(cfgName string, valueType int, defaultValue interface{}, dynamic bool)
- func IsLogLevelEnabled(level logrus.Level) bool
- func Log(src string) *logEntry
- func NewContext(ctx context.Context, tracer Tracer) context.Context
- func RequestWithTracerContext(req *http.Request, tracer Tracer) *http.Request
- func SetExtraLogger(lgr *logrus.Logger)
- func WrapSQLDriver(drv driver.Driver, info DBInfo) driver.Driver
- type Agent
- type Annotation
- type Config
- func (config *Config) AddReloadCallback(optNames []string, callback func())
- func (config *Config) Bool(cfgName string) bool
- func (config *Config) Float(cfgName string) float64
- func (config *Config) Int(cfgName string) int
- func (config *Config) Set(cfgName string, value interface{})
- func (config *Config) String(cfgName string) string
- func (config *Config) StringSlice(cfgName string) []string
- type ConfigOption
- func WithActiveProfile(profile string) ConfigOption
- func WithAgentId(id string) ConfigOption
- func WithAgentName(name string) ConfigOption
- func WithAppName(name string) ConfigOption
- func WithAppType(typ int32) ConfigOption
- func WithCollectorAgentPort(port int) ConfigOption
- func WithCollectorHost(host string) ConfigOption
- func WithCollectorSpanPort(port int) ConfigOption
- func WithCollectorStatPort(port int) ConfigOption
- func WithConfigFile(filePath string) ConfigOption
- func WithEnable(enable bool) ConfigOption
- func WithErrorCallStackDepth(depth int) ConfigOption
- func WithErrorTraceCallStack(trace bool) ConfigOption
- func WithHttpUrlStatEnable(enable bool) ConfigOption
- func WithHttpUrlStatLimitSize(size int) ConfigOption
- func WithHttpUrlStatWithMethod(withMethod bool) ConfigOption
- func WithIsContainerEnv(isContainer bool) ConfigOption
- func WithLogLevel(level string) ConfigOption
- func WithLogMaxSize(size int) ConfigOption
- func WithLogOutput(output string) ConfigOption
- func WithSQLMaxBindValueSize(size int) ConfigOption
- func WithSQLTraceBindValue(trace bool) ConfigOption
- func WithSQLTraceCommit(trace bool) ConfigOption
- func WithSQLTraceQueryStat(collect bool) ConfigOption
- func WithSQLTraceRollback(trace bool) ConfigOption
- func WithSamplingContinueThroughput(tps int) ConfigOption
- func WithSamplingCounterRate(rate int) ConfigOption
- func WithSamplingNewThroughput(tps int) ConfigOption
- func WithSamplingPercentRate(rate float32) ConfigOption
- func WithSamplingRate(rate int) ConfigOption
- func WithSamplingType(samplingType string) ConfigOption
- func WithSpanEventChunkSize(size int) ConfigOption
- func WithSpanMaxCallStackDepth(depth int) ConfigOption
- func WithSpanMaxCallStackSequence(seq int) ConfigOption
- func WithSpanQueueSize(size int) ConfigOption
- func WithStatBatchCount(count int) ConfigOption
- func WithStatCollectInterval(interval int) ConfigOption
- type DBInfo
- type DistributedTracingContextReader
- type DistributedTracingContextWriter
- type SpanEventRecorder
- type SpanRecorder
- type Tracer
- type TransactionId
- type UrlStatEntry
Constants ¶
const ( CfgAppName = "ApplicationName" CfgAppType = "ApplicationType" CfgAgentID = "AgentID" CfgAgentName = "AgentName" CfgCollectorHost = "Collector.Host" CfgCollectorAgentPort = "Collector.AgentPort" CfgCollectorSpanPort = "Collector.SpanPort" CfgCollectorStatPort = "Collector.StatPort" CfgLogLevelOld = "LogLevel" CfgLogLevel = "Log.Level" CfgLogOutput = "Log.Output" CfgLogMaxSize = "Log.MaxSize" CfgSamplingType = "Sampling.Type" CfgSamplingCounterRate = "Sampling.CounterRate" CfgSamplingPercentRate = "Sampling.PercentRate" CfgSamplingNewThroughput = "Sampling.NewThroughput" CfgSamplingContinueThroughput = "Sampling.ContinueThroughput" CfgSpanQueueSize = "Span.QueueSize" CfgSpanEventChunkSize = "Span.EventChunkSize" CfgSpanMaxCallStackDepth = "Span.MaxCallStackDepth" CfgSpanMaxCallStackSequence = "Span.MaxCallStackSequence" CfgStatCollectInterval = "Stat.CollectInterval" CfgStatBatchCount = "Stat.BatchCount" CfgIsContainerEnv = "IsContainerEnv" CfgConfigFile = "ConfigFile" CfgActiveProfile = "ActiveProfile" CfgSQLTraceBindValue = "SQL.TraceBindValue" CfgSQLMaxBindValueSize = "SQL.MaxBindValueSize" CfgSQLTraceCommit = "SQL.TraceCommit" CfgSQLTraceRollback = "SQL.TraceRollback" CfgSQLTraceQueryStat = "SQL.TraceQueryStat" CfgEnable = "Enable" CfgHttpUrlStatEnable = "Http.UrlStat.Enable" CfgHttpUrlStatLimitSize = "Http.UrlStat.LimitSize" CfgHttpUrlStatWithMethod = "Http.UrlStat.WithMethod" CfgErrorTraceCallStack = "Error.TraceCallStack" CfgErrorCallStackDepth = "Error.CallStackDepth" )
Config option keys
const ( CfgInt int = iota CfgFloat CfgBool CfgString CfgStringSlice )
Config value type
const ( HeaderTraceId = "Pinpoint-TraceID" HeaderSpanId = "Pinpoint-SpanID" HeaderParentSpanId = "Pinpoint-pSpanID" HeaderSampled = "Pinpoint-Sampled" HeaderFlags = "Pinpoint-Flags" HeaderParentApplicationName = "Pinpoint-pAppName" HeaderParentApplicationType = "Pinpoint-pAppType" HeaderParentApplicationNamespace = "Pinpoint-pAppNamespace" HeaderHost = "Pinpoint-Host" )
keys of distributed tracing headers
const ( ServiceTypeGoApp = 1800 ServiceTypeGoFunction = 1801 ServiceTypeGoHttpClient = 9401 ServiceTypeAsync = 100 ServiceTypeMysql = 2100 ServiceTypeMysqlExecuteQuery = 2101 ServiceTypeMssql = 2200 ServiceTypeMssqlExecuteQuery = 2201 ServiceTypeOracle = 2300 ServiceTypeOracleExecuteQuery = 2301 ServiceTypePgSql = 2500 ServiceTypePgSqlExecuteQuery = 2501 ServiceTypeCassandraExecuteQuery = 2601 ServiceTypeMongo = 2650 ServiceTypeMongoExecuteQuery = 2651 ServiceTypeGrpc = 9160 ServiceTypeGrpcServer = 1130 ServiceTypeMemcached = 8050 ServiceTypeRedis = 8203 ServiceTypeKafkaClient = 8660 ServiceTypeHbaseClient = 8800 ServiceTypeGoElastic = 9204 )
service types pre-defined
const ( AnnotationArgs0 = -1 AnnotationApi = 12 AnnotationSqlId = 20 AnnotationSqlUid = 25 AnnotationHttpUrl = 40 AnnotationHttpParam = 41 AnnotationHttpCookie = 45 AnnotationHttpStatusCode = 46 AnnotationHttpRequestHeader = 47 AnnotationHttpResponseHeader = 55 AnnotationHttpProxyHeader = 300 AnnotationKafkaTopic = 140 AnnotationKafkaPartition = 141 AnnotationKafkaOffset = 142 AnnotationMongoJasonData = 150 AnnotationMongoCollectionInfo = 151 AnnotationEsDsl = 173 AnnotationHbaseClientParams = 320 AnnotationExceptionChainId = -52 )
annotation keys pre-defined
const ( LogTransactionIdKey = "PtxId" LogSpanIdKey = "PspanId" Logged = 1 NotLogged = 0 MetricURLStat = "URLStat" )
const (
Version = "1.4.7"
)
Variables ¶
This section is empty.
Functions ¶
func IsLogLevelEnabled ¶ added in v1.3.3
func NewContext ¶
NewContext returns a new Context that contains the given Tracer.
func RequestWithTracerContext ¶
RequestWithTracerContext returns the request that has a Context carrying the given Tracer.
func SetExtraLogger ¶ added in v1.2.0
Types ¶
type Agent ¶
type Agent interface { // NewSpanTracer returns a span Tracer indicating the start of a transaction. // A span is generated according to a given sampling policy, and trace data is not collected if not sampled. NewSpanTracer(operation string, rpcName string) Tracer // NewSpanTracerWithReader returns a span Tracer that continues a transaction passed from the previous node. // A span is generated according to a given sampling policy, and trace data is not collected if not sampled. // Distributed tracing headers are extracted from the reader. If it is empty, new transaction is started. NewSpanTracerWithReader(operation string, rpcName string, reader DistributedTracingContextReader) Tracer // Enable returns whether the agent is in an operational state. Enable() bool // Config returns the configuration associated with the agent. Config() *Config // Shutdown stops all related goroutines managing this agent. // After Shutdown is called, the agent will never collect tracing data again. Shutdown() }
Agent instruments an application and makes spans and manages it.
func GetAgent ¶ added in v1.0.0
func GetAgent() Agent
GetAgent returns a global Agent created by NewAgent.
func NewAgent ¶
NewAgent creates an Agent and spawns goroutines that manage spans and statistical data. The generated Agent is maintained globally and only one instance is retained. The provided config is generated by NewConfig and an error is returned if it is nil.
example:
opts := []pinpoint.ConfigOption{ pinpoint.WithAppName("GoTestApp"), pinpoint.WithConfigFile(os.Getenv("HOME") + "/tmp/pinpoint-config.yaml"), } cfg, err := pinpoint.NewConfig(opts...) agent, err := pinpoint.NewAgent(cfg)
type Annotation ¶
type Annotation interface { // AppendInt records an integer value to annotation. AppendInt(key int32, i int32) // AppendLong records a long value to annotation. AppendLong(key int32, l int64) // AppendString records a string value to annotation. AppendString(key int32, s string) // AppendStringString records two string values to annotation. AppendStringString(key int32, s1 string, s2 string) // AppendIntStringString records an integer value and two string values to annotation. AppendIntStringString(key int32, i int32, s1 string, s2 string) // AppendBytesStringString records an array of byte and two string values to annotation. AppendBytesStringString(key int32, b []byte, s1 string, s2 string) // AppendLongIntIntByteByteString records a long integer value, two integer value, two byte value and a string value to annotation. AppendLongIntIntByteByteString(key int32, l int64, i1 int32, i2 int32, b1 int32, b2 int32, s string) }
Annotation is a key-value pair and used to annotate Span and SpanEvent with more information.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config holds agent configuration, for passing to NewAgent.
func GetConfig ¶ added in v1.0.0
func GetConfig() *Config
GetConfig returns a global Config created by NewConfig.
func NewConfig ¶
func NewConfig(opts ...ConfigOption) (*Config, error)
NewConfig creates a Config populated with default settings, command line arguments, environment variables and the given config options. Config uses the following precedence order. Each item takes precedence over the item below it:
- command line flag
- environment variable
- configuration file
- ConfigOption
- default
configuration keys used in config files are case-insensitive. The generated Config is maintained globally.
example:
opts := []pinpoint.ConfigOption{ pinpoint.WithAppName("GoTestApp"), pinpoint.WithConfigFile(os.Getenv("HOME") + "/tmp/pinpoint-config.yaml"), } cfg, err := pinpoint.NewConfig(opts...)
func (*Config) AddReloadCallback ¶ added in v1.3.0
AddReloadCallback adds a callback function will be called after reloading config file.
func (*Config) Bool ¶ added in v1.0.0
Bool returns a boolean value for the specified configuration item.
func (*Config) Float ¶ added in v1.0.0
Float returns a float value for the specified configuration item.
func (*Config) Int ¶ added in v1.0.0
Int returns an integer value for the specified configuration item.
func (*Config) StringSlice ¶ added in v1.0.0
StringSlice returns a string slice value for the specified configuration item.
type ConfigOption ¶
type ConfigOption func(*Config)
ConfigOption represents an option that can be passed to NewConfig.
func WithActiveProfile ¶ added in v1.0.0
func WithActiveProfile(profile string) ConfigOption
WithActiveProfile sets the configuration profile.
func WithAgentName ¶ added in v1.0.0
func WithAgentName(name string) ConfigOption
WithAgentName sets the agent name.
func WithAppName ¶
func WithAppName(name string) ConfigOption
WithAppName sets the application name.
func WithCollectorAgentPort ¶
func WithCollectorAgentPort(port int) ConfigOption
WithCollectorAgentPort sets the agent port of pinpoint collector.
func WithCollectorHost ¶
func WithCollectorHost(host string) ConfigOption
WithCollectorHost sets the host address of pinpoint collector.
func WithCollectorSpanPort ¶
func WithCollectorSpanPort(port int) ConfigOption
WithCollectorSpanPort sets the span port of pinpoint collector.
func WithCollectorStatPort ¶
func WithCollectorStatPort(port int) ConfigOption
WithCollectorStatPort sets the agent stat of pinpoint collector.
func WithConfigFile ¶
func WithConfigFile(filePath string) ConfigOption
WithConfigFile sets the configuration file.
func WithEnable ¶ added in v1.0.0
func WithEnable(enable bool) ConfigOption
WithEnable enables the agent is operational state.
func WithErrorCallStackDepth ¶ added in v1.4.0
func WithErrorCallStackDepth(depth int) ConfigOption
WithErrorCallStackDepth sets the maximum depth of call stack that can be dumped.
func WithErrorTraceCallStack ¶ added in v1.4.0
func WithErrorTraceCallStack(trace bool) ConfigOption
WithErrorTraceCallStack enables the agent collects a call stack when error occurs.
func WithHttpUrlStatEnable ¶ added in v1.3.0
func WithHttpUrlStatEnable(enable bool) ConfigOption
WithHttpUrlStatEnable enables the agent collects the HTTP URL statistics.
func WithHttpUrlStatLimitSize ¶ added in v1.3.0
func WithHttpUrlStatLimitSize(size int) ConfigOption
WithHttpUrlStatLimitSize sets the maximum number of URLs that can be stored in one snapshot.
func WithHttpUrlStatWithMethod ¶ added in v1.4.0
func WithHttpUrlStatWithMethod(withMethod bool) ConfigOption
WithHttpUrlStatWithMethod adds http method as prefix to uri string key.
func WithIsContainerEnv ¶ added in v1.0.0
func WithIsContainerEnv(isContainer bool) ConfigOption
WithIsContainerEnv sets whether the application is running in a container environment or not. If this is not set, the agent automatically checks it.
func WithLogLevel ¶
func WithLogLevel(level string) ConfigOption
WithLogLevel sets the logging level for agent logger.
func WithLogMaxSize ¶ added in v1.2.0
func WithLogMaxSize(size int) ConfigOption
WithLogMaxSize sets the max size of output file for agent logger.
func WithLogOutput ¶ added in v1.2.0
func WithLogOutput(output string) ConfigOption
WithLogOutput sets the output for agent logger.
func WithSQLMaxBindValueSize ¶ added in v1.0.0
func WithSQLMaxBindValueSize(size int) ConfigOption
WithSQLMaxBindValueSize sets the max length of traced bind value for SQL Driver.
func WithSQLTraceBindValue ¶ added in v1.0.0
func WithSQLTraceBindValue(trace bool) ConfigOption
WithSQLTraceBindValue enables bind value tracing for SQL Driver.
func WithSQLTraceCommit ¶ added in v1.0.0
func WithSQLTraceCommit(trace bool) ConfigOption
WithSQLTraceCommit enables commit tracing for SQL Driver.
func WithSQLTraceQueryStat ¶ added in v1.4.0
func WithSQLTraceQueryStat(collect bool) ConfigOption
WithSQLTraceQueryStat enables to trace SQL query statistics for SQL Driver.
func WithSQLTraceRollback ¶ added in v1.0.0
func WithSQLTraceRollback(trace bool) ConfigOption
WithSQLTraceRollback enables rollback tracing for SQL Driver.
func WithSamplingContinueThroughput ¶
func WithSamplingContinueThroughput(tps int) ConfigOption
WithSamplingContinueThroughput sets the cont tps for a 'throughput sampler'.
func WithSamplingCounterRate ¶ added in v1.0.0
func WithSamplingCounterRate(rate int) ConfigOption
WithSamplingCounterRate sets the sampling rate for a 'counter sampler'.
func WithSamplingNewThroughput ¶
func WithSamplingNewThroughput(tps int) ConfigOption
WithSamplingNewThroughput sets the new tps for a 'throughput sampler'.
func WithSamplingPercentRate ¶ added in v1.0.0
func WithSamplingPercentRate(rate float32) ConfigOption
WithSamplingPercentRate sets the sampling rate for a 'percent sampler'.
func WithSamplingRate ¶
func WithSamplingRate(rate int) ConfigOption
WithSamplingRate DEPRECATED: Use WithSamplingCounterRate()
func WithSamplingType ¶ added in v1.0.0
func WithSamplingType(samplingType string) ConfigOption
WithSamplingType sets the type of agent sampler. Either "COUNTER" or "PERCENT" must be specified.
func WithSpanEventChunkSize ¶ added in v1.4.3
func WithSpanEventChunkSize(size int) ConfigOption
WithSpanEventChunkSize sets the event chunk of a span.
func WithSpanMaxCallStackDepth ¶ added in v1.2.0
func WithSpanMaxCallStackDepth(depth int) ConfigOption
WithSpanMaxCallStackDepth sets the max callstack depth of a span.
func WithSpanMaxCallStackSequence ¶ added in v1.2.0
func WithSpanMaxCallStackSequence(seq int) ConfigOption
WithSpanMaxCallStackSequence sets the max callstack sequence of a span.
func WithSpanQueueSize ¶ added in v1.2.0
func WithSpanQueueSize(size int) ConfigOption
WithSpanQueueSize sets the size of the span queue for gRPC.
func WithStatBatchCount ¶
func WithStatBatchCount(count int) ConfigOption
WithStatBatchCount sets batch delivery units for collected statistics.
func WithStatCollectInterval ¶
func WithStatCollectInterval(interval int) ConfigOption
WithStatCollectInterval sets the statistics collection cycle for the agent.
type DistributedTracingContextReader ¶
type DistributedTracingContextReader interface { // Get returns the value of a given key from carrier. Get(key string) string }
DistributedTracingContextReader reads distributed tracing headers from carrier.
type DistributedTracingContextWriter ¶
type DistributedTracingContextWriter interface { // Set sets a given key-value pair to carrier. Set(key string, value string) }
DistributedTracingContextWriter writes distributed tracing headers to carrier.
type SpanEventRecorder ¶
type SpanEventRecorder interface { // SetServiceType sets the type of service. SetServiceType(typ int32) // SetDestination sets the destination of operation. SetDestination(id string) // SetEndPoint sets the end point of operation. SetEndPoint(endPoint string) // SetError Record an error and indicate that operation has failed. SetError(e error, errorName ...string) // SetSQL records the SQL string and bind variables. SetSQL(sql string, args string) // Annotations returns annotations that the SpanEvent holds. Annotations() Annotation // FixDuration fixes the elapsed time of operation. FixDuration(start time.Time, end time.Time) }
SpanEventRecorder records the collected data in the fields of SpanEvent.
type SpanRecorder ¶
type SpanRecorder interface { // SetServiceType sets the type of service. SetServiceType(typ int32) // SetError Record an error and indicate that operation has failed. SetError(e error) // SetFailure indicate that operation has failed. SetFailure() // SetRpcName sets the name of RPC. // This value is displayed as the path of the span on the pinpoint web screen. SetRpcName(rpc string) // SetRemoteAddress sets the remote address. SetRemoteAddress(remoteAddress string) // SetEndPoint sets the end point of RPC. SetEndPoint(endPoint string) // SetAcceptorHost sets the host of acceptor. SetAcceptorHost(host string) // SetLogging sets whether the Span has been logged. SetLogging(logInfo int32) // Annotations returns annotations that the Span holds. Annotations() Annotation }
SpanRecorder records the collected data in the fields of Span.
type Tracer ¶
type Tracer interface { // NewSpanEvent returns a span event. NewSpanEvent(operationName string) Tracer // NewAsyncSpan is deprecated. Use NewGoroutineTracer. NewAsyncSpan() Tracer // NewGoroutineTracer returns a tracer that tracks the call stack of a goroutine. NewGoroutineTracer() Tracer // WrapGoroutine generates a tracer that tracks a given goroutine and passes it in context. WrapGoroutine(goroutineName string, goroutine func(context.Context), ctx context.Context) func() // EndSpan completes the span and transmits it to the collector. // Sending a span is handled by a separate goroutine. EndSpan() // EndSpanEvent completes the span event. EndSpanEvent() // Inject injects distributed tracing headers to the writer. Inject(writer DistributedTracingContextWriter) // Extract extracts distributed tracing headers from the reader. Extract(reader DistributedTracingContextReader) // TransactionId returns the ID of the transaction containing the span. TransactionId() TransactionId // SpanId returns the ID of the span. SpanId() int64 Span() SpanRecorder SpanEvent() SpanEventRecorder // IsSampled returns whether the span has been sampled. IsSampled() bool // AddMetric adds a custom metric. AddMetric(metric string, value interface{}) JsonString() []byte AsyncSpanId() string }
Tracer instruments a single call stack of application and makes the result a single span.
func FromContext ¶
FromContext returns the Tracer from the context. If not present, NoopTracer is returned.
func NewDatabaseTracer ¶
NewDatabaseTracer returns a Tracer for database operation.
func NoopTracer ¶ added in v1.0.0
func NoopTracer() Tracer
NoopTracer returns a Tracer that doesn't collect tracing data.
func TracerFromRequestContext ¶
TracerFromRequestContext returns the Tracer from the request's context. If not present, NoopTracer is returned.
type TransactionId ¶
TransactionId represents that different RPCs are associated with each other as a single transaction.
func (TransactionId) String ¶
func (tid TransactionId) String() string
String returns transaction id string.
type UrlStatEntry ¶ added in v1.3.0
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
example
module
|
|
plugin
|
|
beego
Module
|
|
chi
Module
|
|
echo
Module
|
|
echov4
Module
|
|
fasthttp
Module
|
|
fasthttprouter
Module
|
|
fiber
Module
|
|
gin
Module
|
|
gocql
Module
|
|
goelastic
Module
|
|
gohbase
Module
|
|
gomemcache
Module
|
|
goredis
Module
|
|
goredisv7
Module
|
|
goredisv8
Module
|
|
goredisv9
Module
|
|
gorilla
Module
|
|
gorm
Module
|
|
grpc
Module
|
|
http
Module
|
|
httprouter
Module
|
|
kratos
Module
|
|
logrus
Module
|
|
mongodriver
Module
|
|
mssql
Module
|
|
mysql
Module
|
|
oracle
Module
|
|
pgsql
Module
|
|
pgxv5
Module
|
|
redigo
Module
|
|
rueidis
Module
|
|
sarama
Module
|
|
sarama-IBM
Module
|
|
mock
Package mock_v1 is a generated GoMock package.
|
Package mock_v1 is a generated GoMock package. |