Fix OpenTelemetry naming in logs and spans

lovasoa · lovasoa · commit 1e64d7e3ed73 · 2026-04-16T11:25:31.000+02:00
diff --git a/examples/telemetry/README.md b/examples/telemetry/README.md
@@ -67,25 +67,25 @@ Each HTTP request produces a tree of **spans** (timed operations):
        └─ [sqlpage] SQL website/todos.sql  ← SQL file execution
             ├─ db.pool.acquire             ← time waiting for a DB connection
             └─ db.query                    ← the actual SQL query
-                 db.statement = "SELECT title, ..."
-                 db.system = "PostgreSQL"
+                 db.query.text = "SELECT title, ..."
+                 db.system.name = "postgresql"
 ```
 
 Key attributes on each span:
 
 | Span               | Key attributes                                                |
 |---------------------|--------------------------------------------------------------|
-| HTTP request        | `http.method`, `http.target`, `http.status_code`, `http.user_agent` |
-| SQL file execution  | `sqlpage.file` — which `.sql` file was executed              |
-| `db.pool.acquire`   | `db.pool.size` — current pool size when acquiring            |
-| `db.query`          | `db.statement` — the full SQL text; `db.system` — database type |
+| HTTP request        | `http.request.method`, `http.route`, `http.response.status_code`, `user_agent.original` |
+| SQL file execution  | `code.file.path` — which `.sql` file was executed            |
+| `db.pool.acquire`   | `db.client.connection.pool.name`; `sqlpage.db.pool.size` — current pool size when acquiring |
+| `db.query`          | `db.query.text` — the full SQL text; `db.system.name` — database type |
 
 ### What you will see in the logs
 
 SQLPage writes one structured log line per event, for example:
 
 ```text
-ts=2026-03-08T20:56:15.000Z level=info target=sqlpage::webserver::http msg="request completed" method=GET path=/ trace_id=4f2d...
+ts=2026-03-08T20:56:15.000Z level=info target=sqlpage::webserver::http msg="request completed" http.request.method=GET url.path=/ trace_id=4f2d...
 ```
 
 The OpenTelemetry Collector receives these SQLPage container logs through Docker's syslog
diff --git a/examples/telemetry/nginx/nginx.conf b/examples/telemetry/nginx/nginx.conf
@@ -20,7 +20,7 @@ http {
     }
 
     log_format otel_request 'ts=$time_iso8601 level=$log_level target=$log_target '
-                            'client_ip=$remote_addr method=$request_method path="$uri" '
+                            'client.address=$remote_addr method=$request_method path="$uri" '
                             'status=$status request_time=$request_time '
                             'connection=$connection '
                             'upstream_addr="$upstream_addr" upstream_status="$upstream_status" '
diff --git a/src/telemetry.rs b/src/telemetry.rs
@@ -370,7 +370,7 @@ fn set_global_subscriber(subscriber: impl tracing::Subscriber + Send + Sync) ->
 ///
 /// Outputs one line per event in logfmt format with carefully chosen fields:
 /// ```text
-/// ts=2026-03-08T20:56:15Z level=error target=sqlpage::webserver::error msg="..." method=GET path=/foo client_ip=1.2.3.4 trace_id=abc123
+/// ts=2026-03-08T20:56:15Z level=error target=sqlpage::webserver::error msg="..." http.request.method=GET url.path=/foo client.address=1.2.3.4 trace_id=abc123
 /// ```
 ///
 /// With terminal colors when stderr is a TTY.
