From 26772175788234172b723c7ab3c531edc17754b0 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Thu, 15 Jun 2023 16:46:14 -0400 Subject: [PATCH] Mark certain capabilities as Beta Contributes to https://github.com/open-telemetry/opamp-spec/issues/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 --- proto/opamp.proto | 27 +++++++++++++++++++++++++++ specification.md | 35 +++++++++++++++++++++++++++++++++-- 2 files changed, 60 insertions(+), 2 deletions(-) diff --git a/proto/opamp.proto b/proto/opamp.proto index 7585784..2853546 100644 --- 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. @@ -167,10 +170,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 +185,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 +210,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 +253,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 +278,18 @@ message OtherConnectionSettings { map 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 +319,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 +367,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 packages = 1; @@ -385,6 +399,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 +419,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 @@ -525,23 +542,30 @@ 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. AgentCapabilities_AcceptsRestartCommand = 0x00000400; @@ -604,6 +628,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 +650,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 +703,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 index 0e20371..9182785 100644 --- a/specification.md +++ b/specification.md @@ -510,23 +510,30 @@ 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. AcceptsRestartCommand = 0x00000400; @@ -563,6 +570,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,8 +640,8 @@ 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; @@ -666,12 +675,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 +739,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. @@ -1114,6 +1129,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 +1166,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 +1264,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 +1714,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 +1965,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 +2348,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 +2614,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