Skip to content

A continuation of HomeBox the inventory and organization system built for the Home User

feat: add frontend telemetry proxy and database tracing metrics documentation

Matthew Kilgored26b88308ba0
diff --git a/docs/src/content/docs/en/advanced/opentelemetry.mdx b/docs/src/content/docs/en/advanced/opentelemetry.mdx
index ec2d12c0..b53def1c 100644
--- a/docs/src/content/docs/en/advanced/opentelemetry.mdx
+++ b/docs/src/content/docs/en/advanced/opentelemetry.mdx
@@ -15,7 +15,7 @@ and behavior of their Homebox applications, which can be invaluable for diagnosi
## Configuration
| Variable | Default | Description |
|-----------------------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| HBOX_OTEL_ENABLED | `false` | If Opentelemtry should be enabled or not |
+| HBOX_OTEL_ENABLED | `false` | If OpenTelemetry should be enabled or not |
| HBOX_OTEL_SERVICE_NAME | `homebox` | This is the name of the service as it will appear in OTEL applications |
| HBOX_OTEL_SERVICE_VERSION | (current build version) | This is the version of the service deployed shown in OTEL applications |
| HBOX_OTEL_EXPORTER | `otlp` | This can be `otlp`, `stdout` or `none` |
@@ -23,7 +23,7 @@ and behavior of their Homebox applications, which can be invaluable for diagnosi
| HBOX_OTEL_PATH_PREFIX | | If your collector is on a sub-directory, it goes here, for example `/otlp`, the `/v1/traces`, `/v1/metrics`, and `/v1/logs` will automatically be appended |
| HBOX_OTEL_PROTOCOL | `grpc` | The protocol to use for the OTLP exporter, can be `grpc` or `http` |
| HBOX_OTEL_INSECURE | `false` | If the OTLP exporter should use an insecure connection |
-| HBOX_OTEL_HEADERS | | If you need to add additional headers for authentication you can do so here in a `name=value` fashion, multiple values are seperated by commas (e.g `name1=value,name2=value`) |
+| HBOX_OTEL_HEADERS | | If you need to add additional headers for authentication you can do so here in a `name=value` fashion, multiple values are separated by commas (e.g `name1=value,name2=value`) |
| HBOX_OTEL_SAMPLE_RATE | `1.0` | The sampling rate to use for traces, a value between `0.0` and `1.0` where `1.0` means all traces are captured and `0.0` means no traces are captured |
| HBOX_OTEL_ENABLE_METRICS | `true` | If metrics should be exported to OTEL or not |
| HBOX_OTEL_METRICS_INTERVAL | `15s` | Interval that metrics should be sent to the collector (this does not impact how often measurements are captured) |
@@ -54,6 +54,46 @@ HBOX_OTEL_INSECURE=false
HBOX_OTEL_SAMPLE_RATE=1.0
```
+## Frontend telemetry proxy
+
+Homebox includes an authenticated proxy endpoint for browser-side traces at `/api/v1/telemetry`.
+
+- The endpoint is available only when both `HBOX_OTEL_ENABLED=true` and `HBOX_OTEL_PROXY_ENABLED=true`.
+- The endpoint requires the same authenticated user context as other API routes.
+- Requests must be `POST` JSON payloads that include a `spans` array.
+- Request bodies are limited to `1 MiB`; larger payloads return `413 Request Entity Too Large`.
+- Invalid telemetry payloads return `400 Bad Request` with a validation message.
+- Valid payloads return `202 Accepted`.
+
+### Frontend payload example
+
+```json
+{
+ "resourceAttributes": {
+ "deployment.environment": "prod"
+ },
+ "spans": [
+ {
+ "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+ "spanId": "00f067aa0ba902b7",
+ "name": "ui.click",
+ "kind": "client",
+ "startTime": 1710000000000,
+ "endTime": 1710000000150
+ }
+ ]
+}
+```
+
+## Database tracing and metrics
+
+When `HBOX_OTEL_ENABLE_DATABASE_TRACING=true`, Homebox instruments database operations with `otelsql`.
+
+- SQLite (`sqlite3`) and PostgreSQL (`pgx`) connections are traced.
+- SQL spans include query text through SQL commenter support.
+- If `HBOX_OTEL_ENABLE_METRICS=true`, database stats metrics are also exported through the configured meter provider.
+- Metrics registration is best effort; Homebox logs a warning if registration fails but continues startup.
+