Protocol Documentation

Table of Contents

• deepproto/proto/tracepoint/v1/tracepoint.proto

  • LabelExpression
  • Metric
  • Snapshot
  • Snapshot.VarLookupEntry
  • SnapshotResponse
  • StackFrame
  • TracePointConfig
  • TracePointConfig.ArgsEntry
  • Variable
  • VariableID

  • WatchResult

  • MetricType

  • WatchSource

  • SnapshotService

• Scalar Value Types

Top

deepproto/proto/tracepoint/v1/tracepoint.proto

LabelExpression

LabelExpression describes a label that should be evaluated and the value used as the label

Field	Type	Label	Description
key	string		The label key
static	deepproto.proto.common.v1.AnyValue		The label value
expression	string		The label expression

Metric

Metric describes a metric rule to apply at this point.

Field	Type	Label	Description
name	string		The name of the metric
labelExpressions	LabelExpression	repeated	The metric labels
type	MetricType		The type of metric to generate
expression	string	optional	The result of this expression will become the metric value.
namespace	string	optional	The namespace to set on the metric
help	string	optional	The help statement to attach to the metric
unit	string	optional	The unit associated with this value

Snapshot

Snapshot is the result of a tracepoint being executed.

Field	Type	Label	Description
ID	bytes		The client generated ID for this snapshot
tracepoint	TracePointConfig		The config that was used to generate this snapshot (it could be deleted by the time we look at the data)
var_lookup	Snapshot.VarLookupEntry	repeated	This is a flat list of all the collected variables for this snapshot, to reduce data size we dereference as much as we can
ts_nanos	fixed64		The time in nanos since 1970 when this snapshot was generated
frames	StackFrame	repeated	The active frames at the time the snapshot is generated
watches	WatchResult	repeated	The watches results
attributes	deepproto.proto.common.v1.KeyValue	repeated	The attributes for this snapshot (e.g file_name or line_no)
duration_nanos	uint64		The time in nano seconds it took to collect the data
resource	deepproto.proto.common.v1.KeyValue	repeated	The resource for this client, should match the resource sent with a PollRequest.
log_msg	string	optional	The processed log message if the tracepoint had a log message configured.

Snapshot.VarLookupEntry

Field	Type	Label	Description
key	string
value	Variable

SnapshotResponse

SnapshotResponse this is the response from the server, when it receives a Snapshot

StackFrame

StackFrame is the description of a executing code frame that has been captured by the tracepoint.

Field	Type	Label	Description
file_name	string		This is the full path of the file where the line of code is paused.
method_name	string		This is the method or function name that is being called.
line_number	uint32		This is the line number where the program is paused.
class_name	string	optional	The class name of where the method is defined
is_async	bool	optional	This indicates that the frame is an async frame
column_number	uint32	optional	This is the column number for the line, primarily used in node.
transpiled_file_name	string	optional	The name of the transpiled file. If we have mappings available we can map the file 'something.js' to the original typescript. This will be the transpiled file name e.g. something.js
transpiled_line_number	uint32	optional	The transpiled line number
transpiled_column_number	uint32	optional	The transpiled column number
variables	VariableID	repeated	This is the list of variables (using var ids) that are present at this point in the code.
app_frame	bool	optional	This indicates if the frame is from inside the app, or is from a library
native_frame	bool	optional	This indicates if the frame, from a native library (primarily used in Java)
short_path	string	optional	This is the short path to the file (e.g. /simple-app/main.py instead of /home/ben/repo/app/simple-app/main.py).

TracePointConfig

This is the config of a tracepoint that should be installed by the application agent.

Field	Type	Label	Description
ID	string		The ID of the config
path	string		The path for the file to install in
line_number	uint32		The line number to install on
args	TracePointConfig.ArgsEntry	repeated	Arbitrary key/kay of config values (this can contain conditions, logs, fire counts etc)
watches	string	repeated	Expressions to evaluate at the this point of the code
targeting	deepproto.proto.common.v1.KeyValue	repeated	The targeting config for this tracepoint, used by the server to filter response.
metrics	Metric	repeated	List of metric rules to apply at this point in the code

TracePointConfig.ArgsEntry

Field	Type	Label	Description
key	string
value	string

Variable

Variable is the description of am actual value, that is referenced by a VariableID

Field	Type	Label	Description
type	string		The type/class of the variable (e.g string)
value	string		The value of the variable as a string. All values are converted to string for simplicity. This can also result in the value being truncated if it is a very large string. Collection types should not be to stringed, instead a summary should be given as the value 'HashSet of size: 10'.
hash	string		This should be the object identity, and not the hashcode of the object. Use object hashcode if other info is not available.
children	VariableID	repeated	This is a list of the any variables that this variable references. To reduce duplication we use var_lookup to store and process variables by reference.
truncated	bool	optional	True if the value has been truncated

VariableID

VariableID is used to identify a variable on a stack frame or as a child of another variable.

Field	Type	Label	Description
ID	string		The ID to use to look up in the snapshot 'var_lookup'
name	string		The name of the variable at the point this ID is referenced.
modifiers	string	repeated	The modifiers (private, static etc) at the point this ID is referenced
original_name	string	optional	The unmodified name from the engine, some times a variable is renamed by the compiler, e.g. in python a field called '__someVar' is renamed for runtime to 'Class__someVar'.

WatchResult

WatchResult is the result of a watch expression being executed.

Field	Type	Label	Description
expression	string		the expression executed to collect the data
good_result	VariableID		The VariableID of the variable that represents the result, if the expression completed successfully.
error_result	string		This is to contain the error message generated if the watch expression fails.
from_metric	bool	optional	Is this the result of a metric, or metric tag @Deprecated
source	WatchSource		This is the source of the watch result. e.g. did the watch come from a watch input, a log message or a metric

MetricType

The types of metric to create

Name	Number	Description
COUNTER	0
GAUGE	1
HISTOGRAM	2
SUMMARY	3

WatchSource

WatchSource is the logical source of the watch expression used to generate a result.

Name	Number	Description
WATCH	0	A user attached this as an expression
LOG	1	A watch expression from a log
METRIC	2	A watch expression from a metric value or tag
CAPTURE	3	A watch expression generated from a capture: e.g. thrown, return, duration

SnapshotService

Method Name	Request Type	Response Type	Description
send	Snapshot	SnapshotResponse

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)