@@ -415,11 +415,14 @@ mod logfmt {
     /// Fields we pick from spans, in display order.
     /// (`span_field_name`, `logfmt_key`)
     const SPAN_FIELDS: &[(&str, &str)] = &[
-        (otel::HTTP_REQUEST_METHOD, "method"),
-        (otel::URL_PATH, "path"),
-        (otel::HTTP_RESPONSE_STATUS_CODE, "status"),
-        ("sqlpage.file", "file"),
-        (otel::CLIENT_ADDRESS, "client_ip"),
+        (otel::HTTP_REQUEST_METHOD, otel::HTTP_REQUEST_METHOD),
+        (otel::URL_PATH, otel::URL_PATH),
+        (
+            otel::HTTP_RESPONSE_STATUS_CODE,
+            otel::HTTP_RESPONSE_STATUS_CODE,
+        ),
+        (otel::CODE_FILE_PATH, otel::CODE_FILE_PATH),
+        (otel::CLIENT_ADDRESS, otel::CLIENT_ADDRESS),
     ];
 
     /// All-zeros trace ID means no real trace context.
@@ -780,7 +783,10 @@ mod logfmt {
 
             write_span_field_maps(&mut buf, [&span_fields], true);
 
-            assert_eq!(buf, " method=GET http.route=/users/:id otel.kind=server");
+            assert_eq!(
+                buf,
+                " http.request.method=GET http.route=/users/:id otel.kind=server"
+            );
         }
 
         #[test]
@@ -794,7 +800,7 @@ mod logfmt {
 
             write_span_field_maps(&mut buf, [&span_fields], false);
 
-            assert_eq!(buf, " method=GET");
+            assert_eq!(buf, " http.request.method=GET");
         }
 
         #[test]
diff --git a/src/webserver/database/execute_queries.rs b/src/webserver/database/execute_queries.rs
@@ -98,7 +98,7 @@ impl<'a> DbQueryMetricsContext<'a> {
         self.span
             .record(otel::EXCEPTION_MESSAGE, tracing::field::display(error));
         self.span
-            .record("exception.details", tracing::field::debug(error));
+            .record("sqlpage.exception.details", tracing::field::debug(error));
         let attributes = [
             opentelemetry::KeyValue::new(otel::DB_SYSTEM_NAME, self.db_system_name),
             opentelemetry::KeyValue::new(otel::DB_OPERATION_NAME, self.operation_name.clone()),
@@ -127,7 +127,7 @@ fn create_db_query_span(
         { otel::CODE_LINE_NUMBER } = source_line_number(line),
         { otel::OTEL_STATUS_CODE } = tracing::field::Empty,
         { otel::EXCEPTION_MESSAGE } = tracing::field::Empty,
-        "exception.details" = tracing::field::Empty,
+        "sqlpage.exception.details" = tracing::field::Empty,
         { otel::DB_RESPONSE_RETURNED_ROWS } = tracing::field::Empty,
     );
     (span, operation_name)
@@ -456,7 +456,12 @@ async fn take_connection<'a>(
         return Ok(c);
     }
     let pool_size = db.connection.size();
-    let acquire_span = tracing::info_span!("db.pool.acquire", db.pool.size = pool_size,);
+    let acquire_span = tracing::info_span!(
+        "db.pool.acquire",
+        { otel::DB_SYSTEM_NAME } = db.info.database_type.otel_name(),
+        { otel::DB_CLIENT_CONNECTION_POOL_NAME } = "sqlpage",
+        sqlpage.db.pool.size = pool_size,
+    );
     match db.connection.acquire().instrument(acquire_span).await {
         Ok(c) => {
             log::debug!("Acquired a database connection");
@@ -895,7 +900,7 @@ mod tests {
                 "db.query",
                 otel.status_code = tracing::field::Empty,
                 exception.message = tracing::field::Empty,
-                exception.details = tracing::field::Empty,
+                sqlpage.exception.details = tracing::field::Empty,
                 db.response.returned_rows = tracing::field::Empty,
             );
             let metrics = crate::telemetry_metrics::TelemetryMetrics::default();
@@ -908,7 +913,7 @@ mod tests {
         assert_eq!(fields[otel::OTEL_STATUS_CODE], "OK");
         assert_eq!(fields[otel::DB_RESPONSE_RETURNED_ROWS], "3");
         assert!(!fields.contains_key(otel::EXCEPTION_MESSAGE));
-        assert!(!fields.contains_key("exception.details"));
+        assert!(!fields.contains_key("sqlpage.exception.details"));
     }
 
     #[test]
@@ -918,7 +923,7 @@ mod tests {
                 "db.query",
                 otel.status_code = tracing::field::Empty,
                 exception.message = tracing::field::Empty,
-                exception.details = tracing::field::Empty,
+                sqlpage.exception.details = tracing::field::Empty,
                 db.response.returned_rows = tracing::field::Empty,
             );
             let error = anyhow!("query failed").context("while executing SELECT 1");
@@ -932,6 +937,6 @@ mod tests {
         assert_eq!(fields[otel::OTEL_STATUS_CODE], "ERROR");
         assert_eq!(fields[otel::DB_RESPONSE_RETURNED_ROWS], "2");
         assert!(fields[otel::EXCEPTION_MESSAGE].contains("while executing SELECT 1"));
-        assert!(fields["exception.details"].contains("query failed"));
+        assert!(fields["sqlpage.exception.details"].contains("query failed"));
     }
 }
diff --git a/src/webserver/http.rs b/src/webserver/http.rs
@@ -241,7 +241,7 @@ async fn render_sql(
         let parse_span = tracing::info_span!(
             "http.parse_request",
             http.request.method = %srv_req.method(),
-            http.request.header.content_type = content_type,
+            "http.request.header.content-type" = content_type,
             http.request.body.size = content_length,
             url.query = url_query,
         );
@@ -359,7 +359,7 @@ impl RootSpanBuilder for SqlPageRootSpanBuilder {
             { otel::OTEL_STATUS_CODE } = tracing::field::Empty,
             request_id = %request_id,
             { otel::EXCEPTION_MESSAGE } = tracing::field::Empty,
-            "exception.details" = tracing::field::Empty,
+            "sqlpage.exception.details" = tracing::field::Empty,
         );
         std::mem::drop(connection_info);
         tracing_actix_web::root_span_macro::private::set_otel_parent(request, &span);

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ http {`
`20`	`20`	`}`
`21`	`21`
`22`	`22`	`log_format otel_request 'ts=$time_iso8601 level=$log_level target=$log_target '`
`23`		`- 'client_ip=$remote_addr method=$request_method path="$uri" '`
	`23`	`+ 'client.address=$remote_addr method=$request_method path="$uri" '`
`24`	`24`	`'status=$status request_time=$request_time '`
`25`	`25`	`'connection=$connection '`
`26`	`26`	`'upstream_addr="$upstream_addr" upstream_status="$upstream_status" '`