From c5aa2815c850a5b286a85b21d82dfe6fa12f43b4 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 22 Aug 2024 21:03:48 -0400 Subject: [PATCH 01/16] add spec about reporting component details --- proto/opamp.proto | 14 +++++ specification.md | 127 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 140 insertions(+), 1 deletion(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index 1e233c4..4933d6f 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -609,10 +609,24 @@ message AgentDescription { // with this Agent. repeated KeyValue non_identifying_attributes = 2; + // Details about the components available in the agent. + ComponentDetails component_details = 3; + // TODO: add ability to specify related entities (such as the Service the Agent is // is responsible/associated with). } +message ComponentDetails { + // Extra key/value pairs that may be used to describe the component. + // The key/value pairs are according to semantic conventions, see: + // https://opentelemetry.io/docs/specs/semconv/ + repeated KeyValue metadata = 1; + + // A map of component ID to sub components details. It can nest as deeply as needed to + // describe the underlying system. + map sub_component_map = 2; +} + enum AgentCapabilities { // The capabilities field is unspecified. AgentCapabilities_Unspecified = 0; diff --git a/specification.md b/specification.md index e86953a..848c041 100644 --- a/specification.md +++ b/specification.md @@ -63,6 +63,13 @@ Status: [Beta] + [AgentDescription Message](#agentdescription-message) - [AgentDescription.identifying_attributes](#agentdescriptionidentifying_attributes) - [AgentDescription.non_identifying_attributes](#agentdescriptionnon_identifying_attributes) + - [AgentDescription.component_details](#agentdescriptioncomponent_details) + + [ComponentDetails Message](#componentdetails-message) + - [ComponentDetails.metadata](#componentdetailsmetadata) + - [ComponentDetails.sub_component_map](#componentdetailssub_component_map) + - [Examples](#examples) + * [OpenTelemetry Collector](#opentelemetry-collector) + * [Fluent Bit](#fluent-bit) + [ComponentHealth Message](#componenthealth-message) - [ComponentHealth.healthy](#componenthealthhealthy) - [ComponentHealth.start_time_unix_nano](#componenthealthstart_time_unix_nano) @@ -163,7 +170,7 @@ Status: [Beta] - [CustomMessage.capability](#custommessagecapability) - [CustomMessage.type](#custommessagetype) - [CustomMessage.data](#custommessagedata) - + [Examples](#examples) + + [Examples](#examples-1) - [Pause/Resume Example](#pauseresume-example) * [Agent Connection](#agent-connection) * [Pause](#pause) @@ -1152,6 +1159,124 @@ The following attributes SHOULD be included: - any user-defined attributes that the end user would like to associate with this Agent. +##### AgentDescription.component_details + +Details about the available components in the agent. + +This field gives a description of what components are available, as well +as extra metadata about the components. + +The structure of ComponentDetails DOES NOT need to be a 1-to-1 match with +the ComponentHealth structure. ComponentHealth generally refers to instances of +components, while ComponentDetails refers to the available types of components. + +This field is not required to be specified. + +#### ComponentDetails Message + +Status: [Beta] + +The ComponentDetails message has the following structure: + +```protobuf +message ComponentDetails { + map sub_component_map = 1; + repeated KeyValue metadata = 2; +} +``` + +##### ComponentDetails.metadata + +Extra key/value pairs that may be used to describe the component. + +The key/value pairs are according to semantic conventions, see +the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) for more information. + +##### ComponentDetails.sub_component_map + +A map of component ID to sub components details. It can nest as deeply as needed to +describe the underlying system. + +##### Examples + +###### OpenTelemetry Collector + +Here is an example of how ComponentDetails could hold information regarding the included +components for a custom build collector: + +```json +{ + "sub_component_data": { + "receivers": { + "sub_component_data": { + "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0": { + "metadata": { + "type": "hostmetrics", + } + } + } + }, + "processors": { + "sub_component_data": { + "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0": { + "metadata": { + "type": "batch", + } + }, + "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0": { + "metadata": { + "type": "transform", + } + }, + } + }, + "exporters": { + "sub_component_data": { + "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0": { + "metadata": { + "type": "nop", + } + } + } + } + } + // ... Component list continues for extensions and collectors ... +} +``` + +###### Fluent Bit + +Here's an example of how Fluent Bit could report what components it has available. + +```json +{ + "sub_component_data": { + "input": { + "sub_component_data": { + "tail": {} + } + }, + "parser": { + "sub_component_data": { + "json": {} + } + }, + "filter": { + "sub_component_data": { + "lua": {}, + "modify": {} + } + }, + "output": { + "sub_component_data": { + "null": {}, + "file": {}, + } + } + } +} +``` + #### ComponentHealth Message Status: [Beta] From 2aec2021ff45707301317a008743bc4d2e9fc448 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Mon, 26 Aug 2024 11:15:41 -0400 Subject: [PATCH 02/16] swap proto in spec to match actual proto --- specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification.md b/specification.md index 848c041..ea7eaeb 100644 --- a/specification.md +++ b/specification.md @@ -1180,8 +1180,8 @@ The ComponentDetails message has the following structure: ```protobuf message ComponentDetails { - map sub_component_map = 1; - repeated KeyValue metadata = 2; + repeated KeyValue metadata = 1; + map sub_component_map = 2; } ``` From 4fbdc8c8320df6f1780c6b2903c92de013631a1e Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Mon, 9 Sep 2024 10:42:18 -0400 Subject: [PATCH 03/16] remove top-level ComponentDetails --- proto/opamp.proto | 2 +- specification.md | 101 ++++++++++++++++++++++------------------------ 2 files changed, 50 insertions(+), 53 deletions(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index 4933d6f..eafee26 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -610,7 +610,7 @@ message AgentDescription { repeated KeyValue non_identifying_attributes = 2; // Details about the components available in the agent. - ComponentDetails component_details = 3; + map component_details = 3; // TODO: add ability to specify related entities (such as the Service the Agent is // is responsible/associated with). diff --git a/specification.md b/specification.md index ea7eaeb..5ca7452 100644 --- a/specification.md +++ b/specification.md @@ -1117,6 +1117,7 @@ The AgentDescription message has the following structure: message AgentDescription { repeated KeyValue identifying_attributes = 1; repeated KeyValue non_identifying_attributes = 2; + map component_details = 3; } ``` @@ -1204,38 +1205,36 @@ describe the underlying system. Here is an example of how ComponentDetails could hold information regarding the included components for a custom build collector: -```json +```jsonc { - "sub_component_data": { - "receivers": { - "sub_component_data": { - "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0": { - "metadata": { - "type": "hostmetrics", - } + "receivers": { + "sub_component_data": { + "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0": { + "metadata": { + "type": "hostmetrics", } } - }, - "processors": { - "sub_component_data": { - "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0": { - "metadata": { - "type": "batch", - } - }, - "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0": { - "metadata": { - "type": "transform", - } - }, - } - }, - "exporters": { - "sub_component_data": { - "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0": { - "metadata": { - "type": "nop", - } + } + }, + "processors": { + "sub_component_data": { + "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0": { + "metadata": { + "type": "batch", + } + }, + "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0": { + "metadata": { + "type": "transform", + } + }, + } + }, + "exporters": { + "sub_component_data": { + "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0": { + "metadata": { + "type": "nop", } } } @@ -1248,30 +1247,28 @@ components for a custom build collector: Here's an example of how Fluent Bit could report what components it has available. -```json +```jsonc { - "sub_component_data": { - "input": { - "sub_component_data": { - "tail": {} - } - }, - "parser": { - "sub_component_data": { - "json": {} - } - }, - "filter": { - "sub_component_data": { - "lua": {}, - "modify": {} - } - }, - "output": { - "sub_component_data": { - "null": {}, - "file": {}, - } + "input": { + "sub_component_data": { + "tail": {} + } + }, + "parser": { + "sub_component_data": { + "json": {} + } + }, + "filter": { + "sub_component_data": { + "lua": {}, + "modify": {} + } + }, + "output": { + "sub_component_data": { + "null": {}, + "file": {}, } } } From 1cfdaef631da9ddca148822dc1a3d4963c9ca32d Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Mon, 9 Sep 2024 10:45:13 -0400 Subject: [PATCH 04/16] apply wording suggestions --- specification.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specification.md b/specification.md index 5ca7452..b77d870 100644 --- a/specification.md +++ b/specification.md @@ -1168,10 +1168,12 @@ This field gives a description of what components are available, as well as extra metadata about the components. The structure of ComponentDetails DOES NOT need to be a 1-to-1 match with -the ComponentHealth structure. ComponentHealth generally refers to instances of -components, while ComponentDetails refers to the available types of components. +the ComponentHealth structure. ComponentHealth generally refers to currently running instances of +components, while ComponentDetails refers to the available types of components, +which may not be necessarily running currently. It is also possible that the same component +type may have more than one running instance. -This field is not required to be specified. +This is an optional field. #### ComponentDetails Message @@ -1203,7 +1205,7 @@ describe the underlying system. ###### OpenTelemetry Collector Here is an example of how ComponentDetails could hold information regarding the included -components for a custom build collector: +components for a custom build of [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector):: ```jsonc { From a800b8f0938e254c6b8b212b8cd52844e13a848d Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Mon, 9 Sep 2024 11:16:08 -0400 Subject: [PATCH 05/16] component_details -> available_components --- proto/opamp.proto | 2 +- specification.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index eafee26..e892339 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -610,7 +610,7 @@ message AgentDescription { repeated KeyValue non_identifying_attributes = 2; // Details about the components available in the agent. - map component_details = 3; + map available_components = 3; // TODO: add ability to specify related entities (such as the Service the Agent is // is responsible/associated with). diff --git a/specification.md b/specification.md index b77d870..f4acd54 100644 --- a/specification.md +++ b/specification.md @@ -63,7 +63,7 @@ Status: [Beta] + [AgentDescription Message](#agentdescription-message) - [AgentDescription.identifying_attributes](#agentdescriptionidentifying_attributes) - [AgentDescription.non_identifying_attributes](#agentdescriptionnon_identifying_attributes) - - [AgentDescription.component_details](#agentdescriptioncomponent_details) + - [AgentDescription.available_components](#agentdescriptionavailable_components) + [ComponentDetails Message](#componentdetails-message) - [ComponentDetails.metadata](#componentdetailsmetadata) - [ComponentDetails.sub_component_map](#componentdetailssub_component_map) @@ -1117,7 +1117,7 @@ The AgentDescription message has the following structure: message AgentDescription { repeated KeyValue identifying_attributes = 1; repeated KeyValue non_identifying_attributes = 2; - map component_details = 3; + map available_components = 3; } ``` @@ -1160,7 +1160,7 @@ The following attributes SHOULD be included: - any user-defined attributes that the end user would like to associate with this Agent. -##### AgentDescription.component_details +##### AgentDescription.available_components Details about the available components in the agent. @@ -1169,8 +1169,8 @@ as extra metadata about the components. The structure of ComponentDetails DOES NOT need to be a 1-to-1 match with the ComponentHealth structure. ComponentHealth generally refers to currently running instances of -components, while ComponentDetails refers to the available types of components, -which may not be necessarily running currently. It is also possible that the same component +components, while ComponentDetails refers to the available types of components, +which may not be necessarily running currently. It is also possible that the same component type may have more than one running instance. This is an optional field. From da590b23c6d40a3183528d63e4a532e7ab98f858 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Fri, 11 Oct 2024 13:20:43 -0400 Subject: [PATCH 06/16] Update proto with new spec --- proto/opamp.proto | 51 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 37 insertions(+), 14 deletions(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index e892339..52818f6 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -91,6 +91,10 @@ message AgentToServer { // A custom message sent from an Agent to the Server. // Status: [Development] CustomMessage custom_message = 13; + + // A message indicating the components that are available for configuration on the agent. + // Status: [Development] + AvailableComponents available_components = 14; } enum AgentToServerFlags { @@ -145,6 +149,33 @@ message CertificateRequest { bytes csr = 1; } +// AvailableComponents contains metadata relating to the components included +// within the agent. +// status: [Development] +message AvailableComponents { + // A map of a unique component ID to details about the component. + // This may be omitted from the message if the server has not + // explicitly requested it be sent by setting the ReportAvailableComponents + // flag in the previous ServerToAgent message. + map components = 1; + + // Agent-calculated hash of the components. + // This hash should be included in every AvailableComponents message. + bytes hash = 2; + } + +message ComponentDetails { + // Extra key/value pairs that may be used to describe the component. + // The key/value pairs are according to semantic conventions, see: + // https://opentelemetry.io/docs/specs/semconv/ + repeated KeyValue metadata = 1; + + // A map of component ID to sub components details. It can nest as deeply as needed to + // describe the underlying system. + map sub_component_map = 2; +} + + message ServerToAgent { // Agent instance uid. MUST match the instance_uid field in AgentToServer message. // Used for multiplexing messages from/to multiple agents using one message stream. @@ -212,6 +243,12 @@ enum ServerToAgentFlags { // AgentToServer.sequence_num values. // The Server asks the Agent to report full status. ServerToAgentFlags_ReportFullState = 0x00000001; + + // ReportAvailableComponents flag can be used by the server if the Agent did + // not include the full AvailableComponents message, but only the hash. + // If this flag is specified, the agent will populate available_components.components + // with a full description of the agent's components. + ServerToAgentFlags_ReportAvailableComponents = 0x00000002; } enum ServerCapabilities { @@ -609,24 +646,10 @@ message AgentDescription { // with this Agent. repeated KeyValue non_identifying_attributes = 2; - // Details about the components available in the agent. - map available_components = 3; - // TODO: add ability to specify related entities (such as the Service the Agent is // is responsible/associated with). } -message ComponentDetails { - // Extra key/value pairs that may be used to describe the component. - // The key/value pairs are according to semantic conventions, see: - // https://opentelemetry.io/docs/specs/semconv/ - repeated KeyValue metadata = 1; - - // A map of component ID to sub components details. It can nest as deeply as needed to - // describe the underlying system. - map sub_component_map = 2; -} - enum AgentCapabilities { // The capabilities field is unspecified. AgentCapabilities_Unspecified = 0; From 96733ae269147231934844a37b3ce07ebe3ac9a5 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Tue, 15 Oct 2024 13:21:37 -0400 Subject: [PATCH 07/16] update spec with new flow for reducing data transfer --- specification.md | 282 +++++++++++++++++++++++++++-------------------- 1 file changed, 165 insertions(+), 117 deletions(-) diff --git a/specification.md b/specification.md index f4acd54..62c3596 100644 --- a/specification.md +++ b/specification.md @@ -511,6 +511,7 @@ message AgentToServer { ConnectionSettingsRequest connection_settings_request = 11; // Status: [Development] CustomCapabilities custom_capabilities = 12; // Status: [Development] CustomMessage custom_message = 13; // Status: [Development] + AvailableComponents available_components = 14; // Status: [Development] } ``` @@ -689,6 +690,14 @@ A custom message sent from an Agent to the Server. See [CustomMessage](#custommessage) message for details. +##### AgentToServer.available_components + +Status: [Development] + +A message listing the components available in the Agent. + +See [AvailableComponents](#availablecomponents) message for details. + #### ServerToAgent Message The body of the WebSocket message or HTTP response body is a binary serialized @@ -1117,7 +1126,6 @@ The AgentDescription message has the following structure: message AgentDescription { repeated KeyValue identifying_attributes = 1; repeated KeyValue non_identifying_attributes = 2; - map available_components = 3; } ``` @@ -1160,122 +1168,6 @@ The following attributes SHOULD be included: - any user-defined attributes that the end user would like to associate with this Agent. -##### AgentDescription.available_components - -Details about the available components in the agent. - -This field gives a description of what components are available, as well -as extra metadata about the components. - -The structure of ComponentDetails DOES NOT need to be a 1-to-1 match with -the ComponentHealth structure. ComponentHealth generally refers to currently running instances of -components, while ComponentDetails refers to the available types of components, -which may not be necessarily running currently. It is also possible that the same component -type may have more than one running instance. - -This is an optional field. - -#### ComponentDetails Message - -Status: [Beta] - -The ComponentDetails message has the following structure: - -```protobuf -message ComponentDetails { - repeated KeyValue metadata = 1; - map sub_component_map = 2; -} -``` - -##### ComponentDetails.metadata - -Extra key/value pairs that may be used to describe the component. - -The key/value pairs are according to semantic conventions, see -the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) for more information. - -##### ComponentDetails.sub_component_map - -A map of component ID to sub components details. It can nest as deeply as needed to -describe the underlying system. - -##### Examples - -###### OpenTelemetry Collector - -Here is an example of how ComponentDetails could hold information regarding the included -components for a custom build of [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector):: - -```jsonc -{ - "receivers": { - "sub_component_data": { - "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0": { - "metadata": { - "type": "hostmetrics", - } - } - } - }, - "processors": { - "sub_component_data": { - "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0": { - "metadata": { - "type": "batch", - } - }, - "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0": { - "metadata": { - "type": "transform", - } - }, - } - }, - "exporters": { - "sub_component_data": { - "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0": { - "metadata": { - "type": "nop", - } - } - } - } - // ... Component list continues for extensions and collectors ... -} -``` - -###### Fluent Bit - -Here's an example of how Fluent Bit could report what components it has available. - -```jsonc -{ - "input": { - "sub_component_data": { - "tail": {} - } - }, - "parser": { - "sub_component_data": { - "json": {} - } - }, - "filter": { - "sub_component_data": { - "lua": {}, - "modify": {} - } - }, - "output": { - "sub_component_data": { - "null": {}, - "file": {}, - } - } -} -``` - #### ComponentHealth Message Status: [Beta] @@ -2976,6 +2868,162 @@ CustomMessage { } ``` +### AvailableComponents Message + +Status: [Development] + +Each Agent may be composed of multiple sub-components. These components may have +their own associated metadata. The AvailableComponents message allows the Agent +to inform the OpAMP server about which components the Agent contains. + +The AvailableComponents message has the following structure: + +```protobuf +message AvailableComponents { + map components = 1; + bytes hash = 2; + } +``` + +#### AvailableComponents.components + +The components field contains a map of a unique ID to a [ComponentsDetails](#componentdetails) message. +This field may be omitted from the message if the OpAMP server has not explicitly +requested it by setting the ReportAvailableComponents flag in the preceding +ServerToAgent message. + +##### Examples + +###### OpenTelemetry Collector + +Here is an example of how ComponentDetails could hold information regarding the included +components for a custom build of [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector): + +```jsonc +{ + "receivers": { + "sub_component_map": { + "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0": { + "metadata": { + "type": "hostmetrics", + } + } + } + }, + "processors": { + "sub_component_map": { + "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0": { + "metadata": { + "type": "batch", + } + }, + "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0": { + "metadata": { + "type": "transform", + } + }, + } + }, + "exporters": { + "sub_component_map": { + "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0": { + "metadata": { + "type": "nop", + } + } + } + } + // ... Component list continues for extensions and collectors ... +} +``` + +###### Fluent Bit + +Here's an example of how Fluent Bit could report what components it has available. + +```jsonc +{ + "input": { + "sub_component_map": { + "tail": {} + } + }, + "parser": { + "sub_component_map": { + "json": {} + } + }, + "filter": { + "sub_component_map": { + "lua": {}, + "modify": {} + } + }, + "output": { + "sub_component_map": { + "null": {}, + "file": {}, + } + } +} +``` + +#### AvailableComponents.hash + +The agent-calculated hash of the components field. The agent MUST include this hash +if it has the ability to report the components it has available. + +#### Initial Handshake + +In order to reduce the amount of data transmitted, the AvailableComponents message +does not initially contain the entire components map. Instead, the AvailableComponents +message will have the agent computed hash set, with an empty map for components. + +The OpAMP server may use this hash to determine whether it remembers the set of +AvailableComponents or not. If the hash is not found on the OpAMP server, the server +may request the full components map is reported by setting the ReportAvailableComponents +flag in the ServerToAgent message. If this flag is specified, then the Agent will +populate the components field with a full description of the available components. + +The server may then optionally persist the components for this hash, so that the +server does not need to request them again on subsequent connects. + +The AvailableComponents message is also subject to [status compression](#agent-status-compression), +and may be omitted if the hash has not changed from its previous value. + +#### ComponentDetails Message + +Status: [Beta] + +The ComponentDetails messaged describes a component of the Agent. + +The structure of ComponentDetails DOES NOT need to be a 1-to-1 match with +the ComponentHealth structure. ComponentHealth generally refers to currently running instances of +components, while ComponentDetails refers to the available types of components, +which may not be necessarily running currently. It is also possible that the same component +type may have more than one running instance. + +The ComponentDetails message has the following structure: + +```protobuf +message ComponentDetails { + repeated KeyValue metadata = 1; + map sub_component_map = 2; +} +``` + +##### ComponentDetails.metadata + +Extra key/value pairs that may be used to describe the component. + +The key/value pairs are SHOULD conform to semantic conventions where applicable, see +the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/) for more information. + +##### ComponentDetails.sub_component_map + +A map of unique component ID to sub component details. It can nest as deeply as needed to +describe the underlying system. + ## Connection Management ### Establishing Connection From d84d87b68a39f60214785a92af0e985dd45fcd02 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Tue, 15 Oct 2024 13:42:19 -0400 Subject: [PATCH 08/16] make all --- specification.md | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/specification.md b/specification.md index 62c3596..7c0e72c 100644 --- a/specification.md +++ b/specification.md @@ -40,6 +40,7 @@ Status: [Beta] - [AgentToServer.connection_settings_request](#agenttoserverconnection_settings_request) - [AgentToServer.custom_capabilities](#agenttoservercustom_capabilities) - [AgentToServer.custom_message](#agenttoservercustom_message) + - [AgentToServer.available_components](#agenttoserveravailable_components) + [ServerToAgent Message](#servertoagent-message) - [ServerToAgent.instance_uid](#servertoagentinstance_uid) - [ServerToAgent.error_response](#servertoagenterror_response) @@ -63,13 +64,6 @@ Status: [Beta] + [AgentDescription Message](#agentdescription-message) - [AgentDescription.identifying_attributes](#agentdescriptionidentifying_attributes) - [AgentDescription.non_identifying_attributes](#agentdescriptionnon_identifying_attributes) - - [AgentDescription.available_components](#agentdescriptionavailable_components) - + [ComponentDetails Message](#componentdetails-message) - - [ComponentDetails.metadata](#componentdetailsmetadata) - - [ComponentDetails.sub_component_map](#componentdetailssub_component_map) - - [Examples](#examples) - * [OpenTelemetry Collector](#opentelemetry-collector) - * [Fluent Bit](#fluent-bit) + [ComponentHealth Message](#componenthealth-message) - [ComponentHealth.healthy](#componenthealthhealthy) - [ComponentHealth.start_time_unix_nano](#componenthealthstart_time_unix_nano) @@ -170,7 +164,7 @@ Status: [Beta] - [CustomMessage.capability](#custommessagecapability) - [CustomMessage.type](#custommessagetype) - [CustomMessage.data](#custommessagedata) - + [Examples](#examples-1) + + [Examples](#examples) - [Pause/Resume Example](#pauseresume-example) * [Agent Connection](#agent-connection) * [Pause](#pause) @@ -179,6 +173,16 @@ Status: [Beta] * [Agent Connection](#agent-connection-1) * [FindServices](#findservices) * [FindServicesResponse](#findservicesresponse) + * [AvailableComponents Message](#availablecomponents-message) + + [AvailableComponents.components](#availablecomponentscomponents) + - [Examples](#examples-1) + * [OpenTelemetry Collector](#opentelemetry-collector) + * [Fluent Bit](#fluent-bit) + + [AvailableComponents.hash](#availablecomponentshash) + + [Initial Handshake](#initial-handshake) + + [ComponentDetails Message](#componentdetails-message) + - [ComponentDetails.metadata](#componentdetailsmetadata) + - [ComponentDetails.sub_component_map](#componentdetailssub_component_map) - [Connection Management](#connection-management) * [Establishing Connection](#establishing-connection) * [Closing Connection](#closing-connection) @@ -696,7 +700,7 @@ Status: [Development] A message listing the components available in the Agent. -See [AvailableComponents](#availablecomponents) message for details. +See [AvailableComponents](#availablecomponents-message) message for details. #### ServerToAgent Message @@ -2887,7 +2891,8 @@ message AvailableComponents { #### AvailableComponents.components -The components field contains a map of a unique ID to a [ComponentsDetails](#componentdetails) message. +The components field contains a map of a unique ID +to a [ComponentsDetails](#componentdetails-message) message. This field may be omitted from the message if the OpAMP server has not explicitly requested it by setting the ReportAvailableComponents flag in the preceding ServerToAgent message. @@ -2971,7 +2976,7 @@ Here's an example of how Fluent Bit could report what components it has availabl #### AvailableComponents.hash The agent-calculated hash of the components field. The agent MUST include this hash -if it has the ability to report the components it has available. +if it has the ability to report the components it has available. #### Initial Handshake @@ -2979,7 +2984,7 @@ In order to reduce the amount of data transmitted, the AvailableComponents messa does not initially contain the entire components map. Instead, the AvailableComponents message will have the agent computed hash set, with an empty map for components. -The OpAMP server may use this hash to determine whether it remembers the set of +The OpAMP server may use this hash to determine whether it remembers the set of AvailableComponents or not. If the hash is not found on the OpAMP server, the server may request the full components map is reported by setting the ReportAvailableComponents flag in the ServerToAgent message. If this flag is specified, then the Agent will From 2556d26ed4c5ca0a329f7d9460deb2b8696722ff Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 24 Oct 2024 14:38:58 -0400 Subject: [PATCH 09/16] tweak wording on behaviour on hash mismatch --- specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification.md b/specification.md index 7c0e72c..3124b71 100644 --- a/specification.md +++ b/specification.md @@ -2986,7 +2986,7 @@ message will have the agent computed hash set, with an empty map for components. The OpAMP server may use this hash to determine whether it remembers the set of AvailableComponents or not. If the hash is not found on the OpAMP server, the server -may request the full components map is reported by setting the ReportAvailableComponents +may request for the full components map to be reported by setting the ReportAvailableComponents flag in the ServerToAgent message. If this flag is specified, then the Agent will populate the components field with a full description of the available components. From 0abd35afe60a1c9ca7aeff0c23edaaa10bfe2e33 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 24 Oct 2024 14:43:55 -0400 Subject: [PATCH 10/16] invert module/typestr for ID --- specification.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification.md b/specification.md index 3124b71..d742149 100644 --- a/specification.md +++ b/specification.md @@ -2908,32 +2908,32 @@ components for a custom build of [OpenTelemetry Collector](https://github.com/op { "receivers": { "sub_component_map": { - "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0": { + "hostmetrics": { "metadata": { - "type": "hostmetrics", + "code.namespace": "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver@v0.107.0", } } } }, "processors": { "sub_component_map": { - "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0": { + "batch": { "metadata": { - "type": "batch", + "code.namespace": "go.opentelemetry.io/collector/processor/batchprocessor@v0.107.0" } }, - "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0": { + "transform": { "metadata": { - "type": "transform", + "code.namespace": "github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor@v0.107.0" } }, } }, "exporters": { "sub_component_map": { - "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0": { + "nop": { "metadata": { - "type": "nop", + "code.namespace": "go.opentelemetry.io/collector/exporter/nopexporter@v0.107.0" } } } From 185c8a20237fca18db4895804294bf12224e09ff Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 24 Oct 2024 14:47:11 -0400 Subject: [PATCH 11/16] add examples in proto for what sem-conv to use --- proto/opamp.proto | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proto/opamp.proto b/proto/opamp.proto index 52818f6..86c77d9 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -168,6 +168,14 @@ message ComponentDetails { // Extra key/value pairs that may be used to describe the component. // The key/value pairs are according to semantic conventions, see: // https://opentelemetry.io/docs/specs/semconv/ + // + // For example, you may use the "code" semantic conventions to + // report the location of the code for a specific component: + // https://opentelemetry.io/docs/specs/semconv/attributes-registry/code/ + // + // Or you may use the "vcs" semantic conventions to report the + // repository the component may be a part of: + // https://opentelemetry.io/docs/specs/semconv/attributes-registry/vcs/ repeated KeyValue metadata = 1; // A map of component ID to sub components details. It can nest as deeply as needed to From 4d3af710dee04b820dd84a706a3c9d12b1c33222 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 24 Oct 2024 15:50:29 -0400 Subject: [PATCH 12/16] call out specifically that the initial AgentToServer message should have the AvailableComponents message --- specification.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification.md b/specification.md index d742149..6e18ea8 100644 --- a/specification.md +++ b/specification.md @@ -2984,6 +2984,9 @@ In order to reduce the amount of data transmitted, the AvailableComponents messa does not initially contain the entire components map. Instead, the AvailableComponents message will have the agent computed hash set, with an empty map for components. +The initial AgentToServer message SHOULD contain the AvailableComponents message +with just the agent computed hash set. + The OpAMP server may use this hash to determine whether it remembers the set of AvailableComponents or not. If the hash is not found on the OpAMP server, the server may request for the full components map to be reported by setting the ReportAvailableComponents From a2ca5a1bf201a5d8b998f7cfa7a753dc6330f8f2 Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 24 Oct 2024 15:59:13 -0400 Subject: [PATCH 13/16] add capability to spec --- proto/opamp.proto | 3 +++ specification.md | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index 86c77d9..3cf78e7 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -708,6 +708,9 @@ enum AgentCapabilities { // know the configured interval and should not make assumptions about it. // Status: [Development] AgentCapabilities_ReportsHeartbeat = 0x00002000; + // The will report AvailableComponents via the AgentToServer.available_components field. + // Status: [Development] + AgentCapabilities_ReportsAvailableComponents = 0x00004000; // Add new capabilities here, continuing with the least significant unused bit. } diff --git a/specification.md b/specification.md index 6e18ea8..e313522 100644 --- a/specification.md +++ b/specification.md @@ -698,7 +698,8 @@ See [CustomMessage](#custommessage) message for details. Status: [Development] -A message listing the components available in the Agent. +A message listing the components available in the Agent. This field SHOULD be +reported if and only if the ReportsAvailableComponents capability is set. See [AvailableComponents](#availablecomponents-message) message for details. From 32a70a510470b2e831280757e4da2da8a83452fd Mon Sep 17 00:00:00 2001 From: Brandon Johnson Date: Thu, 24 Oct 2024 16:05:53 -0400 Subject: [PATCH 14/16] add some details about the components hash --- specification.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification.md b/specification.md index e313522..1eb7fdd 100644 --- a/specification.md +++ b/specification.md @@ -2978,6 +2978,8 @@ Here's an example of how Fluent Bit could report what components it has availabl The agent-calculated hash of the components field. The agent MUST include this hash if it has the ability to report the components it has available. +Its format is determined by the agent. +The hash SHOULD be the same for any agent that has the same set of components. #### Initial Handshake From ed37d5123ad0ade0d5bba10cde35e322ba9de41e Mon Sep 17 00:00:00 2001 From: Andy Keller Date: Wed, 30 Oct 2024 16:25:13 -0400 Subject: [PATCH 15/16] Apply suggestions from code review Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> --- proto/opamp.proto | 2 +- specification.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index 3cf78e7..89696ba 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -708,7 +708,7 @@ enum AgentCapabilities { // know the configured interval and should not make assumptions about it. // Status: [Development] AgentCapabilities_ReportsHeartbeat = 0x00002000; - // The will report AvailableComponents via the AgentToServer.available_components field. + // The agent will report AvailableComponents via the AgentToServer.available_components field. // Status: [Development] AgentCapabilities_ReportsAvailableComponents = 0x00004000; // Add new capabilities here, continuing with the least significant unused bit. diff --git a/specification.md b/specification.md index 1eb7fdd..1c83818 100644 --- a/specification.md +++ b/specification.md @@ -2903,7 +2903,7 @@ ServerToAgent message. ###### OpenTelemetry Collector Here is an example of how ComponentDetails could hold information regarding the included -components for a custom build of [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector): +components for a custom build of the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector): ```jsonc { From 808917457e973c251fd6c968bbb2b9dd38cb9f3d Mon Sep 17 00:00:00 2001 From: Andy Keller Date: Wed, 30 Oct 2024 22:18:04 -0400 Subject: [PATCH 16/16] mark Status: [Development] --- proto/opamp.proto | 7 ++++--- specification.md | 4 +--- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index 89696ba..95d7829 100644 --- a/proto/opamp.proto +++ b/proto/opamp.proto @@ -149,7 +149,7 @@ message CertificateRequest { bytes csr = 1; } -// AvailableComponents contains metadata relating to the components included +// AvailableComponents contains metadata relating to the components included // within the agent. // status: [Development] message AvailableComponents { @@ -172,7 +172,7 @@ message ComponentDetails { // For example, you may use the "code" semantic conventions to // report the location of the code for a specific component: // https://opentelemetry.io/docs/specs/semconv/attributes-registry/code/ - // + // // Or you may use the "vcs" semantic conventions to report the // repository the component may be a part of: // https://opentelemetry.io/docs/specs/semconv/attributes-registry/vcs/ @@ -256,6 +256,7 @@ enum ServerToAgentFlags { // not include the full AvailableComponents message, but only the hash. // If this flag is specified, the agent will populate available_components.components // with a full description of the agent's components. + // Status: [Development] ServerToAgentFlags_ReportAvailableComponents = 0x00000002; } @@ -709,7 +710,7 @@ enum AgentCapabilities { // Status: [Development] AgentCapabilities_ReportsHeartbeat = 0x00002000; // The agent will report AvailableComponents via the AgentToServer.available_components field. - // Status: [Development] + // Status: [Development] AgentCapabilities_ReportsAvailableComponents = 0x00004000; // Add new capabilities here, continuing with the least significant unused bit. } diff --git a/specification.md b/specification.md index 1c83818..5593e73 100644 --- a/specification.md +++ b/specification.md @@ -3004,8 +3004,6 @@ and may be omitted if the hash has not changed from its previous value. #### ComponentDetails Message -Status: [Beta] - The ComponentDetails messaged describes a component of the Agent. The structure of ComponentDetails DOES NOT need to be a 1-to-1 match with @@ -3019,7 +3017,7 @@ The ComponentDetails message has the following structure: ```protobuf message ComponentDetails { repeated KeyValue metadata = 1; - map sub_component_map = 2; + map sub_component_map = 2; } ```