Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Mark certain capabilities as Beta #147

Merged
merged 1 commit into from
Jul 6, 2023
Merged

Mark certain capabilities as Beta #147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions proto/opamp.proto
View file
Open in desktop
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 All @@ -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;
}

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

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
42 changes: 39 additions & 3 deletions specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
// 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;
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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].
}
```

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

Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -800,6 +818,8 @@ Additional [RetryInfo](#throttling) message about retrying if type==UNAVAILABLE.

## ServerToAgentCommand Message

// Status: [Beta].

The message has the following structure:

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

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