Proto commits in open-telemetry/opamp-spec

These 16 commits are when the Protocol Buffers files have changed:

2025-05-06

Add TLS settings to all connection settings (#205)

The documentation is generated from this commit.

2025-01-29

Change PackageStatus.download_details.download_bytes_per_second to double (#210)

2024-10-31

Add message about available components to AgentDetails (#201) This PR adds a new ComponentDetails type that allows agents to communicate metadata relating to the components available in the agent.

2024-10-23

Add downloading state and download_details to PackageStatus (#206) Add a separate `Downloading` `PackageStatusEnum` so an agent can use a distinguish between downloading and installing a new package. Add a `download_details` attribute that may optionally be used with the new `Downloading` status to give a user additional details about the package download: download rate, and percentage download. - Closes #204

2024-07-30

Allow setting Headers in DownloadableFile message (#197) Fixes #194 This PR amends the spec and protos to include an optional set of headers in DownloadableFile, to be used in the download GET request to set up auth parameters. This is only one of the ways we could implement setting authentication paramaters to be used by Agents when downloading packages, but it is consistent with other uses of the headers field and generic enough to cover different use cases so I feel it's worth considering.

2024-07-29

Introduce heartbeats (#190) This PR introduces a client side heartbeat that can be set via the OpAMP Connection Settings. After discussing more in the past SIG meeting, I worked through the following pro/con for a client side vs server side heartbeat. closes https://github.com/open-telemetry/opamp-spec/issues/183 ## Client Side A client side heartbeat would be negotiated between the client and server, where the client's default heartbeat is set to 30s. On connect, the server has an option to entirely disable heartbeats by setting an explicit 0 for the field. The server can also offer a different heartbeat interval depending on its infrastructure's needs. After connection, the agent will begin a timer and each N seconds will send a message that minimally contains its instance id. An HTTP connection will use this interval for its polling as well. Some agents that are not directly informed of health changes should also use this for component health reporting. ### Pros 1. The agent is able to prevent a proxy from timing out the socket connection 2. The agent's HTTP polling interval is now configurable 3. The server can properly age out and remove dead agents 4. Requires a single successful message for heartbeat processing ### Cons 1. requires a proto change 2. extra work for the client a. the client will now need to keep track of a heartbeat timer to send this periodic message ## Server Side A server side heartbeat would simply be a part of opamp-go and would require no changes to the spec to allow this to work. The server every N seconds would send an empty message to the client to keep the socket connection active. ### Pros 1. Requires no spec or proto changes 2. Server is in control of the interval ### Cons 1. Server has no way to determine if an Agent is dead a. The core value of the change to me is that the server can now rely on the fact it is receiving a message every N seconds and can take action if that is the case b. If the client is using an http transport, there is no way for the server to reliably send a heartbeat message to guarantee the liveness of the agent. Say the server 'requests' a heartbeat from the client, but the client is already dead 2. The only way to send an 'empty' server to agent message today is by using the report full state flag. This means the message back from the agent is going to be larger than necessary solely to keep the connection. a. We could also add a heartbeat flag as part of the message 3. Requires three successful messages for heartbeat processing a. A server would need to successfully send the heartbeat flagged message over the websocket, the client would then send its heartbeat back via an AgentToServer message, and the server would need to ACK with a responding ServerToAgent message. I think given the pros and cons of the above, I prefer an Agent heartbeat over a server heartbeat. If we need a new proto change anyway to introduce a heartbeat flag, I think the client approach is more effective. Furthermore, this change helps provide guidance for agents that are not informed of status updates. By setting an explicit heartbeat for the client, the server can increase the granularity of the agent's status updates. The client heartbeat approach also matches the design for a conventional deadman's switch – something that is constantly sending a signal out for a receiver to detect only when that signal is no longer received. Flipping that design removes that guarantee and weakens the overall feature. Finally, the server would also be able to explicitly disconnect misbehaving clients and force them to reconnect with new settings. If the server were to not receive a heartbeat within its set window, the server could initiate a disconnect to gracefully close the client. This approach would not work as well for a server heartbeat as it would need to cancel the initial server to agent message. ## References - [RabbitMQ](https://www.rabbitmq.com/docs/heartbeats#tcp-keepalives) - Rabbit prefers client heartbeats over server ones, AND explicit heartbeat instead of TCP keepalives - [MQTT](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901094) - Functionally the same as this proposal, they call them keep alives - [Phoenix Socket Client](https://hexdocs.pm/phoenix/writing_a_channels_client.html#message-format) - Works by the client sending a specific heartbeat message

2024-07-04

Amend field names in TLSCertificate message (#195) Fixes #161 This PR amends two field names in TLSCertificate message, making them more descriptive. I've opted to use the shorter `cert` term, to avoid confusion with the parent message which is used as `TLSCertificate certificate` in three places.

2024-05-22

Fix typos (#192)

2024-05-07

Replace ULIDs by 16 byte ids and recommend UUID v7 (#186) The early version of the spec was written before UUID v7 existed and ULID was chosen as a ID type that is suited to be used as a primary key in databases. Since than UUID v7 was standardized and aims to serve the exact same niche. ## Proposal Replace instance_id definition to be an arbitrary sequence of 16 bytes. Both ULID and any version of UUID may be used as the value. We also recommend to use UUID v7 for the value. This is a breaking change in the spec. We recommend opamp-go implementation to implement the change in backward compatible way, supporting both old and new instance_uid formats for a period of time. Since `bytes` and `string` are compatible in the Protobuf wire encoding it is possible to use the new Protobuf declarations to receive messages encoded using the old Protobuf declarations - string's UTF8 bytes will simply populate the bytes of the new field. Receivers can simply probe for the length of the received bytes field and if it is 26 treat it as ULID in canonical format, if it is 16 bytes treat it as opaque id in new format, otherwise consider it invalid. I will also post a PR in opamp-go that implements the above behavior.

2023-10-20

Add CustomMessage capability (#132) Issue https://github.com/open-telemetry/opamp-spec/issues/49

2023-10-13

Add ComponentHealth message (#168) This commit replaces the AgentHealth message with a wire-backwards-compatible ComponentHealth message. The ComponentHealth message allows reporting health for nested sub-components, component status, and status timestamp, while retaining the fields from the original AgentHealth message.

2023-09-14

Add client-initiated certificate request flow (CSR) (#162) Resolves https://github.com/open-telemetry/opamp-spec/issues/13 Uses [Development] label as the indication of the least mature level proposed in this upcoming OTEP: https://github.com/open-telemetry/oteps/pull/232/

2023-07-10

Drop period after "Status: [Beta]" (#159)

2023-07-06

Mark certain capabilities as Beta (#147) 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 - Server to Agent Command.

2022-11-09

Clarify agent health reporting (#137) Resolves https://github.com/open-telemetry/opamp-spec/issues/136 - Renamed `up` to `healthy`. - `start_time_unix_nano` is no longer tied to `up` and is set independently.

2022-09-22

Move proto files to opamp-spec repo (#126) Contributes to https://github.com/open-telemetry/opamp-go/issues/133 Now that we are adding OpAMP Java implementation the protos can no longer live in opamp-go. We are moving the protos to the spec repo since it fits this repo's purpose naturally. The proto files are copied verbatim from opamp-go. Any changes needed in the proto files can be done in a future PR. In the future it is also worth exploring if we can delete the message definitions from specification.md and instead link them directly to the proto files so that we have a single source of truth.