README
¶
Protocol Documentation
Table of Contents
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 | 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 | 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 |
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) |
Directories
Click to show internal directories.
Click to hide internal directories.