README.md

Protocol Documentation

Table of Contents

• collector.proto

  • Aws

  • Azure

  • HostID

  • K8s

  • MessageRequest

  • MessageResult

  • OboeSetting

  • OboeSetting.ArgumentsEntry

  • PingRequest

  • SettingsRequest

  • SettingsResult

  • EncodingType

  • HostType

  • OboeSettingType

  • ResultCode

  • TraceCollector

• Scalar Value Types

Top

collector.proto

This file defines the RPC between APM libraries and the collector

Aws

Represents AWS metadata from Instance Metadata Service IMDS

Field	Type	Label	Description
cloudProvider	string		always aws
cloudPlatform	string		always aws_ec2
cloudAccountId	string		accountId in IMDS metadata
cloudRegion	string		region in IMDS metadata
cloudAvailabilityZone	string		availabilityZone in IMDS metadata
hostId	string		instanceId in IMDS metadata
hostImageId	string		imageId in IMDS metadata
hostName	string		hostname from either gethostname() in Linux or gethostname() in Windows
hostType	string		instanceType in IMDS metadata

Azure

Represents Azure metadata from Instance Metadata Service IMDS

Field	Type	Label	Description
cloudProvider	string		always azure
cloudPlatform	string		always azure_vm
cloudRegion	string		location in IMDS metadata
cloudAccountId	string		subscriptionId in IMDS metadata
hostId	string		vmId in IMDS metadata
hostName	string		name in IMDS metadata
azureVmName	string		name in IMDS metadata
azureVmSize	string		vmSize in IMDS metadata
azureVmScaleSetName	string		vmScaleSetName in IMDS metadata
azureResourceGroupName	string		resourceGroupName in IMDS metadata

HostID

Represents the host metadata needed to infer entity and make correlations from trace telemetry.

Field	Type	Label	Description
hostname	string		hostname from either gethostname() in Linux or gethostname() in Windows. Java agent will not refresh hostname for now to avoid spawning excessive processes.
ip_addresses	string	repeated	obsolete
uuid	string		[swo only] A random (version 4) UUID generated on application instance startup, analogous to the OTel Resource attribute service.instance.id, e.g. 51fcbc02-670e-454f-84d1-124a500a2646, f620e874-ff3d-4f33-825d-cc4b12b2d005
pid	int32		process id from either getpid() or GetCurrentProcessId()
ec2InstanceID	string		instanceId in AWS EC2 IMDS metadata
ec2AvailabilityZone	string		availabilityZone in AWS EC2 IMDS metadata
dockerContainerID	string		container id from /proc/self/cgroup for cgroups v1
macAddresses	string	repeated	mac addresses for physical interfaces, skipping point-to-point and interfaces w/o IP address from either getifaddrs(...) or GetAdaptersAddresses(...)
herokuDynoID	string		heroku dyno id from environment variable DYNO
azAppServiceInstanceID	string		Azure App Service WEBSITE_INSTANCE_ID which is the unique ID of the current VM instance
hostType	HostType		host type struct
uamsClientID	string		[swo only] uamsclientid exposed to the APM library for Service-to-Host correlation. It is read from /opt/solarwinds/uamsclient/var/uamsclientid or C:\ProgramData\SolarWinds\UAMSClient\uamsclientid. Windows path may be different depending on the setup. If not found, it is retrieved from http://127.0.0.1:2113/info/uamsclient uamsclient_id property
awsMetadata	Aws		[swo only] aws ec2 metadata from IMDS
azureMetadata	Azure		[swo only] azure metadata from IMDS
k8sMetadata	K8s		[swo only] k8s metadata

K8s

Represents k8s metadata

Field	Type	Label	Description
namespace	string		equivalent to k8s.namespace.name. The content from /run/secrets/kubernetes.io/serviceaccount/namespace
podName	string		equivalent to k8s.pod.name. hostname from gethostname() function call
podUid	string		equivalent to k8s.pod.uid. Parsed from /proc/self/mountinfo using best effort

MessageRequest

Represents the message request

Field	Type	Label	Description
api_key	string		the Service Key provided by the customer to authenticate and identify the tenant and service the message is destined for. It is a string composed of two parts, an API token and a descriptive service name, separated by a colon :. Example: qwertyuiop1234567:my_cool_service.
messages	bytes	repeated	bson messages
encoding	EncodingType		always EncodingType::BSON
identity	HostID		host id

MessageResult

Represents the message results

