Documentation
¶
Overview ¶
testhelpers.go provides shared test utilities for parser and integration tests. These functions are used across multiple test files and packages.
Parser is a static analysis library that can detect and inject instrumentation code into a Go application. It does this in the following steps:
Generate an abstract syntax tree from the application using DST. A unique tree will be generated for every package in the parsed application. Trees get stored in a cache that seperates data based on the pacakage it belongs to, and can be looked up by the path of that package, which is a unique identifier.
Walk the syntax tree for each package in a given application. While we do that, we build a new data structure that contains data mapped by package. This data structure is looking for a few key pieces of information, but primarily, it is looking for user defined function declarations. These declarations are objects in the tree, and we can uniquely identify them by package name, and function name. Additional key information is discovered with `FactDiscoveryFunctions` and cached in an object called the `FactStore`, which can be used for recognizing key information that is not available in the scope of a single package or function call.
Once we have gathered all our facts and impelentation data, we have all the information we need to instrument an application. The tool will walk through the entire syntax tree for each package again, making this the second full walk of the tree(s). This time, it will look for sections of code where middleware can be injected, tracing has already been started by middleware, or tracing could potentially be started using `StatelessTracingFunctions`. Then it will apply tracing to that section of code, as well as all reachable code that is called from the current scope, using `StatefulTracingFunctions`. Once this has completed, a modified tree with complete instrumentation written into the code has been built.
Restore the modified tree back to code. That code is compared to the original application, and a GIT compatible diff is generated in memory. This diff file is written to a file in the local operating system where the user can review it and decide how to proceed.
Index ¶
- func CleanTestApp(t *testing.T, appDirectoryName string)
- func ConfigureTestInstrumentationManager(manager *InstrumentationManager) error
- func CreateTestApp(t *testing.T, testAppDir, fileName, contents string) ([]*decorator.Package, error)
- func DetectEchoInstrumentation(manager *InstrumentationManager, c *dstutil.Cursor)
- func DetectEchoV3Instrumentation(manager *InstrumentationManager, c *dstutil.Cursor)
- func DetectErrors(manager *InstrumentationManager, c *dstutil.Cursor)
- func DetectGinInstrumentation(manager *InstrumentationManager, c *dstutil.Cursor)
- func DetectTransactions(manager *InstrumentationManager, c *dstutil.Cursor)
- func NoticeError(manager *InstrumentationManager, stmt dst.Stmt, c *dstutil.Cursor, ...) bool
- func PanicRecovery(t *testing.T)
- func Pseudo_uuid() (string, error)
- func RunStatefulTracingFunction(t *testing.T, code string, stmtFunc StatefulTracingFunction, downstream bool) string
- func RunStatelessTracingFunction(t *testing.T, code string, tracingFunc StatelessTracingFunction, ...) string
- func TraceFunction(manager *InstrumentationManager, node dst.Node, tracing *tracestate.State) (dst.Node, bool)
- func UnitTest(t *testing.T, code string) []*decorator.Package
- type FactDiscoveryFunction
- type InstrumentationManager
- func (m *InstrumentationManager) AddImport(path string)
- func (m *InstrumentationManager) AddRequiredModules() error
- func (m *InstrumentationManager) AgentVariableName() string
- func (m *InstrumentationManager) AppName() string
- func (m *InstrumentationManager) CreateDiffFile() error
- func (m *InstrumentationManager) DebugTransactionCache()
- func (m *InstrumentationManager) ErrorCache() *errorcache.ErrorCache
- func (m *InstrumentationManager) Facts() *facts.Keeper
- func (m *InstrumentationManager) GetDecoratorPackage() *decorator.Package
- func (m *InstrumentationManager) InstrumentApplication() error
- func (m *InstrumentationManager) IsFunctionTraced(functionName string) bool
- func (m *InstrumentationManager) LoadDependencyScans(scans ...FactDiscoveryFunction)
- func (m *InstrumentationManager) LoadPreInstrumentationTracingFunctions(functions ...PreInstrumentationTracingFunction)
- func (m *InstrumentationManager) LoadStatefulTracingFunctions(functions ...StatefulTracingFunction)
- func (m *InstrumentationManager) LoadStatelessTracingFunctions(functions ...StatelessTracingFunction)
- func (m *InstrumentationManager) ResolveUnitTests() error
- func (m *InstrumentationManager) ScanApplication() error
- func (m *InstrumentationManager) SetAgentVariableName(name string)
- func (m *InstrumentationManager) SetCurrentPackage(pkg string)
- func (m *InstrumentationManager) SetFacts(f facts.Keeper)
- func (m *InstrumentationManager) SetPackageState(pkgID string, state *PackageState)
- func (m *InstrumentationManager) SetSetupFunc(fn *dst.FuncDecl)
- func (m *InstrumentationManager) SetupFunc() *dst.FuncDecl
- func (m *InstrumentationManager) TracePackageCalls() error
- func (m *InstrumentationManager) TransactionCache() *transactioncache.TransactionCache
- func (m *InstrumentationManager) WriteDiff(onProgress func(string)) error
- type PackageState
- type PreInstrumentationTracingFunction
- type StatefulTracingFunction
- type StatelessTracingFunction
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CleanTestApp ¶ added in v1.0.0
CleanTestApp removes the test app directory.
func ConfigureTestInstrumentationManager ¶ added in v1.0.0
func ConfigureTestInstrumentationManager(manager *InstrumentationManager) error
func CreateTestApp ¶ added in v1.0.0
func CreateTestApp(t *testing.T, testAppDir, fileName, contents string) ([]*decorator.Package, error)
CreateTestApp creates a test app in the given directory with the given file name and contents. Codegen is expensive, so this will be skipped in short mode.
func DetectEchoInstrumentation ¶ added in v1.1.0
func DetectEchoInstrumentation(manager *InstrumentationManager, c *dstutil.Cursor)
DetectEchoInstrumentation analyzes the AST to identify existing Echo v4 instrumentation. It detects functions that already have nrecho.FromContext() calls and marks them as traced to prevent duplicate instrumentation.
func DetectEchoV3Instrumentation ¶ added in v1.1.0
func DetectEchoV3Instrumentation(manager *InstrumentationManager, c *dstutil.Cursor)
DetectEchoV3Instrumentation analyzes the AST to identify existing Echo v3 instrumentation. It detects functions that already have nrecho.FromContext() calls and marks them as traced to prevent duplicate instrumentation.
func DetectErrors ¶ added in v0.8.0
func DetectErrors(manager *InstrumentationManager, c *dstutil.Cursor)
func DetectGinInstrumentation ¶ added in v1.0.0
func DetectGinInstrumentation(manager *InstrumentationManager, c *dstutil.Cursor)
DetectGinInstrumentation analyzes the AST to identify existing Gin instrumentation. It detects functions that already have nrgin.Transaction() calls and marks them as traced to prevent duplicate instrumentation.
func DetectTransactions ¶ added in v0.7.0
func DetectTransactions(manager *InstrumentationManager, c *dstutil.Cursor)
DetectTransactions analyzes the AST to identify and track transactions within function declarations. It updates the transaction cache with function declarations and expressions related to transactions. If a function already has transactions, it marks the function as traced to prevent duplicate instrumentation.
func NoticeError ¶
func NoticeError(manager *InstrumentationManager, stmt dst.Stmt, c *dstutil.Cursor, tracing *tracestate.State, functionCallWasTraced bool) bool
StatefulTracingFunction NoticeError will check for the presence of an error.Error variable in the body at the index in bodyIndex. If it finds that an error is returned, it will add a line after the assignment statement to capture an error with a newrelic transaction. All transactions are assumed to be named "txn"
func PanicRecovery ¶ added in v1.0.0
PanicRecovery recovers from panics in tests and reports them with stack traces.
func Pseudo_uuid ¶ added in v1.0.0
func RunStatefulTracingFunction ¶ added in v1.0.0
func RunStatefulTracingFunction(t *testing.T, code string, stmtFunc StatefulTracingFunction, downstream bool) string
RunStatefulTracingFunction runs a stateful tracing function against test code.
func RunStatelessTracingFunction ¶ added in v1.0.0
func RunStatelessTracingFunction(t *testing.T, code string, tracingFunc StatelessTracingFunction, statefulTracingFuncs ...StatefulTracingFunction) string
RunStatelessTracingFunction runs a stateless tracing function against test code.
func TraceFunction ¶
func TraceFunction(manager *InstrumentationManager, node dst.Node, tracing *tracestate.State) (dst.Node, bool)
TraceFunction adds tracing to a function. This includes error capture, and passing agent metadata to relevant functions and services. Traces all called functions inside the current package as well. This function returns a FuncDecl object pointer that contains the potentially modified version of the FuncDecl object, fn, passed. If the bool field is true, then the function was modified, and requires a transaction most likely.
This function can accept a FuncDecl or FuncLit object for the node only.
Types ¶
type FactDiscoveryFunction ¶
FactDiscoveryFunction identify a "Fact" about a code pattern, which can be referenced later to identify patterns that are essential for instrumentation. This function is executed on all nodes in the syntax tree of every function declared in an application. Facts are deterministic labels assigned to specific patterns. When a FactDiscoveryFunction identifies a fact in a node of the abstract syntax tree (AST), it should return a fact `Entry“ for the manager to cache for future use and a boolean indicating if the fact was found.
These functions are best used when a piece of information must be known about the application in order for some tracing functions to work, and we can not determine that information from the scope those functions have access to.
type InstrumentationManager ¶
type InstrumentationManager struct {
// contains filtered or unexported fields
}
InstrumentationManager maintains state relevant to tracing across all files, packages and functions.
func NewInstrumentationManager ¶
func NewInstrumentationManager(pkgs []*decorator.Package, appName, agentVariableName, diffFile, userAppPath string) *InstrumentationManager
NewInstrumentationManager initializes an InstrumentationManager cache for a given package.
func TestInstrumentationManager ¶ added in v1.0.0
func TestInstrumentationManager(t *testing.T, code, testAppDir string) *InstrumentationManager
func (*InstrumentationManager) AddImport ¶ added in v1.0.0
func (m *InstrumentationManager) AddImport(path string)
AddImport adds an import path to the current package (exported for integrations)
func (*InstrumentationManager) AddRequiredModules ¶
func (m *InstrumentationManager) AddRequiredModules() error
func (*InstrumentationManager) AgentVariableName ¶ added in v1.0.0
func (m *InstrumentationManager) AgentVariableName() string
AgentVariableName returns the New Relic agent variable name (exported for integrations)
func (*InstrumentationManager) AppName ¶ added in v1.0.0
func (m *InstrumentationManager) AppName() string
AppName returns the application name (exported for integrations)
func (*InstrumentationManager) CreateDiffFile ¶
func (m *InstrumentationManager) CreateDiffFile() error
func (*InstrumentationManager) DebugTransactionCache ¶ added in v0.7.0
func (m *InstrumentationManager) DebugTransactionCache()
func (*InstrumentationManager) ErrorCache ¶ added in v1.0.0
func (m *InstrumentationManager) ErrorCache() *errorcache.ErrorCache
ErrorCache returns the error cache (exported for integrations)
func (*InstrumentationManager) Facts ¶ added in v1.0.0
func (m *InstrumentationManager) Facts() *facts.Keeper
Facts returns the facts keeper (exported for integrations)
func (*InstrumentationManager) GetDecoratorPackage ¶ added in v1.0.0
func (m *InstrumentationManager) GetDecoratorPackage() *decorator.Package
GetDecoratorPackage returns the decorator package for the current package (exported for integrations)
func (*InstrumentationManager) InstrumentApplication ¶
func (m *InstrumentationManager) InstrumentApplication() error
InstrumentApplication applies instrumentation in place to the dst files stored in the InstrumentationManager. This will not generate any changes to the actual source code, just the abstract syntax tree generated from it. Note: only pass tracing functions to this method for testing, or if you sincerely know what you are doing.
func (*InstrumentationManager) IsFunctionTraced ¶ added in v1.0.0
func (m *InstrumentationManager) IsFunctionTraced(functionName string) bool
IsFunctionTraced checks if a function has been marked as already traced in the current package
func (*InstrumentationManager) LoadDependencyScans ¶ added in v1.0.0
func (m *InstrumentationManager) LoadDependencyScans(scans ...FactDiscoveryFunction)
LoadDependencyScans registers fact discovery functions (exported for cmd)
func (*InstrumentationManager) LoadPreInstrumentationTracingFunctions ¶ added in v1.0.0
func (m *InstrumentationManager) LoadPreInstrumentationTracingFunctions(functions ...PreInstrumentationTracingFunction)
LoadPreInstrumentationTracingFunctions registers pre-instrumentation tracing functions (exported for cmd)
func (*InstrumentationManager) LoadStatefulTracingFunctions ¶ added in v1.0.0
func (m *InstrumentationManager) LoadStatefulTracingFunctions(functions ...StatefulTracingFunction)
LoadStatefulTracingFunctions registers stateful tracing functions (exported for cmd)
func (*InstrumentationManager) LoadStatelessTracingFunctions ¶ added in v1.0.0
func (m *InstrumentationManager) LoadStatelessTracingFunctions(functions ...StatelessTracingFunction)
LoadStatelessTracingFunctions registers stateless tracing functions (exported for cmd)
func (*InstrumentationManager) ResolveUnitTests ¶
func (m *InstrumentationManager) ResolveUnitTests() error
func (*InstrumentationManager) ScanApplication ¶ added in v0.7.0
func (m *InstrumentationManager) ScanApplication() error
ScanApplication scans the existing Go application without adding instrumentation to the source code. This will not generate any changes to the actual source code, just the abstract syntax tree generated from it.
func (*InstrumentationManager) SetAgentVariableName ¶ added in v1.0.0
func (m *InstrumentationManager) SetAgentVariableName(name string)
SetAgentVariableName sets the New Relic agent variable name (exported for integrations)
func (*InstrumentationManager) SetCurrentPackage ¶ added in v1.0.0
func (m *InstrumentationManager) SetCurrentPackage(pkg string)
SetCurrentPackage sets the current package (for tests only)
func (*InstrumentationManager) SetFacts ¶ added in v1.0.0
func (m *InstrumentationManager) SetFacts(f facts.Keeper)
SetFacts sets the facts keeper (for tests only)
func (*InstrumentationManager) SetPackageState ¶ added in v1.0.0
func (m *InstrumentationManager) SetPackageState(pkgID string, state *PackageState)
SetPackageState sets package state for a specific package ID (for tests only)
func (*InstrumentationManager) SetSetupFunc ¶ added in v1.0.0
func (m *InstrumentationManager) SetSetupFunc(fn *dst.FuncDecl)
SetSetupFunc sets the setup function declaration (exported for integrations)
func (*InstrumentationManager) SetupFunc ¶ added in v1.0.0
func (m *InstrumentationManager) SetupFunc() *dst.FuncDecl
SetupFunc returns the setup function declaration (exported for integrations)
func (*InstrumentationManager) TracePackageCalls ¶ added in v0.7.0
func (m *InstrumentationManager) TracePackageCalls() error
func (*InstrumentationManager) TransactionCache ¶ added in v1.0.0
func (m *InstrumentationManager) TransactionCache() *transactioncache.TransactionCache
TransactionCache returns the transaction cache (exported for integrations)
func (*InstrumentationManager) WriteDiff ¶
func (m *InstrumentationManager) WriteDiff(onProgress func(string)) error
WriteDiff writes out the changes made to a file to the diff file for this package. onProgress is a callback function that is invoked before writing each file diff. This allows the caller (e.g., the CLI UI) to receive granular progress updates containing the name of the file currently being processed.
type PackageState ¶ added in v1.0.0
type PackageState struct {
Pkg *decorator.Package
TracedFuncs map[string]*tracedFunctionDecl
ImportsAdded map[string]bool
}
PackageState holds state for a single package (exported for test construction)
type PreInstrumentationTracingFunction ¶ added in v0.7.0
type PreInstrumentationTracingFunction func(manager *InstrumentationManager, c *dstutil.Cursor)
PreInstrumentationTracingFunction defines a function that is executed before any instrumentation is applied to a code block. These functions are executed on every node in the DST tree of every function declared in an application.
type StatefulTracingFunction ¶
type StatefulTracingFunction func(manager *InstrumentationManager, stmt dst.Stmt, c *dstutil.Cursor, tracing *tracestate.State) bool
StatefulTracingFunction defines a function that requires knowledge of the state of New Relic tracing in the current scope of the application in order to apply its changes. That state is stored in the `tracestate.State` object. `StatefulTracingFunctions` are executed against every line of code in the body of a function being traced, as well as every line of code in functions that are declard in this application and called by the function being traced.
The `stmt` is the line of code that is currently being analyzed in the body of a function being traced. This should always be the same node as the current node in the `dstutil.Cursor`. The cursor is provided to allow for easy modifications to the AST tree. The `tracing` manages the current state of New Relic tracing in the application, and has a number of methods that can be used to easily access or apply tracing to the current code.
If the `stmt` was modified, it should return true, otherwise false.
type StatelessTracingFunction ¶
type StatelessTracingFunction func(manager *InstrumentationManager, c *dstutil.Cursor)
StatelessTracingFunction are a powerful tool for identifying and modifying specific sections of code. These functions operate independently, without needing information about the current scope of the code they analyze, the Go agent application, Go agent transactions, or any prior modifications to the code. They are particularly effective in detecting code segments suitable for middleware injection or initiating tracing when middleware is already present.
These functions are ideal for scenarios where a consistent operation can be applied to a specific code pattern. Stateless Tracing Functions are loaded into the manager during initialization and are executed during the second traversal of the abstract syntax tree (AST).
These functions are passed the current node, and a cursor to the current node. These functions are invoked on every node in the DST tree.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
facts provides a way to represent determisitic facts about the code in a simple key value store.
|
facts provides a way to represent determisitic facts about the code in a simple key value store. |
|
tracestate is a package that is used to keep track of the state of the tracing process in the scope of a current function.
|
tracestate is a package that is used to keep track of the state of the tracing process in the scope of a current function. |
|
traceobject
traceobject defines an interface for objects that can contain a New Relic transaction, and how to interact with them.
|
traceobject defines an interface for objects that can contain a New Relic transaction, and how to interact with them. |
