Skip to content

Latest commit

 

History

History
349 lines (203 loc) · 16.9 KB

README.md

File metadata and controls

349 lines (203 loc) · 16.9 KB

Protocol Documentation

Table of Contents

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)