Field	Type	Label	Description
result	ResultCode		result code from the collector
arg	string		obsolete
warning	string		user-facing warning message. The APM library attempts to squelch repeated warnings, so care should be taken to ensure that warning messages are consistent across all RPCs.

OboeSetting

Represents oboe setting message

Field	Type	Label	Description
type	OboeSettingType		Deprecated. oboe setting type struct, always DEFAULT_SAMPLE_RATE
flags	bytes		flags where { OK=0x0, INVALID=0x1, OVERRIDE=0x2, SAMPLE_START=0x4, SAMPLE_THROUGH=0x8, SAMPLE_THROUGH_ALWAYS=0x10, TRIGGERED_TRACE=0x20 }. e.g. 54 means OK or OVERRIDE or SAMPLE_START or SAMPLE_THROUGH_ALWAYS or TRIGGERED_TRACE
timestamp	int64		Epoch timestamp
value	int64		Sampling rate, 1000000 means 100%
layer	bytes		Deprecated. layer name, not set since type is always DEFAULT_SAMPLE_RATE
arguments	OboeSetting.ArgumentsEntry	repeated	key-value pairs. Keys can be [BucketCapacity, BucketRate, TriggerRelaxedBucketCapacity, TriggerRelaxedBucketRate, TriggerStrictBucketCapacity, TriggerStrictBucketRate, SignatureKey]
ttl	int64		time to live for this setting struct, in seconds

OboeSetting.ArgumentsEntry

Field	Type	Label	Description
key	string
value	bytes

PingRequest

Represents the ping request

Field	Type	Label	Description
api_key	string		the Service Key provided by the customer to authenticate and identify the tenant and service the message is destined for. It is a string composed of two parts, an API token and a descriptive service name, separated by a colon :. Example: qwertyuiop1234567:my_cool_service.

SettingsRequest

Represents the settings request

Field	Type	Label	Description
api_key	string		the Service Key provided by the customer to authenticate and identify the tenant and service the message is destined for. It is a string composed of two parts, an API token and a descriptive service name, separated by a colon :. Example: qwertyuiop1234567:my_cool_service.
identity	HostID		host id, only the hostname field needs to be set, all the other fields should be left empty.
clientVersion	string		always 2

SettingsResult

Represents the settings result

Field	Type	Label	Description
result	ResultCode		result code from the collector
arg	string		obsolete
settings	OboeSetting	repeated	sampling settings
warning	string		user-facing warning message. The APM library attempts to squelch repeated warnings, so care should be taken to ensure that warning messages are consistent across all RPCs.

EncodingType

Represents the encoding type of messages

Name	Number	Description
BSON	0	binary JSON
PROTOBUF	1	obsolete

HostType

Represents the host type the APM library is running in.

Name	Number	Description
PERSISTENT	0	persistent host type
AWS_LAMBDA	1	[ao-only] AWS Lambda function

OboeSettingType

Represents oboe setting type

Name	Number	Description
DEFAULT_SAMPLE_RATE	0	DEFAULT_SAMPLE_RATE
LAYER_SAMPLE_RATE	1	obsolete
LAYER_APP_SAMPLE_RATE	2	obsolete
LAYER_HTTPHOST_SAMPLE_RATE	3	obsolete
CONFIG_STRING	4	obsolete
CONFIG_INT	5	obsolete

ResultCode

Represents the result code from collector

Name	Number	Description
OK	0	means OK
TRY_LATER	1	APM library will retry the request later
INVALID_API_KEY	2	obsolete, removed handling in this PR
LIMIT_EXCEEDED	3	APM library will retry the request later
REDIRECT	4	obsolete, removed handling in this PR

TraceCollector

Represents the trace collector service

Method Name	Request Type	Response Type	Description
postEvents	MessageRequest	MessageResult	post events (traces) to collector.
postMetrics	MessageRequest	MessageResult	post metrics (internal heartbeats, request counters, summary, runtime or custom metrics) to collector
postStatus	MessageRequest	MessageResult	post __Init message to collector. May be used by APM library to validate api_key.
getSettings	SettingsRequest	SettingsResult	get sampling and other settings for this connection. Note the SettingsRequest requirement for HostID fields. May be used by APM library to validate api_key.
ping	PingRequest	MessageResult	ping is used for keep-alive purpose. The APM library is expected to ping the collector if the connection has been idled for 20 seconds (by default). Take note that keep-alive should only be performed if the connection was previously healthy - last API call gave a response

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)