A telemetry client is an app that interacts with the Telemetry service to
configure data collection, manage metric configurations, and receive telemetry
reports. Clients use the libsdv_telemetry_rust_wrapper Rust library to
interact with the service.
API surface overview
See the Rust telemetry client library API Reference for API documentation.
The library provides a Rust interface for interacting with the underlying Telemetry service. The library is responsible for the following areas:
Service lifecycle management: Manages the connection to the Telemetry service.
- Initialization: Establishes a connection to the service using a blocking call. After connecting, you can register callbacks to receive asynchronous notifications about system status and the availability of new reports.
- Shutdown: Provides a way to gracefully disconnect from the service and clean up all associated resources.
Metrics configuration lifecycle management: Offers control over the lifecycle of metrics configurations.
- Management: Clients can add, remove, activate, and deactivate metrics configurations.
- Inspection: You can query for the list of active and inactive configurations.
Report handling and retrieval: Facilitates access to the data collected by the Telemetry service.
- Notifications: Notifies clients asynchronously using a callback whenever a new metrics report is ready for retrieval.
- Data access: Provides methods to fetch specific reports by their UUID and to retrieve a list of all available reports.
Status and error reporting: Provides insight into the health and status of the Telemetry service.
- Asynchronous status updates: Clients receive real-time status updates, including errors and warnings, through a dedicated callback. This lets you implement robust error handling and monitor the service's state.
Example usage
For a complete, compilable app demonstrating the full lifecycle, see the sample
client implementation:
samples/telemetry/client/rust/telemetry_client/telemetry_rust_c_client.rs.
The sample client is a command-line utility that interacts with the full library API. The sample demonstrates how to bridge the library's callback-based interface with an asynchronous Rust runtime (Tokio) using channels.
The client performs this sequence of operations:
- Establishes a connection to the Telemetry service and registers callbacks for status updates and metrics report notifications.
- Reads metrics configuration files provided as command-line arguments, and then adds and activates the configurations in the service.
- Uses a background task to log asynchronous status messages (errors or warnings) received from the service.
- Manages the data retrieval loop by performing the following actions:
- Waits for a notification that a metrics report is ready.
- Fetches the full metrics report data.
- Optionally writes the report to disk as a binary protocol buffer file.
- Removes metrics configuration from the service once it produces the first metrics report. Note that this is a demo implementation, and your own clients can receive any number of reports.
- Gracefully closes the connection to the service.