tracestate

Documentation

Overview

tracestate is a package that is used to keep track of the state of the tracing process in the scope of a current function. It also provides ways to modify the existing tracing state, or add it to function or line of code.

Index

• type State
  • func FunctionBody(transactionVariable string, obj ...traceobject.TraceObject) *State
  • func Main(agentVariable string) *State
  • func (tc *State) AddParameterToDeclaration(pkg *decorator.Package, node dst.Node) string
  • func (tc *State) AddToCall(pkg *decorator.Package, call *dst.CallExpr, async bool) (*State, string)
  • func (tc *State) AgentVariable() dst.Expr
  • func (tc *State) AssignTransactionVariable(node dst.Node) string
  • func (tc *State) CreateSegment(node dst.Node) (string, bool)
  • func (tc *State) FuncLiteralDeclaration(pkg *decorator.Package, lit *dst.FuncLit) *State
  • func (tc *State) GetFuncLitVariable(pkg *decorator.Package, variable dst.Expr) (*dst.FuncLit, bool)
  • func (tc *State) IsMain() bool
  • func (tc *State) NoticeFuncLiteralAssignment(pkg *decorator.Package, variable dst.Expr, lit *dst.FuncLit)
  • func (tc *State) TransactionVariable() dst.Expr
  • func (tc *State) WrapWithTransaction(c *dstutil.Cursor, functionName, transactionVariable string)

Types

type State

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

State stores the current state of the tracing process in the scope of a current function. Each function should be passed its own unique state object in oreder to preserve indepence between functions, and correctness. The state object will keep track of the current transaction variable, agent variable, and other stateful information about how instrumentation is being added and utilized in the scope of the current function.

When creating a state, a TraceObject should be passed. This object identifies the way the transaction is being passed to the function, and takes care of how to correctly handle it.

func FunctionBody

func FunctionBody(transactionVariable string, obj ...traceobject.TraceObject) *State

FunctionBody creates a trace state for tracing a function body.

func Main

func Main(agentVariable string) *State

Main creates a new State object for tracing a main function. We know the agent must be initialized in the main function.

The agentVariable is the name of the agent variable in the main function. The trace object will always be a transaction in this case, since we have to

start a transaction in the main function.

func (*State) AddParameterToDeclaration

func (tc *State) AddParameterToDeclaration(pkg *decorator.Package, node dst.Node) string

AddToFunctionDecl adds a parameter to pass a New Relic transaction to a function declaration if needed. It MUST be passed the decorator package for the package the function call is being made in.

This function returns a string for any library that needs to be imported with go get before the code will compile.

This function will update the call expression in place. The object containing the transaction that is passed to the function will depend on what parameters the function takes, and what is being passed. In general, the rules for what is passed are:

1. If the function takes an argument of the same type as the tracing object, we will pass as that type.
2. If the function takes an argument of type context.Context, we will inject the transaction into the passed context.
3. If neither case 1 or case 2 is met, a *newrelic.Transaction will be passed as the last argument of the function.

func (*State) AddToCall

func (tc *State) AddToCall(pkg *decorator.Package, call *dst.CallExpr, async bool) (*State, string)

AddToCall passes a New Relic transaction, or an object that contains one, to a function call. It MUST be passed the decorator package for the package the function call is being made in. If the function call is a goroutine, async should be true.

This function returns a string for any library that needs to be imported with go get before the code will compile.

This function will update the call expression in place. The object containing the transaction that is passed to the function will depend on what parameters the function takes, and what is being passed. In general, the rules for what is passed are:

1. If the function takes an argument of the same type as the tracing object, we will pass as that type.
2. If the function takes an argument of type context.Context, we will inject the transaction into the passed context.
3. If neither case 1 or case 2 is met, a *newrelic.Transaction will be passed as the last argument of the function.

func (*State) AgentVariable

func (tc *State) AgentVariable() dst.Expr

AgentVariable returns the name of the agent variable. This may return an empty string if no agent variable is in scope.

func (*State) AssignTransactionVariable

func (tc *State) AssignTransactionVariable(node dst.Node) string

AssignTransactionVariable assigns the transaction variable to a new variable that will always be the default transaction variable name. It will handle all the conditional checking for you, and will only add a transaction assignment if needed. The expression to assign the transaciton variable will be added in place into the body of the node passed, which must be a function declaration or a function literal.

In some cases, this may require a library to be installed, and it will return the import path for that library.

func (*State) CreateSegment

func (tc *State) CreateSegment(node dst.Node) (string, bool)

CreateSegment creates a segment for the current function if needed. Calling this will add a defer statement to the function declaration that will create a segment as the first statement in the function. This function will return the import path for the library that needs to be installed if a segment is created. The second return value will be true if a segment was created.

func (*State) FuncLiteralDeclaration

func (tc *State) FuncLiteralDeclaration(pkg *decorator.Package, lit *dst.FuncLit) *State

FuncDeclaration creates a trace state for a function declaration.

func (*State) GetFuncLitVariable

func (tc *State) GetFuncLitVariable(pkg *decorator.Package, variable dst.Expr) (*dst.FuncLit, bool)

GetFuncLitVariable returns a function literal that was assigned to a variable in the scope of this function. TODO: Move this functionality to manager.

func (*State) IsMain

func (tc *State) IsMain() bool

IsMain returns true if the current state is for a main function.

func (*State) NoticeFuncLiteralAssignment

func (tc *State) NoticeFuncLiteralAssignment(pkg *decorator.Package, variable dst.Expr, lit *dst.FuncLit)

NoticeFuncLiteralAssignment is called when a function literal is assigned to a variable.

func (*State) TransactionVariable

func (tc *State) TransactionVariable() dst.Expr

TransactionVariable returns the name of the transaction variable.

func (*State) WrapWithTransaction

func (tc *State) WrapWithTransaction(c *dstutil.Cursor, functionName, transactionVariable string)

WrapWithTransaction creates a transaction in the line before the current cursor position if all of these contidions are met:

1. The agent variable is in scope
2. The cursor is in a function body
3. We are in the main method

The transaction created will always be assigned to a variable with the default transaction variable name.