From bc9c8ba8f3281bf924449bd54a13742c683f5639 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Wed, 25 May 2022 20:02:37 -0400 Subject: [PATCH] Move messages in StatusReport to AgentToServer message (#85) - StatusReport was an unnecessary message, remaining from the time when we had DataToAgent which had a oneof field, and it was impossible to set multiple fields that together form the status. All its fields are moved to AgentToServer message now and can be set directly there (there is no longer a oneof limitation so now this is possible to do). - Moved Agent to Server State Synchronization under Status Reporting where it is more relevant and renamed to Agent Status Compression. Resolves https://github.com/open-telemetry/opamp-spec/issues/84 --- specification.md | 380 +++++++++++++++++++++++------------------------ 1 file changed, 183 insertions(+), 197 deletions(-) diff --git a/specification.md b/specification.md index 83e264c..56e389f 100644 --- a/specification.md +++ b/specification.md @@ -22,19 +22,21 @@ Note 2: this document requires a simplification pass to reduce the scope, size a * [Plain HTTP Transport](#plain-http-transport) * [AgentToServer Message](#agenttoserver-message) - [instance_uid](#instance_uid) - - [status_report](#status_report) + - [agent_description](#agent_description) + - [capabilities](#capabilities) + - [effective_config](#effective_config) + - [remote_config_status](#remote_config_status) - [package_statuses](#package_statuses) - [agent_disconnect](#agent_disconnect) - [flags](#flags) * [ServerToAgent Message](#servertoagent-message) - * [Agent to Server State Synchronization](#agent-to-server-state-synchronization) - [instance_uid](#instance_uid-1) - [error_response](#error_response) - [remote_config](#remote_config) - [connection_settings](#connection_settings) - [packages_available](#packages_available) - [flags](#flags-1) - - [capabilities](#capabilities) + - [capabilities](#capabilities-1) - [agent_identification](#agent_identification) - [command](#command) * [ServerErrorResponse Message](#servererrorresponse-message) @@ -44,11 +46,7 @@ Note 2: this document requires a simplification pass to reduce the scope, size a * [ServerToAgentCommand Message](#servertoagentcommand-message) - [Operation](#operation) * [Status Reporting](#status-reporting) - + [StatusReport Message](#statusreport-message) - - [agent_description](#agent_description) - - [effective_config](#effective_config) - - [remote_config_status](#remote_config_status) - - [capabilities](#capabilities-1) + + [Agent Status Compression](#agent-status-compression) + [AgentDescription Message](#agentdescription-message) - [hash](#hash) - [identifying_attributes](#identifying_attributes) @@ -287,8 +285,8 @@ particular capability in the corresponding section of this specification. The sequence is normally started by an initiating message triggered by some external event. For example after the connection is established the Agent sends -a StatusReport message. In this case the "connection established" is the -triggering event and the StatusReport is the initiating message. +a AgentToServer message. In this case the "connection established" is the +triggering event and the AgentToServer is the initiating message. Both the Agent and the Server may begin a sequence by sending an initiating message. @@ -305,8 +303,8 @@ some other message. Unlike other protocols in OpAMP there is no strict separation between "request" and "response" messages types. The role of the message depends on how the sequence is triggered. -For example the StatusReport message may be the initiating message sent by the -Agent when the Agent connects to the Server for the first time. The StatusReport +For example the AgentToServer message may be the initiating message sent by the +Agent when the Agent connects to the Server for the first time. The AgentToServer message may also be sent by the Agent in response to the Server making a remote configuration offer to the Agent and Agent reporting that it accepted the configuration. @@ -376,16 +374,18 @@ document are specified in ```protobuf message AgentToServer { string instance_uid = 1; - StatusReport status_report = 2; - PackageStatuses package_statuses = 3; - AgentDisconnect agent_disconnect = 4; - AgentToServerFlags flags = 5; + AgentDescription agent_description = 2; + AgentCapabilities capabilities = 3; + EffectiveConfig effective_config = 4; + RemoteConfigStatus remote_config_status = 5; + PackageStatuses package_statuses = 6; + AgentDisconnect agent_disconnect = 7; + AgentToServerFlags flags = 8; } ``` -One or more of the fields (status_report, package_statuses, -agent_disconnect) MUST be set. The Server should process each field as it is -described in the corresponding [Operation](#operation) section. +The Server should process each field as it is described in the corresponding +[Operation](#operation) section. #### instance_uid @@ -399,18 +399,81 @@ lifetime of the Agent process. The recommended format for the instance_uid is In case the Agent wants to use an identifier generated by the Server, the field SHOULD be set with a temporary value and RequestInstanceUid flag MUST be set. -#### status_report +#### agent_description + +Data that describes the Agent, its type, where it runs, etc. See +[AgentDescription](#agentdescription-message) message for details. +This field SHOULD be unset if this information is unchanged since the last +AgentToServer message. + +#### capabilities + +Bitmask of flags defined by AgentCapabilities enum. +All bits that are not defined in AgentCapabilities enum MUST be set to 0 by +the Agent. This allows extending the protocol and the AgentCapabilities enum +in the future such that old Agents automatically report that they don't +support the new capability. +This field MUST be always set. + +```protobuf +enum AgentCapabilities { + // The capabilities field is unspecified. + UnspecifiedAgentCapability = 0; + // The Agent can report status. This bit MUST be set, since all Agents MUST + // report status. + ReportsStatus = 0x00000001; + // The Agent can accept remote configuration from the Server. + AcceptsRemoteConfig = 0x00000002; + // The Agent will report EffectiveConfig in AgentToServer. + ReportsEffectiveConfig = 0x00000004; + // The Agent can accept package offers. + AcceptsPackages = 0x00000008; + // The Agent can report package status. + ReportsPackageStatuses = 0x00000010; + // The Agent can report own trace to the destination specified by + // the Server via ConnectionSettingsOffers.own_traces field. + ReportsOwnTraces = 0x00000020; + // The Agent can report own metrics to the destination specified by + // the Server via ConnectionSettingsOffers.own_metrics field. + ReportsOwnMetrics = 0x00000040; + // The Agent can report own logs to the destination specified by + // the Server via ConnectionSettingsOffers.own_logs field. + ReportsOwnLogs = 0x00000080; + // The can accept connections settings for OpAMP via + // ConnectionSettingsOffers.opamp field. + AcceptsOpAMPConnectionSettings = 0x00000100; + // The can accept connections settings for other destinations via + // ConnectionSettingsOffers.other_connections field. + AcceptsOtherConnectionSettings = 0x00000200; + // The Agent can accept restart requests. + AcceptsRestartCommand = 0x00000400; + + // Add new capabilities here, continuing with the least significant unused bit. +} +``` -The status of the Agent. MUST be set in the first AgentToServer message that the -Agent sends after connecting. This field SHOULD be unset if this information is -unchanged since the last AgentToServer message for this Agent was sent in the -stream. +#### effective_config + +The current effective configuration of the Agent. The effective configuration is +the one that is currently used by the Agent. The effective configuration may be +different from the remote configuration received from the Server earlier, e.g. +because the Agent uses a local configuration instead (or in addition). See +[EffectiveConfig](#effectiveconfig-message) message for details. +This field SHOULD be unset if this information is unchanged since the last +AgentToServer message. + +#### remote_config_status + +The status of the remote config that was previously received from the Server. +See [RemoteConfigStatus](#remoteconfigstatus-message) message for details. +This field SHOULD be unset if this information is unchanged since the last +AgentToServer message. #### package_statuses -The list of the Agent packages, including package statuses. This field SHOULD be -unset if this information is unchanged since the last AgentToServer message for -this Agent was sent in the stream. +The list of the Agent packages, including package statuses. +This field SHOULD be unset if this information is unchanged since the last +AgentToServer message. #### agent_disconnect @@ -486,55 +549,6 @@ message ServerToAgent { } ``` -## Agent to Server State Synchronization - -The Agent notifies the Server about Agent's state by sending AgentToServer messages. -The state for example includes the Agent description, its effective configuration, -the status of the remote configuration it received from the Server and the status -of the packages. The Server tracks the state of the Agent using the data -specified in the messages referenced from AgentToServer message. - -The Agent MAY compress some of these messages by omitting the data that has not changed -since that particular data was reported last time. The following messages can be subject -to such compression: -[AgentDescription](#agentdescription-message), -[EffectiveConfig](#effectiveconfig-message), -[RemoteConfigStatus](#remoteconfigstatus-message) and -[PackageStatuses](#packagestatuses-message). - -The compression is done by omitting all fields in the message, except -the hash field which MUST always be present (see below for how the hash field is used). -If any of the fields in the message has changed then the compression cannot be used -and all fields MUST be present. - -If all AgentToServer messages are reliably delivered to the Server and the Server -correctly processes them then such compression is safe and the Server should always -have the correct latest state of the Agent. - -However, it is possible that the Agent and Server lose the synchronization and the Agent -believes the Server has the latest data while in reality the Server doesn't. This is -possible for example if the Server is restarted while the Agent keeps running and sends -AgentToServer messages, which the Server does not receive because it is temporarily down. - -In order to detect this situation and recover from it, every compressible message -contains a hash field. The field is the hash of the content of every other field. -The hash is computed on full, uncompressed message (as if no compression is used) and -then unchanged fields may be omitted from the message. Note that either all fields in the -message must be present or all fields (except hash) must be omitted. - -The Server SHOULD store the received hash value for each message type. When the Server -receives a message of the same type with a hash value that is different from the last -stored hash and with omitted data then the Server knows it has lost the state of this -particular message. - -When this situation is encountered, to recover the lost state the Server MUST request -the Agent to report the omitted data. To make this request the Server MUST send -a ServerToAgent message to the Agent and set the corresponding `Report*` bit in -the [flags](#flags-1) field of [ServerToAgent message](#servertoagent-message). -The flags field contains one `Report*` bit per type of compressible message. - -For the details of the flags field see the [descriptions here](#flags-1). - #### instance_uid The Agent instance identifier. MUST match the instance_uid field previously @@ -579,8 +593,8 @@ Bit flags as defined by Flags bit masks. `Report*` flags can be used by the Server if the Agent did not include the particular portion of the data in the last AgentToServer message (which is an allowed compression approach) but the Server does not have that data, e.g. the Server was -restarted and lost the state (see the details in -[this section](#agent-to-server-state-synchronization)). +restarted and lost the agent status (see the details in +[this section](#agent-status-compression)). ```protobuf @@ -594,17 +608,17 @@ enum Flags { // The Server asks the Agent to report full EffectiveConfig. This bit MUST NOT be // set if the Agent indicated it cannot report effective config by setting - // the ReportsEffectiveConfig bit to 0 in StatusReport.capabilities field. + // the ReportsEffectiveConfig bit to 0 in AgentToServer.capabilities field. ReportEffectiveConfig = 0x00000002; // The Server asks the Agent to report full RemoteConfigStatus. This bit MUST NOT be // set if the Agent indicated it cannot accept remote config by setting - // the AcceptsRemoteConfig bit to 0 in StatusReport.capabilities field. + // the AcceptsRemoteConfig bit to 0 in AgentToServer.capabilities field. ReportRemoteConfigStatus = 0x00000004; // The Server asks the Agent to report full PackageStatuses. This bit MUST NOT be // set if the Agent indicated it cannot report package status by setting - // the ReportsPackageStatuses bit to 0 in StatusReport.capabilities field. + // the ReportsPackageStatuses bit to 0 in AgentToServer.capabilities field. ReportPackageStatuses = 0x00000008; } ``` @@ -628,7 +642,7 @@ enum ServerCapabilities { AcceptsStatus = 0x00000001; // The Server can offer remote configuration to the Agent. OffersRemoteConfig = 0x00000002; - // The Server can accept EffectiveConfig in StatusReport. + // The Server can accept EffectiveConfig in AgentToServer. AcceptsEffectiveConfig = 0x00000004; // The Server can offer Packages. OffersPackages = 0x00000008; @@ -738,19 +752,18 @@ will be ignored. ## Status Reporting - The Agent MUST send a status report: - - * First time immediately after connecting to the Server. The status report MUST be the first message sent by the Agent. -* Subsequently every time the status of the Agent changes. +* Subsequently, every time the status of the Agent changes. -The status report is set as a [status_report](#statusreport-message) field in the -AgentToServer message. +The status report is sent as an [AgentToServer](#agenttoserver-message) message. +The following fields in the message can be set to reflect the corresponding +part of the status: agent_description, capabilities, effective_config, +remote_config_status, package_statuses. -The Server MUST respond to the status report by sending a +The Server MUST respond to the AgentToServer message by sending a [ServerToAgent](#servertoagent-message) message. If the status report processing failed then the @@ -773,18 +786,18 @@ server-side processing is successful): │ WebSocket Connect │ ├──────────────────────────────────────►│ │ │ - │ AgentToServer{StatusReport} │ ┌─────────┐ + │ AgentToServer │ ┌─────────┐ ├──────────────────────────────────────►├──►│ │ │ │ │ Process │ - │ ServerToAgent{} │ │ Status │ + │ ServerToAgent │ │ Status │ │◄──────────────────────────────────────┤◄──┤ │ │ │ └─────────┘ . ... . - │ AgentToServer{StatusReport} │ ┌─────────┐ + │ AgentToServer │ ┌─────────┐ ├──────────────────────────────────────►├──►│ │ │ │ │ Process │ - │ ServerToAgent{} │ │ Status │ + │ ServerToAgent │ │ Status │ │◄──────────────────────────────────────┤◄──┤ │ │ │ └─────────┘ │ │ @@ -803,7 +816,7 @@ So, essentially in such cases the sequence of messages may look like this: ``` Agent Server - │ ServerToAgent{} │ + │ ServerToAgent │ ┌───────┤◄──────────────────────────────────────┤ │ │ │ ▼ │ │ @@ -814,10 +827,10 @@ So, essentially in such cases the sequence of messages may look like this: └───┬────┘ │ │ │ │ │ │Status │ │ - │Changed│ AgentToServer{StatusReport} │ ┌─────────┐ + │Changed│ AgentToServer │ ┌─────────┐ └──────►├──────────────────────────────────────►├──►│ │ │ │ │ Process │ - │ ServerToAgent{} │ │ Status │ + │ ServerToAgent │ │ Status │ │◄──────────────────────────────────────┤◄──┤ │ │ │ └─────────┘ ``` @@ -832,7 +845,7 @@ changed). The sequence diagram in this case look like this: ``` Agent Server - │ ServerToAgent{} │ + │ ServerToAgent │ ┌──────┤◄──────────────────────────────────────┤ │ │ │ ▼ │ │ @@ -856,83 +869,54 @@ Server. TODO: add a section explaining how infinite oscillations between remote config and status reporting are possible if an attribute is reported in the status that can be changed via remote config and how to prevent it. -### StatusReport Message - -StatusReport message has the following structure: - -```protobuf -message StatusReport { - AgentDescription agent_description = 1; - EffectiveConfig effective_config = 2; - RemoteConfigStatus remote_config_status = 3; - AgentCapabilities capabilities = 4; -} -``` - -#### agent_description +### Agent Status Compression -The description of the Agent, its type, where it runs, etc. See -[AgentDescription](#agentdescription-message) message for details. +The Agent notifies the Server about Agent's status by sending AgentToServer messages. +The status for example includes the Agent description, its effective configuration, +the status of the remote configuration it received from the Server and the status +of the packages. The Server tracks the status of the Agent using the data +specified in the messages referenced from AgentToServer message. -#### effective_config +The Agent MAY compress some of these messages by omitting the data that has not changed +since that particular data was reported last time. The following messages can be subject +to such compression: +[AgentDescription](#agentdescription-message), +[EffectiveConfig](#effectiveconfig-message), +[RemoteConfigStatus](#remoteconfigstatus-message) and +[PackageStatuses](#packagestatuses-message). -The current effective configuration of the Agent. The effective configuration is -the one that is currently used by the Agent. The effective configuration may be -different from the remote configuration received from the Server earlier, e.g. -because the Agent uses a local configuration instead (or in addition). See -[EffectiveConfig](#effectiveconfig-message) message for details. +The compression is done by omitting all fields in the message, except +the hash field which MUST always be present (see below for how the hash field is used). +If any of the fields in the message has changed then the compression cannot be used +and all fields MUST be present. -#### remote_config_status +If all AgentToServer messages are reliably delivered to the Server and the Server +correctly processes them then such compression is safe and the Server should always +have the correct latest status of the Agent. -The status of the remote config that was previously received from the Server. -See [RemoteConfigStatus](#remoteconfigstatus-message) message for details. +However, it is possible that the Agent and Server lose the synchronization and the Agent +believes the Server has the latest data while in reality the Server doesn't. This is +possible for example if the Server is restarted while the Agent keeps running and sends +AgentToServer messages, which the Server does not receive because it is temporarily down. -#### capabilities +In order to detect this situation and recover from it, every compressible message +contains a hash field. The field is the hash of the content of every other field. +The hash is computed on full, uncompressed message (as if no compression is used) and +then unchanged fields may be omitted from the message. Note that either all fields in the +message must be present or all fields (except hash) must be omitted. -Bitmask of flags defined by AgentCapabilities enum. All bits that are not -defined in AgentCapabilities enum MUST be set to 0 by the Agent. This allows -extending the protocol and the AgentCapabilities enum in the future such that -old Agents automatically report that they don't support the new capability. This -field MUST be set in the first StatusReport sent by the Agent and MAY be omitted -in subsequent StatusReport messages by setting it to UnspecifiedAgentCapability -value. +The Server SHOULD store the received hash value for each message type. When the Server +receives a message of the same type with a hash value that is different from the last +stored hash and with omitted data then the Server knows it does not have full status +of this particular message. -```protobuf -enum AgentCapabilities { - // The capabilities field is unspecified. - UnspecifiedAgentCapability = 0; - // The Agent can report status. This bit MUST be set, since all Agents MUST - // report status. - ReportsStatus = 0x00000001; - // The Agent can accept remote configuration from the Server. - AcceptsRemoteConfig = 0x00000002; - // The Agent will report EffectiveConfig in StatusReport. - ReportsEffectiveConfig = 0x00000004; - // The Agent can accept package offers. - AcceptsPackages = 0x00000008; - // The Agent can report package status. - ReportsPackageStatuses = 0x00000010; - // The Agent can report own trace to the destination specified by - // the Server via ConnectionSettingsOffers.own_traces field. - ReportsOwnTraces = 0x00000020; - // The Agent can report own metrics to the destination specified by - // the Server via ConnectionSettingsOffers.own_metrics field. - ReportsOwnMetrics = 0x00000040; - // The Agent can report own logs to the destination specified by - // the Server via ConnectionSettingsOffers.own_logs field. - ReportsOwnLogs = 0x00000080; - // The can accept connections settings for OpAMP via - // ConnectionSettingsOffers.opamp field. - AcceptsOpAMPConnectionSettings = 0x00000100; - // The can accept connections settings for other destinations via - // ConnectionSettingsOffers.other_connections field. - AcceptsOtherConnectionSettings = 0x00000200; - // The Agent can accept restart requests. - AcceptsRestartCommand = 0x00000400; +When this situation is encountered, to recover the lost status the Server MUST request +the Agent to report the omitted data. To make this request the Server MUST send +a ServerToAgent message to the Agent and set the corresponding `Report*` bit in +the [flags](#flags-1) field of [ServerToAgent message](#servertoagent-message). +The flags field contains one `Report*` bit per type of compressible message. - // Add new capabilities here, continuing with the least significant unused bit. -} -``` +For the details of the flags field see the [descriptions here](#flags-1). ### AgentDescription Message @@ -949,7 +933,7 @@ message AgentDescription { #### hash The hash of the content of all other fields (even if the other fields are omitted -for compression). See [Agent To Server State Synchronization](#agent-to-server-state-synchronization) +for compression). See [Agent Status Compression](#agent-status-compression) for details about hash field usage. #### identifying_attributes @@ -1012,7 +996,7 @@ message EffectiveConfig { #### hash The hash of the content of all other fields (even if the other fields are omitted -for compression). See [Agent To Server State Synchronization](#agent-to-server-state-synchronization) +for compression). See [Agent Status Compression](#agent-status-compression) for details about hash field usage. #### config_map @@ -1056,15 +1040,15 @@ message RemoteConfigStatus { #### hash The hash of the content of all other fields (even if the other fields are omitted -for compression). See [Agent To Server State Synchronization](#agent-to-server-state-synchronization) +for compression). See [Agent Status Compression](#agent-status-compression) for details about hash field usage. #### last_remote_config_hash -The hash of the remote config that was last received by this Agent from the -management Server. The Server SHOULD compare this hash with the config hash it -has for the Agent and if the hashes are different the Server MUST include the -remote_config field in the response in the ServerToAgent message. +The hash of the remote config that was last received by this Agent in the +AgentRemoteConfig.config_hash field. The Server SHOULD compare this hash with the +config hash it has for the Agent and if the hashes are different the Server MUST +include the remote_config field in the response in the ServerToAgent message. #### status @@ -1092,7 +1076,7 @@ message PackageStatuses { #### hash The hash of the content of all other fields (even if the other fields are omitted -for compression). See [Agent To Server State Synchronization](#agent-to-server-state-synchronization) +for compression). See [Agent Status Compression](#agent-status-compression) for details about hash field usage. #### packages @@ -1279,7 +1263,7 @@ destinations: The Server may make an offer for the particular connection class only if the corresponding capability to use the connection is reported by the Agent via -StatusReport.capabilities field: +AgentToServer.capabilities field: - If ReportsOwnTraces capability bit is set the Server may offer connection settings for traces using own_traces field. @@ -1773,7 +1757,7 @@ ServerToAgent message is normally sent by the Server in response to a status report the Server has the Agent's description and may tailor the configuration it offers to the specific Agent if necessary. -The Agent MUST set the AcceptsRemoteConfig bit of StatusReport.capabilities if +The Agent MUST set the AcceptsRemoteConfig bit of AgentToServer.capabilities if the Agent is capable of accepting remote configuration. If the bit is not set the Server MUST not offer a remote configuration to the Agent. @@ -1790,9 +1774,9 @@ and will also report the Effective Configuration to the OpAMP Server via the typically allows the end user to see the effective configuration alongside other data reported in the status reported by the Agent. -The Agent MUST set the ReportsEffectiveConfig bit of StatusReport.capabilities +The Agent MUST set the ReportsEffectiveConfig bit of AgentToServer.capabilities if the Agent is capable of reporting effective configuration. If the bit is not -set the Server should not expect the StatusReport.effective_config field to be +set the Server should not expect the AgentToServer.effective_config field to be set. Here is the typical configuration sequence diagram: @@ -1801,7 +1785,7 @@ Here is the typical configuration sequence diagram: ``` Agent Server - │ AgentToServer{StatusReport} │ ┌─────────┐ + │ AgentToServer{} │ ┌─────────┐ ├──────────────────────────────────►├──►│ Process │ │ │ │ Status │ Local Remote │ │ │ and │ @@ -1814,16 +1798,18 @@ Config Config │ ServerToAgent{AgentRemoteConfig} │ │ Fetch │ └────┬────┘ │ │ │ │ │ │Effective │ │ - │Config │ AgentToServer{StatusReport} │ + │Config │ AgentToServer{} │ └──────────►├──────────────────────────────────►│ │ │ │ │ ``` +EffectiveConfig and RemoteConfigStatus fields are included in the AgentToServer +message if the fields have changed. -Note: the Agent SHOULD NOT send a status report if the Effective Configuration -or other fields that are reported via StatusReport message are unchanged. If the -Agent does not follow this rule the operation may result in an infinite loop of +Note: the Agent SHOULD NOT send AgentToServer message if the Effective Configuration +or other fields that are reported via AgentToServer message are unchanged. +If the Agent does not follow this rule the operation may result in an infinite loop of messages sent back and forth between the Agent and the Server. The Server may also initiate sending of a remote configuration on its own, @@ -1848,7 +1834,7 @@ Config Config │ ServerToAgent{AgentRemoteConfig} │ │and │ └────┬────┘ │ │ │ │ │ │Effective │ │ - │Config │ AgentToServer{StatusReport} │ + │Config │ AgentToServer{} │ └──────────►├──────────────────────────────────►│ │ │ │ │ @@ -1984,7 +1970,7 @@ file the Agent may extract the files contained in it. How exactly this is done is Agent specific and is beyond the scope of the protocol. The Server is allowed to make a package offer only if the Agent indicated that it -can accept packages via AcceptsPackages bit of StatusReport.capabilities field. +can accept packages via AcceptsPackages bit of AgentToServer.capabilities field. ### Downloading Packages @@ -2076,7 +2062,7 @@ reporting process: │◄────────────────┤ │ │ Download file #2│ │ ├────────────────►│ │ - │ │ AgentToServer{StatusReport} │ + │ │ AgentToServer{PackageStatuses} │ │ ├─────────────────────────────────►│ │ │ │ . . . @@ -2176,9 +2162,9 @@ A map of packages. Keys are package names. Aggregate hash of all remotely installed packages. The Agent SHOULD include this value in subsequent -[StatusReport](#statusreport-message) messages. This in turn allows the Server +[PackageStatuses](#packagestatuses-message) messages. This in turn allows the Server to identify that a different set of packages is available for the Agent and -specify the available packages in the next DataToAgent message. +specify the available packages in the next ServerToAgent message. This field MUST be always set if the Server supports sending packages to the Agents and if the Agent indicated it is capable of accepting packages. @@ -2382,13 +2368,13 @@ typically only needs to keep one up-to-date message of each kind that it wants to send to the Server and send it as soon as the connection is available. For example, the Agent should keep track of its own status and compose a -StatusReport message that is ready to be sent at the first opportunity. If the -Agent is unable to send the StatusReport message (for example if the connection -is not yet available) the Agent does not need to create a new StatusReport every -time the Agent's status changes and keep all these StatusReport messages in a +AgentToServer message that is ready to be sent at the first opportunity. If the +Agent is unable to send the AgentToServer message (for example if the connection +is not yet available) the Agent does not need to create a new AgentToServer every +time the Agent's status changes and keep all these AgentToServer messages in a queue ready to be sent. The Agent simply needs to keep one up-to-date -StatusReport message and send it at the first opportunity. This of course -requires the StatusReport message to contain all changes since it was last +AgentToServer message and send it at the first opportunity. This of course +requires the AgentToServer message to contain all changes since it was last reported and to correctly reflect the current (last) state of the Agent. Similarly, all other Agent reporting capabilities, such as Addon Status @@ -2548,11 +2534,11 @@ the peer does not support a particular capability. Both the Agent and the Server indicate the capabilities that they support during the initial message exchange. The Agent sets the capabilities bit-field in the -StatusReport message, the Server sets the capabilities bit-field in the +AgentToServer message, the Server sets the capabilities bit-field in the ServerToAgent message. Each set bit in the capabilities field indicates that the particular capability -is supported. The list of Agent capabilities is [here](#statusreport-message). +is supported. The list of Agent capabilities is [here](#agenttoserver-message). The list of Server capabilities is [here](#servertoagent-message). After the Server learns about the capabilities of the particular Agent the @@ -2587,7 +2573,7 @@ deserialized by the recipient. For the new capabilities that extend the functionality in such a manner that they cannot be silently ignored by the peer a different approach is used. -The capabilities fields in StatusReport and ServerToAgent messages contains a +The capabilities fields in AgentToServer and ServerToAgent messages contains a number of reserved bits. These bits SHOULD be used for indicating support of new capabilities that will be added to OpAMP in the future. @@ -2596,7 +2582,7 @@ message. This allows the recipient, which implements a newer version of OpAMP to learn that the sender does not support the new capability and adjust its behavior correspondingly. -The StatusReport and ServerToAgent messages are the first messages exchanged by +The AgentToServer and ServerToAgent messages are the first messages exchanged by the Agent and Server which allows them to learn about the capabilities of the peer and adjust their behavior appropriately. How exactly the behavior is adjusted for future capabilities MUST be defined in the future specification of