Skip to content

Commit

Permalink
Mark certain capabilities as Beta
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@tigrannajaryan
tigrannajaryan committed Jun 28, 2023
1 parent e19c666 commit 2677217
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 2 deletions.
27 changes: 27 additions & 0 deletions proto/opamp.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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"
Expand All @@ -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"
Expand Down Expand Up @@ -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;
Expand All @@ -269,15 +278,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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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<string, PackageAvailable> packages = 1;
Expand Down Expand Up @@ -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;

Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
35 changes: 33 additions & 2 deletions specification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 2677217

Please sign in to comment.