telemetry

jumpstarter.v1

Services

TelemetryService

A service that reverse-scrapes exporter metrics and receives structured logs. Implemented by jumpstarter-telemetry; not part of the controller.

Method	Request	Response	Description
MetricsStream	stream MetricsStreamRequest	stream MetricsStreamResponse	Persistent bidirectional stream: telemetry sends scrape requests, exporter responds with metric snapshots (structured families plus optional OpenMetrics text).
PushLogs	PushLogsRequest	PushLogsResponse	Push structured log entries to the telemetry service for Loki ingest.

Messages

MetricsStreamRequest

Exporter → Telemetry

Field	Number	Type	Label	Description
register	1	MetricsRegister	oneof msg	First message: identify this exporter.
scrape_response	2	MetricsScrapeResponse	oneof msg	Subsequent: reply to a scrape.

MetricsRegister

Field	Number	Type	Label	Description
identity	1	string		Exporter CRD name (verified against the auth token by the server).

MetricsScrapeResponse

Field	Number	Type	Label	Description
metrics_text	1	bytes		Optional generate_latest() OpenMetrics text (legacy / debug).
timestamp	2	google.protobuf.Timestamp		When the snapshot was taken.
families	3	MetricsFamily	repeated	DD-3 sidecar: in-memory registry dump so the hub can merge and filter exemplars without parsing OpenMetrics text (prometheus/common cannot).

MetricsLabel

One label name/value pair on a sample or exemplar.

Field	Number	Type	Label	Description
name	1	string		Label name.
value	2	string		Label value.

MetricsExemplar

OpenMetrics exemplar attached to a sample (JEP-0013 allowlist applied on the hub).

Field	Number	Type	Label	Description
labels	1	MetricsLabel	repeated	Exemplar labels (client, lease_id, …).
value	2	double		Exemplar observation value.
timestamp	3	google.protobuf.Timestamp		Optional exemplar timestamp.

MetricsSample

One collected sample from prometheus_client (including histogram _bucket/_sum/_count).

Field	Number	Type	Label	Description
name	1	string		Sample name (may include _bucket, _sum, _count).
labels	2	MetricsLabel	repeated	Sample labels (histogram buckets include le).
value	3	double		Sample value.
exemplar	4	MetricsExemplar		Optional exemplar for this sample.

MetricsFamily

One metric family from CollectorRegistry.collect().

Field	Number	Type	Label	Description
name	1	string		Family name (counters include _total
help	2	string		Help text.
type	3	MetricsType		Family type.
samples	4	MetricsSample	repeated	Collected samples, including exemplars.

MetricsStreamResponse

Telemetry → Exporter

Field	Number	Type	Label	Description
scrape_request	1	MetricsScrapeRequest	oneof msg

MetricsScrapeRequest

Empty request: “send your /metrics now”.

No fields defined.

PushLogsRequest

Request to push log entries to the telemetry service.

Field	Number	Type	Label	Description
entries	1	LogEntry	repeated	Log entries to push.

PushLogsResponse

Response to a PushLogs request.

Field	Number	Type	Label	Description
accepted	1	uint32		Number of entries accepted.
dropped	2	uint32		Number of entries dropped (backpressure).

LogEntry

A structured log entry from an exporter or client. Maps directly to a Loki log entry with stream labels and body fields.

Field	Number	Type	Label	Description
timestamp	1	google.protobuf.Timestamp		When the log was emitted.
severity	2	string		Log severity: debug, info, warning, error, critical.
message	3	string		Human-readable log message.
component	4	string		Loki stream label: cli, exporter, controller, router, telemetry.
exporter	5	string		Loki stream label: exporter CRD name (bounded by cluster size).
lease	6	string		Log body only (high cardinality): active lease name.
client	7	string		Log body only (high cardinality): client CRD name.
operation	8	string		Log body: operation name (flash, power, etc.).
result	9	string		Log body: operation outcome (success, failure, etc.).
driver_type	10	string		Log body: driver category (storage, power, network, etc.).
extra_fields	11	map<string, string>		Additional structured key-value fields.
namespace	12	string		Loki stream label: Kubernetes namespace (bounded by cluster size).

Enums

MetricsType

Prometheus metric type for a MetricsFamily.

Name	Number	Description
METRICS_TYPE_UNSPECIFIED	0	Unknown or unset type.
METRICS_TYPE_COUNTER	1	Monotonic counter.
METRICS_TYPE_GAUGE	2	Gauge.
METRICS_TYPE_HISTOGRAM	3	Histogram (bucket / sum / count samples).
METRICS_TYPE_SUMMARY	4	Summary.
METRICS_TYPE_UNTYPED	5	Untyped / unknown.