Mark certain capabilities as Beta

Contributes to open-telemetry#146 As agreed we will mark certain capabilities as Beta for now, until we have more confidence that they are well-specified. This will be primarily driven by feedback from implementations. Capabilities marked Beta: - Packages - Connection Settings Managements - Own Telemetry Reporting - Server to Agent Command.
tigrannajaryan · Jul 6, 2023 · 6c018e0 · 6c018e0
1 parent e19c666
commit 6c018e0
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 3 deletions.
diff --git a/proto/opamp.proto b/proto/opamp.proto
@@ -67,6 +67,7 @@ message AgentToServer {
     // 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.
+    // Status: [Beta].
     PackageStatuses package_statuses = 8;
 
     // AgentDisconnect MUST be set in the last AgentToServer message sent from the
@@ -113,9 +114,11 @@ message ServerToAgent {
 
     // This field is set when the Server wants the Agent to change one or more
     // of its client connection settings (destination, headers, certificate, etc).
+    // Status: [Beta].
     ConnectionSettingsOffers connection_settings = 4;
 
     // This field is set when the Server has packages to offer to the Agent.
+    // Status: [Beta].
     PackagesAvailable packages_available = 5;
 
     // Bit flags as defined by ServerToAgentFlags bit masks.
@@ -138,6 +141,7 @@ message ServerToAgent {
     // Allows the Server to instruct the Agent to perform a command, e.g. RESTART. This field should not be specified
     // with fields other than instance_uid and capabilities. If specified, other fields will be ignored and the command
     // will be performed.
+    // Status: [Beta].
     ServerToAgentCommand command = 9;
 }
 
@@ -167,10 +171,13 @@ enum ServerCapabilities {
     // The Server can accept EffectiveConfig in AgentToServer.
     ServerCapabilities_AcceptsEffectiveConfig   = 0x00000004;
     // The Server can offer Packages.
+    // Status: [Beta].
     ServerCapabilities_OffersPackages           = 0x00000008;
     // The Server can accept Packages status.
+    // Status: [Beta].
     ServerCapabilities_AcceptsPackagesStatus    = 0x00000010;
     // The Server can offer connection settings.
+    // Status: [Beta].
     ServerCapabilities_OffersConnectionSettings = 0x00000020;
 
     // Add new capabilities here, continuing with the least significant unused bit.
@@ -179,6 +186,7 @@ enum ServerCapabilities {
 // The OpAMPConnectionSettings message is a collection of fields which comprise an
 // offer from the Server to the Agent to use the specified settings for OpAMP
 // connection.
+// Status: [Beta].
 message OpAMPConnectionSettings {
     // OpAMP Server URL This MUST be a WebSocket or HTTP URL and MUST be non-empty, for
     // example: "wss://example.com:4318/v1/opamp"
@@ -203,6 +211,7 @@ message OpAMPConnectionSettings {
 // The TelemetryConnectionSettings message is a collection of fields which comprise an
 // offer from the Server to the Agent to use the specified settings for a network
 // connection to report own telemetry.
+// Status: [Beta].
 message TelemetryConnectionSettings {
     // The value MUST be a full URL an OTLP/HTTP/Protobuf receiver with path. Schema
     // SHOULD begin with "https://", for example "https://example.com:4318/v1/metrics"
@@ -245,6 +254,7 @@ message TelemetryConnectionSettings {
 // field is not set (this is done to overcome the limitation of old protoc
 // compilers don't generate methods that allow to check for the presence of
 // the field.
+// Status: [Beta].
 message OtherConnectionSettings {
     // A URL, host:port or some other destination specifier.
     string destination_endpoint = 1;
@@ -269,15 +279,18 @@ message OtherConnectionSettings {
     map<string, string> other_settings = 4;
 }
 
+// Status: [Beta].
 message Headers {
     repeated Header headers = 1;
 }
 
+// Status: [Beta].
 message Header {
     string key = 1;
     string value = 2;
 }
 
+// Status: [Beta].
 message TLSCertificate {
     // The (public_key,private_key) certificate pair should be issued and
     // signed by a Certificate Authority that the destination Server recognizes.
@@ -307,6 +320,7 @@ message TLSCertificate {
     bytes ca_public_key = 3;
 }
 
+// Status: [Beta].
 message ConnectionSettingsOffers {
     // Hash of all settings, including settings that may be omitted from this message
     // because they are unchanged.
@@ -354,6 +368,7 @@ message ConnectionSettingsOffers {
 }
 
 // List of packages that the Server offers to the Agent.
+// Status: [Beta].
 message PackagesAvailable {
     // Map of packages. Keys are package names, values are the packages available for download.
     map<string, PackageAvailable> packages = 1;
@@ -385,6 +400,7 @@ message PackagesAvailable {
 // If the Agent has an installed package with the specified name and the same
 // hash then the Agent does not need to do anything, it already
 // has the right version of the package.
+// Status: [Beta].
 message PackageAvailable {
     PackageType type = 1;
 
@@ -404,11 +420,13 @@ message PackageAvailable {
 }
 
 // The type of the package, either an addon or a top-level package.
+// Status: [Beta].
 enum PackageType {
     PackageType_TopLevel = 0;
     PackageType_Addon    = 1;
 }
 
+// Status: [Beta].
 message DownloadableFile {
     // The URL from which the file can be downloaded using HTTP GET request.
     // The Server at the specified URL SHOULD support range requests
@@ -462,10 +480,12 @@ message RetryInfo {
 
 // ServerToAgentCommand is sent from the Server to the Agent to request that the Agent
 // perform a command.
+// Status: [Beta].
 message ServerToAgentCommand {
     CommandType type = 1;
 }
 
+// Status: [Beta].
 enum CommandType {
     // The Agent should restart. This request will be ignored if the Agent does not
     // support restart.
@@ -525,25 +545,33 @@ enum AgentCapabilities {
     // The Agent will report EffectiveConfig in AgentToServer.
     AgentCapabilities_ReportsEffectiveConfig         = 0x00000004;
     // The Agent can accept package offers.
+    // Status: [Beta].
     AgentCapabilities_AcceptsPackages                = 0x00000008;
     // The Agent can report package status.
+    // Status: [Beta].
     AgentCapabilities_ReportsPackageStatuses         = 0x00000010;
     // The Agent can report own trace to the destination specified by
     // the Server via ConnectionSettingsOffers.own_traces field.
+    // Status: [Beta].
     AgentCapabilities_ReportsOwnTraces               = 0x00000020;
     // The Agent can report own metrics to the destination specified by
     // the Server via ConnectionSettingsOffers.own_metrics field.
+    // Status: [Beta].
     AgentCapabilities_ReportsOwnMetrics              = 0x00000040;
     // The Agent can report own logs to the destination specified by
     // the Server via ConnectionSettingsOffers.own_logs field.
+    // Status: [Beta].
     AgentCapabilities_ReportsOwnLogs                 = 0x00000080;
     // The can accept connections settings for OpAMP via
     // ConnectionSettingsOffers.opamp field.
+    // Status: [Beta].
     AgentCapabilities_AcceptsOpAMPConnectionSettings = 0x00000100;
     // The can accept connections settings for other destinations via
     // ConnectionSettingsOffers.other_connections field.
+    // Status: [Beta].
     AgentCapabilities_AcceptsOtherConnectionSettings = 0x00000200;
     // The Agent can accept restart requests.
+    // Status: [Beta].
     AgentCapabilities_AcceptsRestartCommand          = 0x00000400;
     // The Agent will report Health via AgentToServer.health field.
     AgentCapabilities_ReportsHealth                  = 0x00000800;
@@ -604,6 +632,7 @@ enum RemoteConfigStatuses {
 
 // The PackageStatuses message describes the status of all packages that the Agent
 // has or was offered.
+// Status: [Beta].
 message PackageStatuses {
     // A map of PackageStatus messages, where the keys are package names.
     // The key MUST match the name field of PackageStatus message.
@@ -625,6 +654,7 @@ message PackageStatuses {
 }
 
 // The status of a single package.
+// Status: [Beta].
 message PackageStatus {
     // Package name. MUST be always set and MUST match the key in the packages field
     // of PackageStatuses message.
@@ -677,6 +707,7 @@ message PackageStatus {
 }
 
 // The status of this package.
+// Status: [Beta].
 enum PackageStatusEnum {
     // Package is successfully installed by the Agent.
     // The error_message field MUST NOT be set.

diff --git a/specification.md b/specification.md
@@ -510,25 +510,33 @@ enum AgentCapabilities {
     // The Agent will report EffectiveConfig in AgentToServer.
     ReportsEffectiveConfig         = 0x00000004;
     // The Agent can accept package offers.
+    // Status: [Beta].
     AcceptsPackages                = 0x00000008;
     // The Agent can report package status.
+    // Status: [Beta].
     ReportsPackageStatuses         = 0x00000010;
     // The Agent can report own trace to the destination specified by
     // the Server via ConnectionSettingsOffers.own_traces field.
+    // Status: [Beta].
     ReportsOwnTraces               = 0x00000020;
     // The Agent can report own metrics to the destination specified by
     // the Server via ConnectionSettingsOffers.own_metrics field.
+    // Status: [Beta].
     ReportsOwnMetrics              = 0x00000040;
     // The Agent can report own logs to the destination specified by
     // the Server via ConnectionSettingsOffers.own_logs field.
+    // Status: [Beta].
     ReportsOwnLogs                 = 0x00000080;
     // The can accept connections settings for OpAMP via
     // ConnectionSettingsOffers.opamp field.
+    // Status: [Beta].
     AcceptsOpAMPConnectionSettings = 0x00000100;
     // The can accept connections settings for other destinations via
     // ConnectionSettingsOffers.other_connections field.
+    // Status: [Beta].
     AcceptsOtherConnectionSettings = 0x00000200;
     // The Agent can accept restart requests.
+    // Status: [Beta].
     AcceptsRestartCommand          = 0x00000400;
     // The Agent will report Health via AgentToServer.health field.
     ReportsHealth                  = 0x00000800;
@@ -563,6 +571,8 @@ AgentToServer message.
 
 #### AgentToServer.package_statuses
 
+Status: [Beta].
+
 The list of the Agent packages, including package statuses.
 This field SHOULD be unset if this information is unchanged since the last
 AgentToServer message.
@@ -631,12 +641,12 @@ message ServerToAgent {
     string instance_uid = 1;
     ServerErrorResponse error_response = 2;
     AgentRemoteConfig remote_config = 3;
-    ConnectionSettingsOffers connection_settings = 4;
-    PackagesAvailable packages_available = 5;
+    ConnectionSettingsOffers connection_settings = 4; // Status: [Beta].
+    PackagesAvailable packages_available = 5; // Status: [Beta].
     uint64 flags = 6;
     uint64 capabilities = 7;
     AgentIdentification agent_identification = 8;
-    ServerToAgentCommand command = 9;
+    ServerToAgentCommand command = 9; // Status: [Beta].
 }
 ```
 
@@ -666,12 +676,16 @@ This field is set when the Server has a remote config offer for the Agent. See
 
 #### ServerToAgent.connection_settings
 
+Status: [Beta].
+
 This field is set when the Server wants the Agent to change one or more of its
 client connection settings (destination, headers, certificate, etc). See
 [Connection Settings Management](#connection-settings-management) for details.
 
 #### ServerToAgent.packages_available
 
+Status: [Beta].
+
 This field is set when the Server has packages to offer to the Agent. See
 [Packages](#packages) for details.
 
@@ -726,8 +740,10 @@ enum ServerCapabilities {
     // The Server can offer Packages.
     OffersPackages                 = 0x00000008;
     // The Server can accept Packages status.
+    // Status: [Beta].
     AcceptsPackagesStatus          = 0x00000010;
     // The Server can offer connection settings.
+    // Status: [Beta].
     OffersConnectionSettings       = 0x00000020;
 
     // Add new capabilities here, continuing with the least significant unused bit.
@@ -750,6 +766,8 @@ message AgentIdentification {
 
 #### ServerToAgent.command
 
+Status: [Beta].
+
 This field is set when the Server wants the Agent to
 perform a restart. This field must not be set with other fields
 besides instance_uid or capabilities. All other fields will be ignored and the
@@ -800,6 +818,8 @@ Additional [RetryInfo](#throttling) message about retrying if type==UNAVAILABLE.
 
 ## ServerToAgentCommand Message
 
+// Status: [Beta].
+
 The message has the following structure:
 
 ```protobuf
@@ -1114,6 +1134,8 @@ Optional error message if status==FAILED.
 
 ### PackageStatuses Message
 
+Status: [Beta].
+
 The PackageStatuses message describes the status of all packages that the Agent
 has or was offered. The message has the following structure:
 
@@ -1149,6 +1171,8 @@ The field must be unset is there were no processing errors.
 
 ### PackageStatus Message
 
+Status: [Beta].
+
 The PackageStatus has the following structure:
 
 ```protobuf
@@ -1245,6 +1269,8 @@ An error message if the status is erroneous.
 
 ## Connection Settings Management
 
+Status: [Beta].
+
 OpAMP includes features that allow the Server to manage Agent's connection
 settings for all of the destinations that the Agent connects to,
 as well as the OpAMP Client's connection settings.
@@ -1693,6 +1719,8 @@ in the future.
 
 ## Own Telemetry Reporting
 
+Status: [Beta].
+
 Own Telemetry Reporting is an optional capability of OpAMP protocol. The Server
 can offer to the Agent a destination to which the Agent can send its own
 telemetry (metrics, traces or logs). If the Agent is capable of producing
@@ -1942,6 +1970,8 @@ message AgentRemoteConfig {
 
 ## Packages
 
+Status: [Beta].
+
 Each Agent is composed of one or more packages. A package has a name and content stored
 in a file. The content of the file, functionality provided by the packages, how they are
 stored and used by the Agent side is Agent type-specific and is outside the concerns of
@@ -2323,6 +2353,8 @@ a new instance_uid, and send it as new_instance_uid value of AgentIdentification
 
 ## Authentication
 
+Status: [Beta].
+
 The Client and the Server MAY use authentication methods supported by HTTP, such
 as [Basic](https://datatracker.ietf.org/doc/html/rfc7617) authentication or
 [Bearer](https://datatracker.ietf.org/doc/html/rfc6750) authentication. The
@@ -2587,6 +2619,10 @@ The specification provides the follow stability guarantees of the
 - `optional` and `repeated` declarators of existing fields will not change.
 - No existing symbol will be deleted.
 
+Note that the above guarantees do not apply to messages and fields which are
+labeled [Beta]. [Beta] message and fields are subject to weaker guarantees defined
+[here](https://github.com/open-telemetry/community/blob/47813530864b9fe5a5146f466a58bd2bb94edc72/maturity-matrix.yaml#L57).
+
 Future versions of the OpAMP specification may be extended by modifying the
 Protobuf schema defined in this specification version. The following Protobuf schema
 changes are allowed, provided that they comply with the interoperability requirements