# telemetry

`jumpstarter.v1`

## Services

### TelemetryService

A service that receives structured logs from exporters and clients. Implemented by jumpstarter-telemetry; not part of the controller.

| Method | Request | Response | Description |
| --- | --- | --- | --- |
| `PushLogs` | [`PushLogsRequest`](telemetry.md#pushlogsrequest) | [`PushLogsResponse`](telemetry.md#pushlogsresponse) | Push structured log entries to the telemetry service for Loki ingest. |

## Messages

### PushLogsRequest

Request to push log entries to the telemetry service.

| Field | Number | Type | Label | Description |
| --- | --- | --- | --- | --- |
| `entries` | 1 | [`LogEntry`](telemetry.md#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). |